A strongly typed Data Transfer Object without magic for PHP 7.4+

Maintainers

Details

github.com/romanzipp/DTO

Source

Issues

Fund package maintenance!
romanzipp

2.3.1 2022-12-14 13:49 UTC

README

Latest Stable Version Total Downloads License GitHub Build Status

A strongly typed Data Transfer Object without magic for PHP 8.0+ . Features support for PHP 8 union types and attributes.

Contents

Installation

composer require romanzipp/dto
  • For PHP 7.4 please use 1.x
  • For PHP 8.0 please use 2.x

Usage

use romanzipp\DTO\AbstractData;
use romanzipp\DTO\Attributes\Required;

class DummyData extends AbstractData
{
    #[Required]
    public string $name;

    public ?string $nickname;

    public string|int $height;

    public DateTime $birthday;

    public bool $subscribeNewsletter = false;
}

$data = new DummyData([
    'name' => 'Roman',
    'height' => 180,
]);

Require properties

When declaring required properties, the DTO will validate all parameters against the declared properties. Take a look at the validation table for more details.

use romanzipp\DTO\AbstractData;
use romanzipp\DTO\Attributes\Required;

class DummyData extends AbstractData
{
    #[Required]
    public string $name;
}

$data = new DummyData([]);

romanzipp\DTO\Exceptions\InvalidDataException: The required property `name` is missing

Array methods

Simple array representation

To get an array representation of the DTO, simply call the toArray instance method.

When transferring the DTO properties to an array format, the package will respect and call any toArray methods of nested DTO instances or otherwise fall back to any declared jsonSerialize method when implementing the JsonSerializable interface.

use romanzipp\DTO\AbstractData;

class DummyData extends AbstractData
{
    public string $firstName;

    public DummyData $childData;
    
    /** @var self[] */
    public array $children = [];
}

$data = new DummyData([
    'firstName' => 'Roman',
    'childData' => new DummyData([
        'firstName' => 'Tim',
     ]),
    'children' => [
        new DummyData([
            'firstName' => 'Tom'
        ]),
    ],
]);

$data->toArray();
// [
//    'firstName' => 'Roman',
//    'childData' => ['firstName' => 'Tim']
//    'children' => [
//        ['firstName' => 'Tom']
//    ] 
// ];

Convert keys

The toArrayConverted method allows the simple conversion of property keys to a given case.

use romanzipp\DTO\AbstractData;
use romanzipp\DTO\Cases;

class DummyData extends AbstractData
{
    public string $firstName;
}

$data = new DummyData([
    'firstName' => 'Roman',
]);

$data->toArrayConverted(Cases\CamelCase::class);  // ['firstName' => 'Roman'];
$data->toArrayConverted(Cases\KebabCase::class);  // ['first-name' => 'Roman'];
$data->toArrayConverted(Cases\PascalCase::class); // ['FirstName' => 'Roman'];
$data->toArrayConverted(Cases\SnakeCase::class);  // ['first_name' => 'Roman'];

Flexible DTOs

When attaching the Flexible attribute you can provide more parameters than declared in the DTO instance. All properties will also be included in the toArray methods. This would otherwise throw an InvalidDataException.

use romanzipp\DTO\AbstractData;
use romanzipp\DTO\Attributes\Flexible;

#[Flexible]
class DummyData extends AbstractData
{
    public string $name;
}

$data = new DummyData([
    'name' => 'Roman',
    'website' => 'ich.wtf',
]);

$data->toArray(); // ['name' => 'Roman', 'website' => 'ich.wtf];

Validation

* Attributes with default values cannot be required.

Testing

./vendor/bin/phpunit

Credits

This package has been inspired by Spaties Data-Transfer-Object released under the MIT License.