README

介绍

组件提供基本功能以安全地处理 DTO。接口和基本实现确保了记录在 DTO 中的数据的一致性，避免了其修改。组件基于 OptionsResolver 构建，并允许验证和规范化传递给 DTO 的数据。

安装

打开控制台，转到项目目录，然后执行以下命令以加载此组件的合适稳定版本

    composer require marfatech/dto-resolver

此命令假定已全局安装并可用 Composer。

使用

创建 DTO

<?php declare(strict_types=1);

namespace AcmeBundle\Dto;

use MarfaTech\Component\DtoResolver\Dto\DtoResolverTrait;
use MarfaTech\Component\DtoResolver\Dto\DtoResolverInterface;

class AcmeUserDto implements DtoResolverInterface
{
    use DtoResolverTrait;
    
    /**
     * @var string
     */
    protected $email;

    /**
     * @var string|null
     */
    protected $fullName = null;

    /**
     * @var string
     */
    protected $username;

    /**
     * @return string
     */
    public function getEmail(): string
    {
        return $this->email;
    }

    /**
     * @return string|null
     */
    public function getFullName(): ?string
    {
        return $this->fullName;
    }

    /**
     * @return string
     */
    public function getUsername(): string
    {
        return $this->username;
    }
}

填充 DTO 数据

<?php declare(strict_types=1);

$dto = new AcmeUserDto([
    'email' => 'test@gmail.com', 
    'username' => 'test_user', 
    'fullName' => 'Test User'
]);

echo $dto->getUsername(); // test_user
echo $dto->getEmail(); // test@gmail.com
echo $dto->getFullName(); // Test User

echo json_encode($dto); 
// {"email":"test@gmail.com","username":"test_user","fullName":"Test User"}

注意：组件的一个重要特点是自动规范化传入数组的键。即使传入的数组是 full-name 或 full_name 而不是 fullName，此方法也能正确填充您的 DTO 数据。

添加数据验证

<?php declare(strict_types=1);

namespace AcmeBundle\Dto;

use Symfony\Component\OptionsResolver\OptionsResolver;
use MarfaTech\Component\DtoResolver\Dto\DtoResolverInterface;
use MarfaTech\Component\DtoResolver\Dto\DtoResolverTrait;

class AcmeUserDto implements DtoResolverInterface
{
    use DtoResolverTrait;
    
    // ...
    
    /**
     * {@inheritdoc}
     */
    protected function configureOptions(OptionsResolver $options): void
    {
        $options->setRequired(['username']);
        $options->addAllowedTypes('email', ['string', 'null']);
        $options->addAllowedTypes('username', 'string');
    }
}

填充 DTO 数据

<?php declare(strict_types=1);

// ошибка: отсутвует обязательное смещение username
$entryDto = new AcmeUserDto([
    'email' => 'test@gmail.com'
]);

// ошибка: email имеет недопустимый тип
$entryDto = new AcmeUserDto([
    'email' => 123, 
    'username' => 'test_user'
]);

// успех
$entryDto = new AcmeUserDto([
    'email' => 'test@gmail.com', 
    'username' => 'test_user'
]);

echo $entryDto->getUsername(); // test_user
echo $entryDto->getEmail(); // test@gmail.com

使用 DTO 集合

<?php declare(strict_types=1);

namespace AcmeBundle\Dto;

use MarfaTech\Component\DtoResolver\Dto\CollectionDtoResolverTrait;
use MarfaTech\Component\DtoResolver\Dto\CollectionDtoResolverInterface;

class AcmeUserCollectionDto implements CollectionDtoResolverInterface
{
    use CollectionDtoResolverTrait;
    
    /**
     * {@inheritdoc}
     */
    public static function getItemDtoClassName(): string
    {
        return AcmeUserDto::class;
    }
}

填充 DTO 集合数据

<?php declare(strict_types=1);

/** @var \MarfaTech\Component\DtoResolver\Dto\CollectionDtoResolverInterface $collectionDto */
$collectionDto = new AcmeUserCollectionDto();
$collectionDto->add([
    'email' => '1_test@gmail.com',
    'username' => '1_test_user',
    'fullName' => '1 Test User'
]);
$collectionDto->add([
    'email' => '2_test@gmail.com',
    'username' => '2_test_user',
    'fullName' => '2 Test User'
]);

echo json_encode($collectionDto);
// [
//      {"email":"1_test@gmail.com","username":"1_test_user","fullName":"1 Test User"},
//      {"email":"2_test@gmail.com","username":"2_test_user","fullName":"2 Test User"}
// ]

其他

使用自定义 OptionResolver

如果您需要使用由第三方服务创建的 OptionResolver 对象，则可以使用构造函数。

<?php declare(strict_types=1);

$customResolver = new \Symfony\Component\OptionsResolver\OptionsResolver();
$entryDto = new AcmeUserDto(['email' => 'test@gmail.com'], $customResolver);
$collectionDto = new AcmeUserCollectionDto($customResolver);

按特定字段索引集合

要索引的字段由集合构造函数的第二个参数指定。

<?php declare(strict_types=1);

$collectionDto = new AcmeUserCollectionDto(null, 'email');
$collectionDto->add([
    'email' => '1_test@gmail.com',
     'username' => '1_test_user',
     'fullName' => '1 Test User'
 ]);
$collectionDto->add([
    'email' => '2_test@gmail.com',
    'username' => '2_test_user',
    'fullName' => '2 Test User'
]);

许可证