README

value-object

Immutable Value Objects for PHP

Installation

Composer

composer require phpgears/value-object

Usage

Require composer autoload file

require './vendor/autoload.php';

Extend from Gears\ValueObject\AbstractValueObject. Make your class final, value objects should always be final

Be aware of the protected constructor, you should create a "named constructor" for your value object

use Gears\ValueObject\AbstractValueObject;

final class CustomStringValueObject extends AbstractValueObject
{
    private $value;

    public static function fromString(string $value)
    {
        $stringObject = new self();
        $stringObject->value = $value;

        return $stringObject;
    }

    public function getValue(): string
    {
        return $this->value;
    }

    public function isEqualTo($valueObject): bool
    {
        return \get_class($valueObject) === self::class 
            && $valueObject->getValue() === $this->value;
    }
}

Serialization

Extending AbstractValueObject does not automatically define serialization mechanisms in your value objects because value objects can be composed of several values, other value objects and even other objects such as enums

For this consider adding serialization methods in your value objects to control how serialization takes place

use Gears\ValueObject\AbstractValueObject;

final class Money extends AbstractValueObject implements \Serializable
{
    private const CURRENCY_EUR = 'eur';

    private $value;
    private $precision;
    private $currency;

    public static function fromEuro(int $value, int $precision)
    {
        $money = new self();
        $money->value = $value;
        $money->precision = $precision;
        $money->currency = static::CURRENCY_EUR; // Should be an enum

        return $money;
    }

    // [...]

    final public function __serialize(): array
    {
        return [
            'value' => $this->value,
            'precision' => $this->precision,
            'currency' => $this->currency,
        ];
    }

    final public function __unserialize(array $data): void
    {
        $this->assertImmutable();

        $this->value = $data['value'];
        $this->precision = $data['precision'];
        $this->currency = $data['currency'];
    }

    final public function serialize(): string
    {
        return serialize([
            $this->value,
            $this->precision,
            $this->currency,
        ]);
    }

    public function unserialize($serialized): void 
    {
        $this->assertImmutable();

        list(
            $this->value,
            $this->precision,
            $this->currency
        ) = \unserialize($serialized, ['allowed_classes' => false]);
    }
}

Enums and Value Objects get along perfectly, consider using phpgears/enum for enumerations

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.