Month: April 2021

[AdSense-A]

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:

use SpatieDataTransferObjectDataTransferObject;
class MyDTO extends DataTransferObject
{
public OtherDTO $otherDTO;
<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 = new MyDTO(
a: 5,
collection: [
['id' => 1],
['id' => 2],
['id' => 3],
],
complexObject: [
'name' => 'test',
],
complexObjectWithCast: [
'name' => 'test',
],
otherDTO: ['id' => 5],
);

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 = new MyDTO([
'a' => 5,
'collection' => [
['id' => 1],
['id' => 2],
['id' => 3],
],
'complexObject' => [
'name' => 'test',
],
'complexObjectWithCast' => [
'name' => 'test',
],
'otherDTO' => ['id' => 5],
]);

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 = 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
);

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:

class ComplexObject
{
public string $name;
}

And its caster ComplexObjectCaster:

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

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:

class MyDTO extends DataTransferObject
{
public ComplexObjectWithCast $complexObjectWithCast;
}

#[CastWith(ComplexObjectWithCastCaster::class)]
class ComplexObjectWithCast
{
public 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.

#[
DefaultCast(DateTimeImmutable::class, DateTimeImmutableCaster::class),
DefaultCast(Enum::class, EnumCaster::class),
]
abstract class BaseDataTransferObject extends DataTransferObject
{
public MyEnum $status; // EnumCaster will be used
<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:

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

It works like this under the hood:

#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
class NumberBetween implements Validator
{
public function __construct(
private int $min,
private int $max
) {
}
<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

What Is Form Validation? Form validation is a process to check where the information provided by the user is met our requirements or not.That is provided data is in right format or not. Before Submitting Read more…