README

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->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

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.