Download the PHP package spatie/value-object without Composer
On this page you can find all versions of the php package spatie/value-object. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download spatie/value-object
More information about spatie/value-object
Files in spatie/value-object
Package value-object
Short Description Data transfer objects with batteries included
License MIT
Homepage https://github.com/spatie/data-transfer-object
Informations about the package value-object
Warning We have decided to stop maintaining this package.
Consider migrating to spatie/laravel-data or cuyz/valinor.
Feel free to fork our code and adapt it to your needs.
Data transfer objects with batteries included
Installation
You can install the package via composer:
- Note: v3 of this package only supports
php:^8.0
. If you're looking for the older version, check out v2.
Support us
We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.
Usage
The goal of this package is to make constructing objects from arrays of (serialized) data as easy as possible. Here's what a DTO looks like:
You could construct this DTO like so:
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.
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:
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
:
And its caster ComplexObjectCaster
:
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:
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.
Using custom caster arguments
Any caster can be passed custom arguments, the built-in ArrayCaster
implementation is a good example of how this may be used.
Using named arguments when passing input to your caster will help make your code more clear, but they are not required.
For example:
Note that the first argument passed to the caster constructor is always the array with type(s) of the value being casted.
All other arguments will be the ones passed as extra arguments in the CastWith
attribute.
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:
It works like this under the hood:
Mapping
You can map a DTO property from a source property with a different name using the #[MapFrom]
attribute.
It works with a "dot" notation property name or an index.
Sometimes you also want to map them during the transformation to Array.
A typical usecase would be transformation from camel case to snake case.
For that you can use the #[MapTo]
attribute.
Strict DTOs
The previous version of this package added the FlexibleDataTransferObject
class which allowed you to ignore properties that didn't exist on the DTO. This behaviour has been changed, all DTOs are flexible now by default, but you can make them strict by using the #[Strict]
attribute:
Helper functions
There are also some helper functions provided for working with multiple properties at once.
Note that all()
will simply return all properties, while toArray()
will cast nested DTOs to arrays as well.
You can chain the except()
and only()
methods:
It's important to note that except()
and only()
are immutable, they won't change the original data transfer object.
Immutable DTOs and cloning
This package doesn't force immutable objects since PHP doesn't support them, but you're always encouraged to keep your DTOs immutable. To help you, there's a clone
method on every DTO which accepts data to override:
Note that no data in $original
is changed.
Collections of DTOs
This version removes the DataTransferObjectCollection
class. Instead you can use simple casters and your own collection classes.
Here's an example of casting a collection of DTOs to an array of DTOs:
If you don't want the redundant typehint, or want extended collection functionality; you could create your own collection classes using any collection implementation. In this example, we use Laravel's:
Simple arrays of DTOs
For a simple array of DTOs, or an object that implements PHP's built-in ArrayAccess
, consider using the ArrayCaster
which requires an item type to be provided:
Testing
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security
If you've found a bug regarding security please mail [email protected] instead of using the issue tracker.
Postcardware
You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.
Our address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium.
We publish all received postcards on our company website.
External tools
- json2dto: a GUI to convert JSON objects to DTO classes (with nesting support). Also provides a CLI tool for local usage.
- Data Transfer Object Factory: Intelligently generates a DTO instance using the correct content for your properties based on its name and type.
Credits
- Brent Roose
- All Contributors
Our Arr
class contains functions copied from Laravels Arr
helper.
License
The MIT License (MIT). Please see License File for more information.