triun/value-object

Value Object

Value Object

![Software License][ico-license], _(*1)

Value Object definition., _(*2)

About

PHP Class interface to define and standardise a Value Object format., _(*3)

In computer science, a value object is a small object that represents a simple entity whose equality is not based on identity: i.e. two value objects are equal when they have the same value, not necessarily being the same object (Wikipedia)., _(*4)

Installation

Require this package with composer using the following command:, _(*5)

composer require triun/value-object

Description

The package contains a ValueObject interface:, _(*6)

interface ValueObject
{
    /**
     * Returns a object taking PHP native value(s) as argument(s).
     *
     * @return \Triun\ValueObject\ValueObject
     */
    public static function fromNative();

    /**
     * Returns PHP native value(s)
     *
     * @return mixed
     */
    public function toNative();

    /**
     * Compare two ValueObjectInterface and tells whether they can be considered equal.
     *
     * @param \Triun\ValueObject\ValueObject $object
     *
     * @return mixed
     */
    public function equals(ValueObject $object);

    /**
     * Returns a string representation of the object.
     *
     * @return string
     */
    public function __toString();
}

And a Invalid Argument Exception:, _(*7)

class InvalidNativeArgumentException extends \InvalidArgumentException
{
    /**
     * InvalidNativeArgumentException constructor.
     *
     * @param string $value
     * @param array  $allowed_types
     */
    public function __construct($value, array $allowed_types)
    {
        $this->message = sprintf(
            'Argument "%s" is invalid. Allowed types for argument are "%s".',
            $value,
            implode(', ', $allowed_types)
        );
    }
}

Usage

Example of use for a single field ValueObject:, _(*8)

use Triun\ValueObject\ValueObject;
use Triun\ValueObject\Exceptions\InvalidNativeArgumentException;

class StringLiteral implements ValueObject
{
    /**
     * Native string
     *
     * @var string
     */
    protected $value;

    /**
     * Returns a StringLiteral object given a PHP native string as parameter.
     *
     * @internal param string $value
     * 
     * @return StringLiteral
     */
    public static function fromNative()
    {
        $value = func_get_arg(0);

        return new static($value);
    }

    /**
     * Returns a StringLiteral object given a PHP native string as parameter.
     *
     * @param string $value
     */
    public function __construct($value)
    {
        if (false === \is_string($value)) {
            throw new InvalidNativeArgumentException($value, array('string'));
        }

        $this->value = $value;
    }

    /**
     * Returns the value of the string
     *
     * @return string
     */
    public function toNative()
    {
        return $this->value;
    }

    /**
     * Tells whether two string literals are equal by comparing their values
     *
     * @param  ValueObject $stringLiteral
     * 
     * @return bool
     */
    public function equals(ValueObject $stringLiteral)
    {
        if (static::class !== get_class($stringLiteral)) {
            return false;
        }

        return $this->toNative() === $stringLiteral->toNative();
    }

    /**
     * Tells whether the StringLiteral is empty
     *
     * @return bool
     */
    public function isEmpty()
    {
        return \strlen($this->toNative()) == 0;
    }

    /**
     * Returns the string value itself
     *
     * @return string
     */
    public function __toString()
    {
        return $this->toNative();
    }
}

Links

• Wikipedia: Value Object
• Wikipedia: Domain-Driven Design
• Culttt: What is the difference between Entities and Value Objects?

Issues

Bug reports and feature requests can be submitted on the Github Issue Tracker., _(*9)

Contributing

See CONTRIBUTING.md for information., _(*10)

License

The Laravel Model Base is open-sourced software licensed under the MIT license, _(*11)