Download the PHP package larapie/data-transfer-object without Composer

Data transfer objects with validation through annotations

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:

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:

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:

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:

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

Now you can use this data in a structured way:

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

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:

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:

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

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:

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:

WithAdditionalProperties:

Overriding & Adding Properties

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

Adding Data:

Overriding Property:

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.

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.

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.

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

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

Automatic casting of nested DTOs

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

PostData can now be constructed like so:

Automatic casting of nested array DTOs

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

PostData will automatically construct tags like such:

Helper functions

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

You can also chain these methods:

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

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Credits

• Anthony Vancauwenberghe
• Brent Roose
• All Contributors

License

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