Download the PHP package sunrise/hydrator without Composer

Strongly typed hydrator for PHP 7.4+ with extensibility

php, dto, hydrator, mapper, populator, data-mapper

Installation

Navigation

• Allowed property types
• • Required
• • Optional
• • Null
• • Boolean
• • Integer
• • Number
• • String
• • Array
• • Timestamp
• • Timezone
• • Enumeration
• • UUID
• • Relationship
• • Custom type
• Ignored property
• Property alias
• Error handling
• Localization
• Doctrine annotations

How to use

Let's consider a typical DTO set:

Now, let's populate them all from an array:

Or, you can populate them using JSON:

Allowed property types

Required

If a property has no a default value, then the property is required.

Optional

If a property has a default value, then the property is optional.

Null

If a property is nullable, then the property can accept null.

Also, please note that empty strings or strings consisting only of whitespace will be handled as null for certain properties.

Boolean

A boolean value in a dataset can be represented as:

Also, please note that if a value in a dataset for this property is represented as an empty string or a string consisting only of whitespace, then the value will be handled as null.

Integer

An integer value in a dataset can also be represented as a string, e.g., "42".

Also, please note that if a value in a dataset for this property is represented as an empty string or a string consisting only of whitespace, then the value will be handled as null.

Number

A numerical value in a dataset can be represented not only as an integer or a floating-point number but also as a string containing a number. However, regardless of how such a value is represented in the dataset, it will always be stored in this property as a floating-point number.

Also, please note that if a value in a dataset for this property is represented as an empty string or a string consisting only of whitespace, then the value will be handled as null.

String

This property has no any additional behavior and only accepts strings.

Array

By default, this property accepts an array with any data. However, it can also be used to store relationships by using a special annotation, as shown in the example below:

In other words, the Subtype annotation can contain the same types as the types of class properties...

Having an unlimited number of relationships in an array is a potentially bad idea as it can lead to memory leaks. To avoid this, it is recommended to limit such an array, as shown in the example below:

In addition to arrays, you can also use collections, in other words, classes implementing the ArrayAccess interface, for example:

Note that for collections, instead of the Subtype annotation, you can use typing through its constructor. It is important that there is only one variadic parameter in it. Please refer to the example below:

Please note that in this case, you take on the responsibility of limiting the collection. To ensure that the hydrator understands when the collection is full, the offsetSet method should throw an OverflowException.

In general, remember that regardless of whether arrays or collections are used, their elements can be typed. For example, if you need an array that should consist only of dates, your code should look something like this:

Sometimes, there is a need to map a typed list to a collection. It's a relatively simple task; just use the example below:

This property has no any additional behavior and only accepts arrays.

Timestamp

Only the DateTimeImmutable type is supported.

This property accepts a date as a string in the specified format, but it can also accept a Unix timestamp as an integer or a string. To specify the Unix timestamp format, it should be indicated as follows:

Also, please note that if a value in a dataset for this property is represented as an empty string or a string consisting only of whitespace, then the value will be handled as null.

Default timestamp format

Timezone

Only the DateTimeZone type is supported.

Also, please note that if a value in a dataset for this property is represented as an empty string or a string consisting only of whitespace, then the value will be handled as null.

Default timezone

UUID

Using the ramsey/uuid package

Using the symfony/uid package

Also, please note that if a value in a dataset for this property is represented as an empty string or a string consisting only of whitespace, then the value will be handled as null.

Enumeration

PHP 8.1 built-in enumerations

This property should be typed only with typed enumerations. Therefore, for integer enumerations, a value in a dataset can be either an integer or an integer represented as a string. For string enumerations, a value in a dataset can only be a string.

MyCLabs enumerations

The popular alternative for PHP less than 8.1...

Also, please note that if a value in a dataset for this property is represented as an empty string or a string consisting only of whitespace, then the value will be handled as null.

Relationship

A value in a dataset can only be an array. However, please note that if you need a one-to-many relationship, you should refer to the array section for further information.

Support for custom types

If you need support for a custom type, it is a relatively simple task. Let's write such support for PSR-7 URI from the sunrise/http-message package:

Now, let's inform the hydrator about the new type:

Ignored property

If you need a property to be ignored and not populated during the object hydration process, use a special annotation like the example below:

Property alias

If you need to handle an unnormalized key in a dataset or have other reasons to associate such a key with a property that has a different name, you can use a special annotation for this purpose:

Error handling

The InvalidDataException exception contains errors related to an input dataset and is designed to display errors directly on the client side.

If you are using the symfony/validator package, you may find it useful to present the errors as a \Symfony\Component\Validator\ConstraintViolationListInterface. To achieve this, you can call the following method on this exception:

Or you can retrieve the list of errors in the standard way, as shown in the example below:

Localization

Doctrine annotations

To use annotations, you need to install the doctrine/annotations package:

To use annotations in PHP 7 or explicitly in PHP 8, you can use the following method of the hydrator:

If you need to provide your instance of an annotation reader, you can use the following method:

Test run