General purpose immutable Data Transfer Objects for PHP

0.1 2018-09-16 15:03 UTC

README

PHP version Latest Version License

Build Status Style Check Code Quality Code Coverage

Total Downloads Monthly Downloads

DTO

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)

Installation

Composer

composer require phpgears/dto

Usage

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->checkImmutability();

        $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

Constructors are declared protected forcing you to create "named constructors", this have 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
{
    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. It's purpose is to ensure the DTO can be securely serialized, it is the perfect match to create Domain Events, or CQRS Command/Query. Other than that both classes are exactly the same

Finally Gears\DTO\AbstractDTOCollection is a special type of DTO that only accepts a list of elements, being this 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 request

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 you're IDE auto-completion

Contributing

Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before.

See file CONTRIBUTING.md

License

See file LICENSE included with the source code for a copy of the license terms.