★ Data Transfer Object v3 has been released

We’ve released a new major version of spatie/data-transfer-object. This package makes it easy to create objects that have a certain shape. Properties can even be validated.

🐘 Need self-validating PHP objects? Here you go!https://t.co/osPCSr0qu8

Gotta love PHP 8

Very nice work by @brendt_gd pic.twitter.com/Sn1mS7R8Sv

— Freek Van der Herten 🎆 (@freekmurze) April 2, 2021

In this post I’d like to tell you more the package.

A modern package to construct data transfer objects #

When we original released the data-transfer-object package, it was meant to solve four problems:

• Runtime type checks for class properties
• Support for union types
• Support for array types (these are not full blown generics!)
• Named arguments

Typed properties are added in PHP 7.4, and union types and named arguments in PHP 8. So now that PHP 8 has been released, it makes sense that we leverage PHP’s native type check abilities.

The renewed goal of our package is to make constructing objects from arrays of (serialized) data as easy as possible. Here’s what a DTO looks like:

<span class="hljs-keyword">use</span> <span class="hljs-title">Spatie</span><span class="hljs-title">DataTransferObject</span><span class="hljs-title">DataTransferObject</span>;
<p><span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyDTO</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">DataTransferObject</span>
</span>{
<span class="hljs-keyword">public</span> OtherDTO $otherDTO;</p>
<pre><code><span class="hljs-keyword">public</span> OtherDTOCollection $collection;

<span class="hljs-comment">#[CastWith(ComplexObjectCaster::class)]</span>
<span class="hljs-keyword">public</span> ComplexObject $complexObject;

<span class="hljs-keyword">public</span> ComplexObjectWithCast $complexObjectWithCast;

<span class="hljs-comment">#[NumberBetween(1, 100)]</span>
<span class="hljs-keyword">public</span> int $a;

}

You could construct this DTO like so:

$dto = <span class="hljs-keyword">new</span> MyDTO(
a: <span class="hljs-number">5</span>,
collection: [
[<span class="hljs-string">'id'</span> => <span class="hljs-number">1</span>],
[<span class="hljs-string">'id'</span> => <span class="hljs-number">2</span>],
[<span class="hljs-string">'id'</span> => <span class="hljs-number">3</span>],
],
complexObject: [
<span class="hljs-string">'name'</span> => <span class="hljs-string">'test'</span>,
],
complexObjectWithCast: [
<span class="hljs-string">'name'</span> => <span class="hljs-string">'test'</span>,
],
otherDTO: [<span class="hljs-string">'id'</span> => <span class="hljs-number">5</span>],
);

Let’s discuss all possibilities one by one.

Named arguments #

Constructing a DTO can be done with named arguments. It’s also possible to still use the old array notation. This example is equivalent to the one above.

$dto = <span class="hljs-keyword">new</span> MyDTO([
<span class="hljs-string">'a'</span> => <span class="hljs-number">5</span>,
<span class="hljs-string">'collection'</span> => [
[<span class="hljs-string">'id'</span> => <span class="hljs-number">1</span>],
[<span class="hljs-string">'id'</span> => <span class="hljs-number">2</span>],
[<span class="hljs-string">'id'</span> => <span class="hljs-number">3</span>],
],
<span class="hljs-string">'complexObject'</span> => [
<span class="hljs-string">'name'</span> => <span class="hljs-string">'test'</span>,
],
<span class="hljs-string">'complexObjectWithCast'</span> => [
<span class="hljs-string">'name'</span> => <span class="hljs-string">'test'</span>,
],
<span class="hljs-string">'otherDTO'</span> => [<span class="hljs-string">'id'</span> => <span class="hljs-number">5</span>],
]);

Value casts #

If a DTO has a property that is another DTO or a DTO collection, the package will take care of automatically casting arrays of data to those DTOs:

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

Custom casters #

You can build your own caster classes, which will take whatever input they are given, and will cast that input to the desired result.

Take a look at the ComplexObject:

<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">ComplexObject</span>
</span>{
<span class="hljs-keyword">public</span> string $name;
}

And its caster ComplexObjectCaster:

<span class="hljs-keyword">use</span> <span class="hljs-title">Spatie</span><span class="hljs-title">DataTransferObject<span class="hljs-title">Caster;
<p><span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">ComplexObjectCaster</span> <span class="hljs-keyword">implements</span> <span class="hljs-title">Caster</span>
</span>{
<span class="hljs-comment">/**
* <span class="hljs-doctag">@param</span> array|mixed $value
*
* <span class="hljs-doctag">@return</span> mixed
*/</span>
<span class="hljs-keyword">public</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">cast</span><span class="hljs-params">(mixed $value)</span>: <span class="hljs-title">ComplexObject</span>
</span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> ComplexObject(
name: $value[<span class="hljs-string">'name'</span>]
);
}
}
</p>

Class-specific casters #

Instead of specifying which caster should be used for each property, you can also define that caster on the target class itself:

<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyDTO</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">DataTransferObject</span>
</span>{
<span class="hljs-keyword">public</span> ComplexObjectWithCast $complexObjectWithCast;
}

<span class="hljs-comment">#[CastWith(ComplexObjectWithCastCaster::class)]</span>
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">ComplexObjectWithCast</span>
</span>{
<span class="hljs-keyword">public</span> string $name;
}

Default casters #

It’s possible to define default casters on a DTO class itself. These casters will be used whenever a property with a given type is encountered within the DTO class.

<span class="hljs-comment">#[</span>
DefaultCast(DateTimeImmutable::class, DateTimeImmutableCaster::class),
DefaultCast(Enum::class, EnumCaster::class),
]
<span class="hljs-keyword">abstract</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">BaseDataTransferObject</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">DataTransferObject</span>
</span>{
<span class="hljs-keyword">public</span> MyEnum $status; <span class="hljs-comment">// EnumCaster will be used</span>
<pre><code><span class="hljs-keyword">public</span> DateTimeImmutable $date; <span class="hljs-comment">// DateTimeImmutableCaster will be used</span>

}

Validation #

This package doesn’t offer any specific validation functionality, but it does give you a way to build your own validation attributes. For example, NumberBetween is a user-implemented validation attribute:

<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyDTO</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">DataTransferObject</span>
</span>{
<span class="hljs-comment">#[NumberBetween(1, 100)]</span>
<span class="hljs-keyword">public</span> int $a;
}

It works like this under the hood:

<span class="hljs-comment">#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]</span>
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">NumberBetween</span> <span class="hljs-keyword">implements</span> <span class="hljs-title">Validator</span>
</span>{
<span class="hljs-keyword">public</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">__construct</span><span class="hljs-params">(
private int $min,
private int $max
)</span> </span>{
}
<pre><code><span class="hljs-keyword">public</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">validate</span><span class="hljs-params">(mixed $value)</span>: <span class="hljs-title">ValidationResult</span>
</span>{
    <span class="hljs-keyword">if</span> ($value &lt; <span class="hljs-keyword">$this</span>-&gt;min) {
        <span class="hljs-keyword">return</span> ValidationResult::invalid(<span class="hljs-string">"Value should be greater than or equal to {$this-&gt;min}"</span>);
    }

    <span class="hljs-keyword">if</span> ($value &gt; <span class="hljs-keyword">$this</span>-&gt;max) {
        <span class="hljs-keyword">return</span> ValidationResult::invalid(<span class="hljs-string">"Value should be less than or equal to {$this-&gt;max}"</span>);
    }

    <span class="hljs-keyword">return</span> ValidationResult::valid();
}

}

In closing #

We use spatie/data-transfer-object in our bigger projects. We hope that this package can be handy for you as well. The package has a few more features, to learn them, head over to the readme on GitHub.

The principal author of this package is my colleague Brent, who, like always, did an excellent job.

Want to see more packages that our team has created? Head over to the open source section on spatie.be