README

Note

Even though most of the codebase has been rewritten entirely. This project was originally forked from (https://github.com/spatie/data-transfer-object). The base repository is still maintained by spatie (https://github.com/spatie). Our goal is to increase the performance (mostly through caching of the reflection properties) and improve this package with additional features (see more below).

Improvements:

Improved immutability.
Reflection property & annotation caching (for improved performance).
Fully qualified name resolving.
Immutable properties (through annotations).
Validation (through annotations).
Overriding & adding properties.
Optional property support.
Annotation/validation inheritance.

Installation

You can install the package via composer:

composer require larapie/data-transfer-object

Have you ever…

… worked with an array of data, retrieved from a request, a CSV file or a JSON API; and wondered what was in it?

Here's an example:

public function handleRequest(array $dataFromRequest)
{
    $dataFromRequest[/* what to do now?? */];
}

The goal of this package is to structure "unstructured data", which is normally stored in associative arrays. By structuring this data into an object, we gain several advantages:

We're able to type hint data transfer objects, instead of just calling them array.
By making all properties on our objects typeable, we're sure that their values are never something we didn't expect.
Because of typed properties, we can statically analyze them and have auto completion.

Let's look at the example of a JSON API call:

$post = $api->get('posts', 1); 

[
    'title' => '…',
    'body' => '…',
    'author_id' => '…',
]

Working with this array is difficult, as we'll always have to refer to the documentation to know what's exactly in it. This package allows you to create data transfer object definitions, classes, which will represent the data in a structured way.

We did our best to keep the syntax and overhead as little as possible:

class PostData extends DataTransferObject
{
    /** @var string */
    public $title;
    
    /** @var string */
    public $body;
    
    /** @var \Author */
    public $author;
}

An object of PostData can from now on be constructed like so:

$postData = new PostData([
    'title' => '…',
    'body' => '…',
    'author_id' => '…',
]);

Now you can use this data in a structured way:

$postData->title;
$postData->body;
$postData->author_id;

It's, of course, possible to add static constructors to PostData:

class PostData extends DataTransferObject
{
    // …
    
    public static function fromRequest(Request $request): self
    {
        return new self([
            'title' => $request->get('title'),
            'body' => $request->get('body'),
            'author' => Author::find($request->get('author_id')),
        ]);
    }
}

By adding doc blocks to our properties, their values will be validated against the given type; and a TypeError will be thrown if the value doesn't comply with the given type.

Here are the possible ways of declaring types:

class PostData extends DataTransferObject
{
    /**
     * Built in types: 
     *
     * @var string 
     */
    public $property;
    
    /**
     * Classes with their FQCN: 
     *
     * @var \App\Models\Author
     */
    public $property;
    
    /**
     * Lists of types: 
     *
     * @var \App\Models\Author[]
     */
    public $property;
    
    /**
     * Union types: 
     *
     * @var string|int
     */
    public $property;
    
    /**
     * Nullable types: 
     *
     * @var string|null
     */
    public $property;
    
    /**
     * Mixed types: 
     *
     * @var mixed|null
     */
    public $property;
    
    /**
     * No type, which allows everything
     */
    public $property;
}

When PHP 7.4 introduces typed properties, you'll be able to simply remove the doc blocks and type the properties with the new, built-in syntax.

Immutability

If you want your data object to be never changeable (this is a good idea in some cases), you can make it immutable:

class PostData extends DataTransferObject
{
    use MakeImmutable;
    
    /** @var string */
    public $name;
}

If you only want to make a certain property immutable you can annotate this on the variable.

class PostData extends DataTransferObject
{
    /**
     * @Immutable
     * @var string $name
     */
    public $name;
}

Trying to change a property of $postData after it's constructed, will result in a ImmutableDtoException.

Optional Properties

By default all dto properties are required. If you want to make certain properties on the dto optional:

class PostData extends DataTransferObject
{
    /**
     * @Optional
     * @var string $name
     */
    public $name;
}

Note

The default value will NOT be set when a property is annotated as optional!

Additional Properties

By default only dto properties can be set on the dto. Attempting to input data that is not declared as a public property on the dto will throw a UnknownPropertiesDtoException. If you want to allow additional properties you can do so by implementing the AdditionalProperties or WithAdditionalProperties interface.

AdditionalProperties:

class PostData extends DataTransferObject implements AdditionalProperties
{
    /**
     * @var string $name
     */
    public $name;
}

$dto = new PostData(["name" => "foo", "address" => "bar"]);
$dto->toArray();

returns:
["name" => "foo"]

WithAdditionalProperties:

class PostData extends DataTransferObject implements WithAdditionalProperties
{
    /**
     * @var string $name
     */
    public $name;
}

$dto = new PostData(["name" => "foo", "address" => "bar"]);
$dto->toArray();

returns:
["name" => "foo", "address" => "bar"]

Overriding & Adding Properties

If you want to add or override a certain value on the dto you can do it as follows:

Adding Data:

    public function create(PostData $data, User $user)
    {
        $data->with('user_id', $user->id);
        return $this->repository->create($data->toArray());
    }

Overriding Property:

    public function create(PostData $data, User $user)
    {
        if($this->user->isAdmin()){
            $data->override('name', 'admin');
        }
        $data->with('user_id', $user->id);
        return $this->repository->create($data->toArray());
    }

Notes:

You cannot add or override data on an immutable dto. You also can't override immutable properties.
You cannot use the with method to add properties that are declared as public properties on the dto.

Validation

Constraints

If you want to validate the input of a property. You can do so through annotations.

class PostData extends DataTransferObject
{
    /**
     * @var string
     * @Assert\NotBlank()
     * @Assert\Length(min = 3, max = 20)
     */
    public $name;
}

Inheritence

If you want to extend a dto and add extra constraints or the optional annotation you can do so by adding the Inherit annotation. This will merge all existing constraints from the parent class. If no type is specified on the current class it will also inherit the type of the parent dto.

class UpdatePostData extends PostData
{
    /**
     * @Optional
     * @Inherit
     */
    public $name;
}

Notes:

If you are using phpstorm you can install this plugin: https://plugins.jetbrains.com/plugin/7320-php-annotations to typehint the annotations.
The Optional annotation will not be inherited from the parent class. This is to ensure you always have a clear overview of what values are required in a dto.
Validation is NOT done upon constructing the object. But only when accessing the variables. This can be done through the magic __get method $dto->property or when outputting the values of the array through the toArray() or all() methods. You could also call the validate() method manually. If the dto is not valid it will throw a ValidatorException.
The ValidatorException message will include all the property names and the constraints that have failed on that specific property. For example: property 'author_name' is required.
To implement this functionality the excellent symfony\validation library was used. For more info please check https://symfony.com/doc/current/validation.html .

Working with collections

If you're working with collections of DTOs, you probably want auto completion and proper type validation on your collections too. This package adds a simple collection implementation, which you can extend from.

use \Spatie\DataTransferObject\DataTransferObjectCollection;

class PostCollection extends DataTransferObjectCollection
{
    public function current(): PostData
    {
        return parent::current();
    }
}

By overriding the current method, you'll get auto completion in your IDE, and use the collections like so.

foreach ($postCollection as $postData) {
    $postData-> // … your IDE will provide autocompletion.
}

$postCollection[0]-> // … and also here.

Of course you're free to implement your own static constructors:

class PostCollection extends DataTransferObjectCollection
{
    public static function create(array $data): PostCollection
    {
        $collection = [];

        foreach ($data as $item)
        {
            $collection[] = PostData::create($item);
        }

        return new self($collection);
    }
}

Automatic casting of nested DTOs

If you've got nested DTO fields, data passed to the parent DTO will automatically be casted.

class PostData extends DataTransferObject
{
    /** @var \AuthorData */
    public $author;
}

PostData can now be constructed like so:

$postData = new PostData([
    'author' => [
        'name' => 'Foo',
    ],
]);

Automatic casting of nested array DTOs

Similarly to above, nested array DTOs will automatically be casted.

class TagData extends DataTransferObject
{
    /** @var string */
   public $name;
}

class PostData extends DataTransferObject
{
    /** @var \TagData[] */
   public $tags;
}

PostData will automatically construct tags like such:

$postData = new PostData([
    'tags' => [
        ['name' => 'foo'],
        ['name' => 'bar']
    ]
]);

Helper functions

There are also some helper functions provided for working with multiple properties at once.

$postData->all();

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

You can also chain these methods:

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

It's important to note that except and only are immutable, they won't change the original data transfer object.

Exception handling

Beside property type validation, you can also be certain that the data transfer object in its whole is always valid. On outputting the data from a data transfer object (through the all() & toArray() methods and also when you access the properties of the dto e.g. $dto->name) , we'll validate whether all required properties are set, if the constraints are met and if each property is of the correct type. If not, a Larapie\DataTransferObject\Exceptions\ValidatorException will be thrown.

Likewise, if you're trying to set non-defined properties, you'll get a Larapie\DataTransferObject\Exceptions\UnknownPropertiesDtoException.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

License

The MIT License (MIT). Please see License File for more information.

larapie / data-transfer-object

Maintainers

Details

README

Note

Improvements:

Installation

Have you ever…

Immutability

Optional Properties

Note

Additional Properties

Overriding & Adding Properties

Notes:

Validation

Constraints

Inheritence

Notes:

Working with collections

Automatic casting of nested DTOs

Automatic casting of nested array DTOs

Helper functions

Exception handling

Testing

Changelog

Contributing

Credits

License