romanzipp/dto

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

2.3.1 2022-12-14 13:49 UTC

Requires

• php: ^8.0
• ext-json: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• phpstan/phpstan: ^0.12.99|^1.0
• phpunit/phpunit: ^9.0
• romanzipp/php-cs-fixer-config: ^3.0
• symfony/var-dumper: ^5.1

MIT

• romanzipp

README

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

Contents

• Installation
• Usage
• Validation table

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

Definition	Required	Value	Valid	isset()
public $foo	no	''	✅	✅
public $foo	no	NULL	✅	✅
public $foo	no	none	✅	✅
public $foo	yes	''	✅	✅
public $foo	yes	NULL	✅	✅
public $foo	yes	none	🚫	-
public string $foo	no	''	✅	✅
public string $foo	no	NULL	🚫	-
public string $foo	no	none	✅	🚫
public string $foo	yes	''	✅	✅
public string $foo	yes	NULL	🚫	-
public string $foo	yes	none	🚫	-
public ?string $foo	no	''	✅	✅
public ?string $foo	no	NULL	✅	✅
public ?string $foo	no	none	✅	🚫
public ?string $foo	yes	''	✅	✅
public ?string $foo	yes	NULL	✅	✅
public ?string $foo	yes	none	🚫	-
public ?string $foo = null	no	''	✅	✅
public ?string $foo = null	no	NULL	✅	✅
public ?string $foo = null	no	none	✅	✅
public ?string $foo = null	yes	''	⚠️*	-
public ?string $foo = null	yes	NULL	⚠️*	-
public ?string $foo = null	yes	none	⚠️*	-

* Attributes with default values cannot be required.

Testing

./vendor/bin/phpunit

Credits

• Roman Zipp

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