fsubal/donphan

Utility traits for type-safe & immutable entity in PHP

Donphan

Utility traits for type-safe & immutable entity in PHP., _(*1)

Install

https://packagist.org/packages/fsubal/donphan, _(*2)

composer require fsubal/donphan

Why Donphan ?

In PHP application without certain frameworks, arrays are often used as domain models., _(*3)

<?php

$user = [
    'user_id' => validateInt($_POST['user_id']),
    'name' => validateString($_POST['name']),
];

...

function doSomethingForUser(array $user)
{
    $name = $user['name'];
    ...
}

When refactoring these mess (or migrating to completely new framework) seems too hard, Donphan may help you., _(*4)

What Donphan does

It provides two utility traits., _(*5)

• \Donphan\Validatable: provides ::validate method, and lifecycle hooks.
• \Donphan\Immutable: provides ::from factory method.

<?php

final class User
{
    use \Donphan\Immutable;

    const REQUIRED = [
        'user_id' => 'numeric',
        'name' => 'string'
    ];
}

// and then
$user = User::from([
    'user_id' => $_POST['user_id'],
    'name' => $_POST['name']
]);

function doSomethingForUser(User $user)
{
    $name = $user->name;
    ...
}

Not perfect, but now you have type safety with ease., _(*6)

How to use

• Define your own model class
• use \Donphan\Immutable inside
• Define const REQUIRED = [...], and const OPTIONAL = [...] if you want.
• If you need, define static functions beforeTypeCheck or afterTypeCheck (See Lifecycle methods)

Then, you can use YourClass::from(array $params) or YourClass::validate(array $params)., _(*7)

Type checking

Donphan supports these types., _(*8)

• mixed
• int
• float
• numeric
• string
• boolean
• array
• and any defined class name.

numeric looks like an original type ? Yes, but it is just validated by is_numeric ( https://secure.php.net/manual/en/function.is-numeric.php )., _(*9)

It is almost like int|string, useful for some ids in $_GET or $_POST or something., _(*10)

These types are not supported., _(*11)

• null
• object
• resource
• callable
• Closure
• Exception
• Error

Lifecycle methods

If you want to have default value ? Or if you allow additional validation to your Immutable object ?, _(*12)

Then, the lifecycle methods might be needed., _(*13)

\Donphan\Validatable provides two lifecycle methods., _(*14)

• beforeTypeCheck: Executed just before type checking. It gets original params, and you must return an array.
• afterTypeCheck: Executed just after type checking. It gets original params, and you must NOT return anything.

beforeTypeCheck is useful for mutating the original array, and afterTypeCheck is useful for performing additional validations., _(*15)

Example below, _(*16)

final class User
{
    use \Donphan\Immutable;

    const REQUIRED = [
        'user_id' => 'numeric',
        'name' => 'string',
        'birthday' => '\DateTimeImmutable'
    ];

    const OPTIONAL = [
        'url' => 'string'
    ];

    public static function beforeTypeCheck(array $params)
    {
        if (!isset($params['url'])) {
            $params['url'] = 'https://example.com';
        }
        return $params;
    }

    public static function afterTypeCheck(array $params)
    {
        if (strlen($params['name']) == 0) {
            throw new \InvalidArgumentException('params[name] must not be empty!');
        }
    }
}

Note that the url added in beforeTypeCheck is also type checked (if it is written in REQUIRED or OPTIONAL)., _(*17)

Requirements

PHP 5.6+ ( Needs to be writable const with array in classes ), _(*18)

LICENSE

This is licensed under MIT License., _(*19)