ValueObjects

A PHP Value Object Library in use by Morebec Projects

Value objects are small objects representing simple concepts, and whose equality is based on their internal property values rather than a specific identity.

Value objects must honour the following contract:

• They are immutable (no setters)
• They are Self Validating
• They represent and describe concepts in a clear way

Installation

To install the library in a project, add these lines to your composer.json configuration file:

{
"repositories": [
{
"url": "https://github.com/Morebec/ValueObjects.git",
"type": "git"
}
],
"require": {
"morebec/value-objects": "^1.0"
}
}

Usage

This library comes with a number of predesigned ValueObject classes, that you can use in your projects. The ValueObject either implement the ValueObjectInterface or extend the BasicEnum class.

Creating your own Value Object using ValueObjectInterface

To create, one needs to implement the ValueObjectInterface and implement the two following methods:

• __toString()
• isEqualTo(ValueObjectInterface $valueObject): bool

Here's a basic example:

useAssert\Assertion;
useMorebec\ValueObjects\ValueObjectInterface;
/** * Age Value Object */finalclass Age implements ValueObjectInterface
{
/** @var int age */private$age;
publicfunction__construct(int$age)
{
Assertion::min($age, 1);
$this->age = $age;
}
publicfunction__toString()
{
returnstrval($this->age);
}
/** * Returns the value of this age object * @return int */publicfunctiontoInt(): int
{
return$this->age;
}
/** * Indicates if this value object is equal to abother value object * @param ValueObjectInterface $valueObject othervalue object to compare to * @return boolean true if equal otherwise false */publicfunctionisEqualTo(ValueObjectInterface$vo): bool
{
return (string)$this === (string)$vo;
}
}

Doing that, our class can be used as follows:

$age = newAge(24);
// Test Equality$maturity = newAge(18);
$age->isEqualTo($maturity); // false $age == $maturity; // false$age === '18'; // false// Test Greater than$age->toInt() >= 18; // true$age->toInt() >= $maturity->toInt();

Creating your own Enum class extending BasicEnum

To create a new Enum, one needs to extend the BasicEnum class. As an example, lets pretend we want to create a CardinalPoint Class. Since there are strictly 4 cardinal points, we will create an enum based ValueObject:

<?phpuseMorebec\ValueObjects\ValueObjectInterface;
/** * CardinalPoint */class CardinalPoint implements ValueObjectInterface
{
constNORTH = 'NORTH'; constEAST = 'EAST'; constWEST = 'WEST'; constSOUTH = 'SOUTH';
}

Doing this, will allow us to use our class in the following way:

// Instatiate a new CardinalPoint instance$direction = newCardinalPoint(CardinalPoint::NORTH);
// Since Enums have builtin validation,// the following line would throw an InvalidArgumentException:$direction = newCardinalPoint('North');
// However the following would work:$direction = newCardinalPoint('NORTH');
// Using in functions or class methods publicfunctionchangeDirection(CardinalPoint$direction)
{
// Testing equlity with stringif(!$direction->isEqualTo(newCardinalPoint(CardinalPoint::EAST))) {
echo'Not going East!';
}
// Since the constants are strings, it is also possible to compare// using string comparisonif($direction == CardinalPoint::NORTH) {
echo'Definitely going North!';
} }

Running Tests

The tests are based on codeception. To run the tests simply run:

composer test