General purpose immutable Data Transfer Objects for PHP
This library provides a means to implement DTO classes as long as three different implementations of general purpose abstract DTO objects you can extend from
This DTO objects are immutable as can be thanks to gears/immutability that means once the DTO is created there is no way a value on it is mutated (inside PHP boundaries)
composer require phpgears/dto
Require composer autoload file
require './vendor/autoload.php';You can use ImmutabilityBehaviour and PayloadBehaviour in any object you want to have immutable DTO functionality
use Gears\Immutability\ImmutabilityBehaviour;
use Gears\DTO\DTO;
use Gears\DTO\PayloadBehaviour;
class MyDTO implements DTO, MyDTOInterface
{
use ImmutabilityBehaviour, PayloadBehaviour {
PayloadBehaviour::__call insteadof ImmutabilityBehaviour;
}
public function __construct(array $parameters)
{
$this->assertImmutable();
$this->setPayload($parameters);
}
final public function getAllowedInterfaces(): array
{
return [DTO::class, MyDTOInterface::class];
}
}If you just need a plain DTO object it gets a lot easier, this boilerplate code is already in place for you by extending Gears\DTO\AbstractDTO or Gears\DTO\AbstractScalarDTO classes
Protected constructors force you to create "named constructors", this has a very useful side effect, you get to type-hint all your DTO parameters
use Gears\DTO\AbstractScalarDTO;
/**
* @method hasName(): bool
* @method getName(): string
* @method hasLastName(): bool
* @method getLastName(): string
* @method hasDate(): bool
* @method getDate(): \DateTimeImmutable
*/
class MyDTO extends AbstractScalarDTO
{
/**
* Custom named constructor.
*
* @param string $name
* @param string $lastName
* @param DateTimeImmutable $date
*
* @return self
*/
public static function instantiate(
string $name,
string $lastName,
\DateTimeImmutable $date
): self {
return new static([
'name' => $name,
'lastName' => $lastName,
'date' => $date->setTimezone(new \DateTimeZone('UTC'))->format('U'),
]);
}
/**
* Transforms 'date' parameter every time it is accessed.
*/
protected function outputDate(string $date): \DateTimeImmutable
{
return DateTimeImmutable::createFromFormat('U', $date);
}
}The difference between Gears\DTO\AbstractDTO and Gears\DTO\AbstractScalarDTO is that the later ensures all payload is either a scalar value (null, string, int, float or bool) or an array of scalar values. Its purpose is to ensure the object can be securely serialized, it is the perfect match to create Domain Events, or CQRS Commands/Queries
Finally Gears\DTO\AbstractDTOCollection is a special type of DTO that only accepts a list of elements, being these elements implementations of DTO interface itself. This object is meant to be used as a return value when several DTOs should be returned, for example from a DDBB query result
You can take advantage of magic method __call on DTO objects to access parameters. If you plan to use this feature it's best to annotate this magic accessors at class level with @method phpDoc tag, this will help your IDE auto-completion
Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before.
See file CONTRIBUTING.md
See file LICENSE included with the source code for a copy of the license terms.