I'm currently organising the third edition Full Stack Europe. It's a conference in Antwerp, Belgium in October for developers who want to learn across the stack. We have a great line up with lots of familiar faces! Register your ticket now!

Data Transfer Object v3 has been released

Original – by Brent Roose and Freek Van der Herten – 4 minute read

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.

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 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;
}

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\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-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
    
    public DateTimeImmutable $date; // DateTimeImmutableCaster will be used
}

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
    ) {
    }

    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();
    }
}

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

Stay up to date with all things Laravel, PHP, and JavaScript.

You can follow me on these platforms:

On all these platforms, regularly share programming tips, and what I myself have learned in ongoing projects.

Every month I send out a newsletter containing lots of interesting stuff for the modern PHP developer.

Expect quick tips & tricks, interesting tutorials, opinions and packages. Because I work with Laravel every day there is an emphasis on that framework.

Rest assured that I will only use your email address to send you the newsletter and will not use it for any other purposes.

Comments

What are your thoughts on "Data Transfer Object v3 has been released"?

Comments powered by Laravel Comments
Want to join the conversation? Log in or create an account to post a comment.

Webmentions

Gaurav Makhecha liked on 10th April 2021
Joan Masó liked on 9th April 2021
Jens liked on 8th April 2021
Adam Skinner liked on 8th April 2021
J.O.Y liked on 8th April 2021
Simon Blonér liked on 8th April 2021
Stefan Riehl liked on 8th April 2021
devzaim replied on 8th April 2021
Hi, pretty new with in this industry. Does this package is similar to native 'interface' that requires an object to comply to the 'shape' and properties of an interface?
Ashish Dhamala liked on 8th April 2021
ali ali liked on 8th April 2021
Ruslan liked on 8th April 2021
Tauseef shah liked on 8th April 2021
MasDan retweeted on 8th April 2021
Romain Filinto liked on 8th April 2021
Romain Filinto retweeted on 8th April 2021
Mark Topper liked on 8th April 2021
Bajram Emini liked on 8th April 2021
Etienne liked on 8th April 2021
SouthDreamz liked on 8th April 2021
Manuk Minasyan liked on 8th April 2021
Matteo Mangoni replied on 8th April 2021
Will definitely take a closer look in the coming days, looks awesome!
Matteo Mangoni retweeted on 8th April 2021
Matteo Mangoni liked on 8th April 2021
Ernest Chiang liked on 8th April 2021
Ken V. liked on 8th April 2021
Karel retweeted on 8th April 2021
Karel liked on 8th April 2021
Victor Dauchy replied on 8th April 2021
On my toUse list... Either when spatie-settings support it, or when I have the time to PR to it ^^
Victor Dauchy liked on 8th April 2021
Jamie York liked on 8th April 2021
Sid liked on 8th April 2021
Daragh O'Shea replied on 8th April 2021
Great package. Especially when used with @jessarchercodes castable DTO extension for Models
Jack at SYD1 liked on 8th April 2021
Vitor Hugo R liked on 8th April 2021
Sebastian Fix liked on 8th April 2021
Tim MacDonald replied on 8th April 2021
Can confirm. Do like!
Paul Redmond 🇺🇸 replied on 8th April 2021
Thank you, this is one of my favorite packages! 🏩
Robert van Steen liked on 8th April 2021
Paul Redmond 🇺🇸 liked on 8th April 2021
Joachim Løvgaard replied on 7th April 2021
Use it all the time. Will have to send a post card soon. Thank you ❤️
Richard van Baarsen liked on 7th April 2021
Shafqat ali liked on 7th April 2021
Mike liked on 7th April 2021
Travis Elkins liked on 7th April 2021
Santosh Khanal liked on 7th April 2021
Jorge González liked on 7th April 2021
فرودو liked on 7th April 2021
Calefyb retweeted on 7th April 2021
Osmar Alves retweeted on 7th April 2021
Web Code retweeted on 7th April 2021
ReynierPM retweeted on 7th April 2021
José Cage retweeted on 7th April 2021
Andrii Kuzo liked on 7th April 2021
_D_ liked on 7th April 2021
Web Code liked on 7th April 2021
José Cage liked on 7th April 2021
Ξlliott Lawson liked on 7th April 2021
Roy Shay liked on 7th April 2021
Miten Patel liked on 7th April 2021
Osmar Alves liked on 7th April 2021
Sven liked on 7th April 2021