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

Data Transfer Object for PHP 8

Easily manage Data Transfer Objects in PHP.

This DTO library, for PHP 8 and above, is designed to keep data consistent throughout your project thanks to strict type-hinted properties, nested data mapping and value manipulation.

Authors

• Dom McLaughlin @d3jmc

Installation

We recommend installing this library via Composer.

Or, if you'd prefer, you can clone this repository into your project.

Usage

Each developer and/or project will have their own preference in creating and managing DTOs. Please feel free to use whichever method you'd like. These are just guidelines.

In this example, we'll be creating a simple User DTO which will store all of the user's profile information, GDPR preferneces and roles.

Creating the User DTO Class

We first need to start out by creating a DTO class for the user. This class will contain all of the properties we want to store and any custom logic we need to use to modify incoming data.

Property names should always be camelCase. When populating data into the DTO, you can use snake_case as this will be converted automatically. If you are passing data into the DTO but the output is not what you're expecting, this is likely to be due to name mismatch.

Populating the User DTO Class

Populating data into a DTO class is really simple. You can either pass your data into the constructor or use the fill method.

Please be aware that the data must be an array.

Outputting the User DTO Class properties

There are 2 methods you can use to return the properties inside the DTO class. These are get and toArray. The former will return an instance of the DTO class, whereas toArray will do what it says on the tin and convert the properties to an array.

Type-hinting another DTO class to a property

Let's say we want to store some GDPR preferences for the user. While we could create a separate property for each setting in the User DTO Class, it would be better to group them together in their own DTO class. Not only will this make it easier to pull out all of the GDPR properties in one go, we can also reuse this class elsewhere.

So, let's create a new DTO class for GDPR preferences.

Now, in the User DTO class, we need to create the property. Pay attention to the type-hint for the $gdpr property. This is neccessary so when it comes to populating the data, it will be automatically mapped to the UserGdprDto class.

Finally, in our data array, we can add the user's GDPR preferences.

The output would be something like:

Type-hinting another DTO class to a property as an array

In this example, we want to store the user's roles, however a user can have many roles so this property will need to be an array. Like in the previous example, we may reference roles elsewhere in the project, so it's better to create a separate UserRoleDto class.

Now, in our main User DTO class, we'll need to create a property for roles. This will be slightly different to our $gdpr property as we need to create a doc comment to tell the library that each array should be an instance of the UserRoleDto class.

This must be specified as the full namespace.

In our data array, we can now add the roles.

The output would be something like:

This functionality will work for multi-nested arrays too, so say you have a permissions array inside of roles, just repeat this process.

Mapping Data

In some cases, the data you are sending to the DTO class won't match the properties you have set up. A common example is when processing data from an API. In your project, you refer to a user's last name as 'last_name', whereas the API refers to it as 'surname'. This can be easily solved by creating a map.

The output of the above would return John as the first name, but null as the last name as our DTO class doesn't have a property for 'surname'.

A map is just a key value array, where the key is the property name in your DTO class and the value is the key of the data you want to use.

Your DTO class can either take a map through its constructor or by using the map function. If you choose to use the function, please ensure it is triggered before the fill function, otherwise the mappings won't work.

Mappings work for type-hinted DTO properties too.

Manipulating Data

Sometimes, the data you receive in your DTO class isn't in the format you'd like, or perhaps you want to create a fallback if the value is null, or even populate a whole new property based on other property values.

This can be achieved by using the magic set function in your DTO class. You can override any property value by calling setPropertyName(). The function will include a default value parameter.

In this example, we want to create a displayName property that will use the value of firstName and lastName, or the original displayName value if one is passed in with the data.

Another example is in our UserRoleDto class, we want to specify whether they are a super user.

Contributing

Contributions are always welcome!

Please submit your PR and we will review it as soon as possible.

License

MIT