best-served-cold/phalue-objects

Phalue Objects - PHP Value Objects

PhalueObjects

, _(*1)

A generic set of PHP Value Objects for use in any project., _(*2)

Wikipedia, _(*3)

When people exchange business cards, they generally do not distinguish between each unique card; they only are concerned about the information printed on the card. In this context, business cards are value objects., _(*4)

Table of contents

• Installation
• Philosophy
• Documents
  • Format

Installation

composer require best-served-cold/phalue-objects

Philosophy

To make this code consistent, we've stuck to a certain set of restrictions:, _(*5)

Rules

• Must be immutable
• Must contain one value
• Can instantiate new object from value
• Can be created from multiple arguments
• Can be equal regardless of object
• Must have a zero lifespan

Disclaimer: This is my interpretation of "The rules"., _(*6)

Must be immutable

The value object's value must be set at the time of construction. At no point should the value be mutated within the object., _(*7)

Must contain one value

The value object can only be constructed from one value, this can be any of the following types: * boolean * integer * float/double * string * array * object * resource * null, _(*8)

Can instantiate new object from value

Rather than mutating, a new object can be instantiated from an existing one., _(*9)

Example:, _(*10)

//...
public function double() 
{
    return new static($this->getValue() * 2);
}
...//

Can be created from multiple arguments

Instead of an object having multiple object properties, it should be created from multiple arguments., _(*11)

Example:, _(*12)

//...
public static function fromVars($one = 1, $two = 2, $three = 3)
{
    return new static([$one, $two, $three]); 
}
...//

Can be equal regardless of object

The type of a value object is irrelevant to equality:, _(*13)

Example:, _(*14)

//...
$bob = $stringValueObject->equals($csvValueObject);
...//

$bob is true where the type and value are equal., _(*15)

Must have a zero lifespan

Value objects must not persist data between run times. For example: no database or session information should be collected from within the object., _(*16)

Conventions

Follow PSR-FIG rules., _(*17)

Constructor

Example:, _(*18)

new SomeClass('value');

• Must only have one argument of any type

Creation methods (From)

Example:, _(*19)

SomeClass::fromSomeObject($someObject);

• Always start with "from"
• Must be static
• Can contain multiple arguments
• Must return new static instance

Conversion methods (To)

Example:, _(*20)

$someObject->toArray();

• Always start with "to"
• Must not be static
• Must have zero arguments
• Must return new static instance