README

警告我们已决定停止维护此包。

请考虑迁移到 spatie/laravel-data 或 cuyz/valinor。

请随意复制我们的代码并适应您的需求。

自带电池的数据传输对象

安装

您可以通过composer安装此包

composer require spatie/data-transfer-object

注意：此包的v3版本仅支持 php:^8.0。如果您需要旧版本，请查看 v2。

支持我们

我们投入了大量资源创建最佳的开源包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡给我们寄来明信片，提及您正在使用我们的哪个包。您可以在我们的联系页面上找到我们的地址。我们将所有收到的明信片发布在我们的虚拟明信片墙上。

用法

此包的目标是使从（序列化的）数据数组构建对象尽可能简单。以下是一个DTO的例子

use Spatie\DataTransferObject\Attributes\MapFrom;
use Spatie\DataTransferObject\DataTransferObject;

class MyDTO extends DataTransferObject
{
    public OtherDTO $otherDTO;
    
    public OtherDTOCollection $collection;
    
    #[CastWith(ComplexObjectCaster::class)]
    public ComplexObject $complexObject;
    
    public ComplexObjectWithCast $complexObjectWithCast;
    
    #[NumberBetween(1, 100)]
    public int $a;
    
    #[MapFrom('address.city')]
    public string $city;
}

您可以这样构建DTO

$dto = new MyDTO(
    a: 5,
    collection: [
        ['id' => 1],
        ['id' => 2],
        ['id' => 3],
    ],
    complexObject: [
        'name' => 'test',
    ],
    complexObjectWithCast: [
        'name' => 'test',
    ],
    otherDTO: ['id' => 5],
);

让我们逐一讨论所有可能性。

命名参数

可以使用命名参数来构建DTO。仍然可以继续使用旧的数组表示法。此示例与上面的示例等效。

$dto = new MyDTO([
    'a' => 5,
    'collection' => [
        ['id' => 1],
        ['id' => 2],
        ['id' => 3],
    ],
    'complexObject' => [
        'name' => 'test',
    ],
    'complexObjectWithCast' => [
        'name' => 'test',
    ],
    'otherDTO' => ['id' => 5],
]);

值转换

如果DTO具有另一个DTO或DTO集合的属性，则包将自动将数据数组的数组转换为这些DTO

$dto = new MyDTO(
    collection: [ // This will become an object of class OtherDTOCollection
        ['id' => 1],
        ['id' => 2], // Each item will be an instance of OtherDTO
        ['id' => 3],
    ],
    otherDTO: ['id' => 5], // This data will be cast to OtherDTO
);

自定义转换器

您可以构建自己的转换器类，这些类将接受它们接收的任何输入，并将该输入转换为目标结果。

看看 ComplexObject

class ComplexObject
{
    public string $name;
}

及其转换器 ComplexObjectCaster

use Spatie\DataTransferObject\Caster;

class ComplexObjectCaster implements Caster
{
    /**
     * @param array|mixed $value
     *
     * @return mixed
     */
    public function cast(mixed $value): ComplexObject
    {
        return new ComplexObject(
            name: $value['name']
        );
    }
}

类特定的转换器

除了为每个属性指定应使用的转换器外，您还可以在目标类本身上定义该转换器

class MyDTO extends DataTransferObject
{
    public ComplexObjectWithCast $complexObjectWithCast;
}

#[CastWith(ComplexObjectWithCastCaster::class)]
class ComplexObjectWithCast
{
    public string $name;
}

默认转换器

可以在DTO类本身上定义默认转换器。这些转换器将在DTO类中遇到给定类型的属性时使用。

#[
    DefaultCast(DateTimeImmutable::class, DateTimeImmutableCaster::class),
    DefaultCast(MyEnum::class, EnumCaster::class),
]
abstract class BaseDataTransferObject extends DataTransferObject
{
    public MyEnum $status; // EnumCaster will be used
    
    public DateTimeImmutable $date; // DateTimeImmutableCaster will be used
}

使用自定义转换器参数

任何转换器都可以传递自定义参数，内置的 ArrayCaster 实现是如何使用此功能的良好示例。

在将输入传递给您的转换器时使用命名参数可以帮助使您的代码更清晰，但它们不是必需的。

例如

    /** @var \Spatie\DataTransferObject\Tests\Foo[] */
    #[CastWith(ArrayCaster::class, itemType: Foo::class)]
    public array $collectionWithNamedArguments;
    
    /** @var \Spatie\DataTransferObject\Tests\Foo[] */
    #[CastWith(ArrayCaster::class, Foo::class)]
    public array $collectionWithoutNamedArguments;

请注意，传递给转换器构造函数的第一个参数始终是要转换的值的类型（s）的数组。所有其他参数都将作为 CastWith 属性中传递的额外参数。

验证

此包不提供任何特定的验证功能，但它确实提供了一种方式来构建自己的验证属性。例如，NumberBetween 是用户实现的验证属性

class MyDTO extends DataTransferObject
{
    #[NumberBetween(1, 100)]
    public int $a;
}

其底层工作原理如下

#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
class NumberBetween implements Validator
{
    public function __construct(
        private int $min,
        private int $max
    ) {
    }

    public function validate(mixed $value): ValidationResult
    {
        if ($value < $this->min) {
            return ValidationResult::invalid("Value should be greater than or equal to {$this->min}");
        }

        if ($value > $this->max) {
            return ValidationResult::invalid("Value should be less than or equal to {$this->max}");
        }

        return ValidationResult::valid();
    }
}

映射

您可以使用 #[MapFrom] 属性将源属性的属性映射到 DTO 属性。

它可以与使用“点”表示法命名的属性或索引一起使用。

class PostDTO extends DataTransferObject
{
    #[MapFrom('postTitle')]
    public string $title;
    
    #[MapFrom('user.name')]
    public string $author;
}

$dto = new PostDTO([
    'postTitle' => 'Hello world',
    'user' => [
        'name' => 'John Doe'
    ]
]);

class UserDTO extends DataTransferObject
{

    #[MapFrom(0)]
    public string $firstName;
    
    #[MapFrom(1)]
    public string $lastName;
}

$dto = new UserDTO(['John', 'Doe']);

有时您也希望在转换为数组时进行映射。一个典型的用例是将驼峰式命名转换为蛇形命名。为此，您可以使用 #[MapTo] 属性。

class UserDTO extends DataTransferObject
{

    #[MapFrom(0)]
    #[MapTo('first_name')]
    public string $firstName;
    
    #[MapFrom(1)]
    #[MapTo('last_name')]
    public string $lastName;
}

$dto = new UserDTO(['John', 'Doe']);
$dto->toArray() // ['first_name' => 'John', 'last_name'=> 'Doe'];
$dto->only('first_name')->toArray() // ['first_name' => 'John'];

严格的 DTO

此包的先前版本添加了 FlexibleDataTransferObject 类，允许您忽略 DTO 中不存在的属性。但这种行为已被更改，现在所有 DTO 默认都是灵活的，但您可以使用 #[Strict] 属性使它们变得严格。

class NonStrictDto extends DataTransferObject
{
    public string $name;
}

// This works
new NonStrictDto(
    name: 'name',
    unknown: 'unknown'
);

use \Spatie\DataTransferObject\Attributes\Strict;

#[Strict]
class StrictDto extends DataTransferObject
{
    public string $name;
}

// This throws a \Spatie\DataTransferObject\Exceptions\UnknownProperties exception
new StrictDto(
    name: 'name',
    unknown: 'unknown'
);

辅助函数

还提供了一些辅助函数，用于一次处理多个属性。

$postData->all();

$postData
    ->only('title', 'body')
    ->toArray();
    
$postData
    ->except('author')
    ->toArray();

请注意，all() 将简单地返回所有属性，而 toArray() 将将嵌套 DTO 转换为数组。

您可以链式调用 except() 和 only() 方法。

$postData
    ->except('title')
    ->except('body')
    ->toArray();

请注意，except() 和 only() 是不可变的，它们不会更改原始的数据传输对象。

不可变 DTO 和克隆

由于 PHP 不支持不可变对象，因此此包不强制使用不可变对象，但您始终被鼓励保持您的 DTO 不可变。为了帮助您，每个 DTO 上都有一个 clone 方法，该方法接受要覆盖的数据。

$clone = $original->clone(other: ['name' => 'a']);

请注意，$original 中的数据没有更改。

DTO 集合

此版本删除了 DataTransferObjectCollection 类。相反，您可以使用简单的转换器和您自己的集合类。

以下是将 DTO 集合转换为 DTO 数组的示例

class Bar extends DataTransferObject
{
    /** @var \Spatie\DataTransferObject\Tests\Foo[] */
    #[CastWith(FooArrayCaster::class)]
    public array $collectionOfFoo;
}

class Foo extends DataTransferObject
{
    public string $name;
}

class FooArrayCaster implements Caster
{
    public function cast(mixed $value): array
    {
        if (! is_array($value)) {
            throw new Exception("Can only cast arrays to Foo");
        }

        return array_map(
            fn (array $data) => new Foo(...$data),
            $value
        );
    }
}

如果您不想使用冗余的类型提示，或想要扩展集合功能，则可以创建自己的集合类，使用任何集合实现。在这个例子中，我们使用了 Laravel 的。

class Bar extends DataTransferObject
{
    #[CastWith(FooCollectionCaster::class)]
    public CollectionOfFoo $collectionOfFoo;
}

class Foo extends DataTransferObject
{
    public string $name;
}

use Illuminate\Support\Collection;

class CollectionOfFoo extends Collection
{
    // Add the correct return type here for static analyzers to know which type of array this is 
    public function offsetGet($key): Foo
    {
        return parent::offsetGet($key);
    }
}

class FooCollectionCaster implements Caster
{
    public function cast(mixed $value): CollectionOfFoo
    {
        return new CollectionOfFoo(array_map(
            fn (array $data) => new Foo(...$data),
            $value
        ));
    }
}

简单的 DTO 数组

对于简单的 DTO 数组，或者实现了 PHP 内置的 ArrayAccess 的对象，请考虑使用 ArrayCaster，它需要一个项目类型。

class Bar extends DataTransferObject
{
    /** @var \Spatie\DataTransferObject\Tests\Foo[] */
    #[CastWith(ArrayCaster::class, itemType: Foo::class)]
    public array $collectionOfFoo;
}

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献。

安全

如果您发现有关安全性的错误，请通过security@spatie.be 发送电子邮件，而不是使用问题跟踪器。

Postcardware

您可以使用此包，但如果它进入您的生产环境，我们非常感谢您从您家乡寄给我们一张明信片，说明您正在使用我们哪个包。

我们的地址是：Spatie，Kruikstraat 22，2018 安特卫普，比利时。

我们在我们的公司网站上发布所有收到的明信片在这里。

外部工具

json2dto：将 JSON 对象转换为 DTO 类的图形界面（支持嵌套）。还提供CLI 工具以供本地使用。
数据传输对象工厂：智能生成 DTO 实例，根据属性名称和类型使用正确的内容。

致谢

我们的 Arr 类包含从 Laravel 的 Arr 辅助程序复制的函数。

许可证

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

m1services / data-transfer-object

维护者

详细信息