README

This library offer you an easy way to handle value objects in a Doctrine ORM application.

It will save you the creation of Doctrine types for every different value object types you have.

Installation

composer require yokai/doctrine-value-object

Setup

You will have to register your value object types to the Doctrine type system.

use Doctrine\DBAL\Types\Type;
use Yokai\DoctrineValueObject\Doctrine\Types;

(new Types(['doctrine_type_name' => MyValueObject::class]))
    ->register(Type::getTypeRegistry());

If you are using Symfony, you can register your value object types in the kernel construction.

use Doctrine\DBAL\Types\Type;
use Yokai\DoctrineValueObject\Doctrine\Types;

class Kernel extends BaseKernel
{
    private const DOCTRINE_VALUE_OBJECTS = [
        'doctrine_type_name' => MyValueObject::class,
    ];

    public function __construct(string $environment, bool $debug)
    {
        parent::__construct($environment, $debug);
        (new Types(self::DOCTRINE_VALUE_OBJECTS))->register(Type::getTypeRegistry());
    }
}

You can also leverage the power of attributes, along with olvlvl/composer-attribute-collector, to automatically register all your value objects at once.

use Doctrine\DBAL\Types\Type;
use Yokai\DoctrineValueObject\Doctrine\Types;

#[\Attribute(\Attribute::TARGET_CLASS)]
final readonly class AsValueObject
{
    public function __construct(
        public string $name,
    ) {
    }
}

#[AsValueObject(MyValueObject::DOCTRINE_TYPE_NAME)]
final class MyValueObject implements \Yokai\DoctrineValueObject\StringValueObject
{
    public const DOCTRINE_TYPE_NAME = 'doctrine_type_name';
}

$types = [];
foreach (Attributes::findTargetClasses(AsValueObject::class) as $target) {
    /** @var AsValueObject $attribute */
    $attribute = $target->attribute;
    $types[$attribute->name] = $target->name;
}
(new Types($types))->register(Type::getTypeRegistry());

Usage

After you completed setup you will be able to use your value object types type in any of your entities:

<?php

namespace Yokai\DoctrineValueObject\Tests;

use Doctrine\ORM\Mapping as ORM;

final class Entity
{
    #[ORM\Column(type="doctrine_type_name")]
    public MyValueObject $status;
}

Value Object Types

Value objects are wrappers around existing doctrine types.

Let's see what wrappers exist and give you an example for each.

String

Imagine you have an application that stores phone numbers in database. You will often have to determine the country from which the number is originated.

You can centralize this logic in a PhoneNumber string value object. The object will be stored as a string in the database but hydrated back to this object by Doctrine.

See PhoneNumber code in tests.

DateTime

Imagine you have an application that stores users birthdate. You will often have to determine the age of the user, and put rules on this value.

You can centralize this logic in a Birthdate datetime value object. The object will be stored as datetime immutable in the database but hydrated back to this object by Doctrine.

See Birthdate code in tests.

Integer

Imagine you have an application that stores user status. You will often have to put rules on this value.

You can centralize this logic in a Status integer value object. The object will be stored as a integer in the database but hydrated back to this object by Doctrine.

See Status code in tests.

Object

⚠️ If you are looking for value objects with multiple properties each stored in a table column: please use Doctrine Embeddables.

⚠️ If you are looking for polymorphic value objects stored as JSON: please use dunglas/doctrine-json-odm.

Imagine you have an application that stores user notifications preferences. There is multiple information you want to store, as a JSON object.

You can centralize this logic in a Notifications object value object. The object will be stored as a json object in the database but hydrated back to this object by Doctrine.

See Notifications code in tests.

Collection

Imagine that you have an application that have to store multiple phone numbers in a property. You can centralize this type hinting in a PhoneNumbers collection value object.

The object will be stored as a json array in the database but hydrated back to this object by Doctrine.

See PhoneNumbers code in tests.

Contribution

Please feel free to open an issue or a pull request.

The library was originally created by Yann Eugoné. See the list of contributors.

License

This library is under MIT LICENSE.