best-served-cold/phalue-objects

Phalue Objects - PHP Value Objects

v0.0.11-alpha 2017-03-12 13:06 UTC

Requires

• php: >=5.6
• sabre/xml: ^1.5
• symfony/finder: 2.*
• symfony/yaml: 2.*

Requires (Dev)

• mockery/mockery: ^0.9.4
• phpdocumentor/phpdocumentor: ^2.8
• phpmd/phpmd: @stable
• phpunit/phpunit: ~4.0
• squizlabs/php_codesniffer: 2.*

MIT

• Adam Lewis

• value objects
• immutable
• PhalueObjects
• Best Served Cold

README

A generic set of PHP Value Objects for use in any project.

Wikipedia

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.

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:

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".

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.

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

Can instantiate new object from value

Rather than mutating, a new object can be instantiated from an existing one.

Example:

//...
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.

Example:

//...
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:

Example:

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

$bob is true where the type and value are equal.

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.

Conventions

Follow PSR-FIG rules.

Constructor

Example:

new SomeClass('value');

• Must only have one argument of any type

Creation methods (From)

Example:

SomeClass::fromSomeObject($someObject);

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

Conversion methods (To)

Example:

$someObject->toArray();

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