README

SimpleDTO 是 PHP Experts, Inc. 的项目，旨在简化数据传输对象 (DTO)。

基本上，DTO 上的任何受保护属性都可以作为传入到 __constructor 的数组元素或属性本身的默认值设置。

DTO 是不可变的：一旦创建，就不能更改。请创建一个新的对象。

安装

通过 Composer

composer require phpexperts/simple-dto

使用方法

从版本 2 开始，你必须为每个属性定义类级别的 @property docblocks。

你还必须定义数据类型。

use Carbon\Carbon;
use PHPExperts\SimpleDTO\SimpleDTO;

/**
 * @property-read string $name
 * @property-read Carbon $name
 */
class BirthdayDTO extends SimpleDTO
{
    /** @var string */
    protected $name;
    
    /** @var Carbon */
    protected $date;
}

$birthdayDTO = new BirthdayDTO([
    'name' => 'Donald J. Trump',
    'date' => '1946-06-14',
]);

// Access as a property:
echo $birthday->name; // Donald J. Trump

// Properties with the data type of "Carbon" or "Carbon\Carbon" 
// are automagically converted to Carbon objects.
echo $birthday->date->format('F jS, Y'); // June 14th, 1946

// Easily output as an array:
$birthday->toArray();

// Copy from one to another:
$newDTO = new BirthdayDTO($birthdayDTO->toArray());

// Copy from one to another, with new properties:
$newDTO = new BirthdayDTO($birthdayDTO->toArray() + [
    'date' => '2020-11-03',
]);

// Easily output as JSON:
echo json_encode($birthdayDTO);
/* Output: 
{
    "name": "Donald J. Trump",
    "date": "1946-06-14T00:00:00.000000Z"
}
*/

模糊数据类型

但如果你还没有准备好/能够深入到严格的 PHP 数据类型呢？

那么，只需像这样实例化父类即可

    use PHPExperts\DataTypeValidator\DataTypeValidator;
    use PHPExperts\DataTypeValidator\IsAFuzzyDataType;
    
    /**
     * @property int   $daysAlive
     * @property float $age
     * @property bool  $isHappy
     */
    class MyFuzzyDTO extends SimpleDTO
    {
        public function __construct(array $input)
        {
            parent::__construct($input, new DataTypeValidator(new IsAFuzzyDataType());
        }
    }

    $person = new MyFuzzyDTO([
        'daysAlive' => '5000',
        'age'       => '13.689',
        'isHappy'   => 1,
    ]);

    echo json_encode($person, JSON_PRETTY_PRINT);
    /*
    {
        "daysAlive": "5000",
        "age": "13.689",
        "isHappy": 1
    }
    */

嵌套 DTO

你可以在彼此内部嵌套 DTO。

    $myDTO = new MyTestDTO([
        'name' => 'PHP Experts, Inc.',
        'age'  => 7.01,
        'year' => 2019,
    ]);

    /**
     * @property MyTestDTO $myDTO
     */
    $dto = new class(['myDTO' => $myDTO], ['myDTO' => MyTestDTO::class]) extends NestedDTO
    {
    };
    
    /*
    PHPExperts\SimpleDTO\NestedDTO@anonymous {
      -dataTypeRules: array:1 [
        "myDTO" => "?MyTestDTO"
      ]
      -data: array:1 [
        "myDTO" => PHPExperts\SimpleDTO\Tests\MyTestDTO {#355
          -dataTypeRules: array:3 [
            "name" => "?string"
            "age" => "?float"
            "year" => "?int"
          ]
          -data: array:3 [
            "name" => "PHP Experts, Inc."
            "age" => 7.01
            "year" => 2019
          ]
        }
      ]
    }
    */

用例

PHPExperts\SimpleDTO\SimpleDTO
✔ 属性通过构造函数设置
✔ 属性作为公共属性访问
✔ 公共、私有和静态受保护属性将被忽略
✔ 每个DTO都是不可变的
✔ 设置任何属性都会抛出异常
✔ 可以使用具体属性来设置默认值
✔ 类型为 carbon 的属性将成为 carbon 日期
✔ 可以轻松输出到数组
✔ 可以轻松地进行 json 编码
✔ 可以轻松地进行 json 解码
✔ 允许可空属性
✔ 在宽松模式下，每个属性都是可空的
✔ 可以序列化
✔ 可以反序列化
✔ 可以添加额外的验证

PHPExperts\SimpleDTO\NestedDTO
✔ 将构造嵌套 DTO
✔ 可以构造嵌套 DTO 的数组
✔ 将数组转换为适当的嵌套 DTO
✔ 将 stdClasses 转换为适当的嵌套 DTO
✔ 嵌套 DTO 使用宽松类型
✔ 所有注册的嵌套 DTO 都是必需的
✔ 可选的、未注册的嵌套 DTO 将被优雅地处理
✔ 可以序列化
✔ 可以反序列化

PHPExperts\SimpleDTO\WriteOnceTrait
✔ 可以接受 null 值
✔ 在序列化时进行验证
✔ 在转换为数组时进行验证
✔ 可以写每个 null 值一次
✔ 写一次的值必须验证

SimpleDTO 令人悲伤的路径
✔ 不能使用不存在的属性进行初始化
✔ 访问不存在的属性会抛出错误
✔ DTO 必须为每个具体属性有类属性 docblocks
✔ Carbon 日期字符串必须是可解析的日期
✔ 属性必须匹配其数据类型
✔ 不会反序列化包含无效数据的 DTO
✔ 不能覆盖不存在的属性

测试

phpunit --testdox

贡献者

Theodore R. Smith theodore@phpexperts.pro
GPG 指纹: 4BF8 2613 1C34 87AC D28F 2AD8 EB24 A91D D612 5690
CEO: PHP Experts, Inc.

许可证

MIT 许可证。有关更多信息，请参阅 许可证文件。