README

This package provides a tuple type object for PHP. It is based off simondeeley\Type package which provides immutable objects.

In mathematics a tuple is a finite ordered list (sequence) of elements. An n-tuple is a sequence (or ordered list) of n elements, where n is a non-negative integer.

–Wikipedia

An example of a tuple could be [1, 2, 3, 4, 5]. The order of the items in a tuple is important, so given a set of 'A' being [1, 2, 3] and 'B' also being [1, 2, 3] then it's true that A equals B. However if we have another set 'C' which is [3, 2, 1] then this is not equal to A (or B).

This package was born out of a love creating beautifully crafted 'boilerplate' code which can be reused again and again in any number of both simple and complex objects. Most of the ideas used in this package revolve around the need to create the most basic of PHP objects - one that is immutable and unchanging. Trouble is, PHP has a fair few 'magic methods' which, although great for method overriding, are less great for ensuring an immutable state. This package aims to solve that problem and provide a number of base classes to allow you to build easy-to-use immutable classes of your own.

Requirements

PHP >= 7.1.0

Installation

composer require simondeeley/tuple

Usage

Create your own tuple object

use simondeeley\Tuple;

class MyTuple extends Tuple
{
    //...
}

This is the starting point to creating a tuple. By default you can have any number of items in your tuple object (up to the limit of PHP's PHP_INT_MAX value). You can override this and create your own maximum length tuples.

Let's go ahead and create a simple tuple called a pair. Unsurprisingly this has a maximum of two items.

use simondeeley\Tuple;

class Pair extends Tuple
{
    const MAX_LENGTH = 2;
}

Now we have our new class we can create pair-type objects until out hearts content...

$numeric = new Pair(1, 2);
$strings = new Pair('A', 'B');
$mixed = new Pair(1024, 'FooBar');
$objects = new Pair($numeric, $strings);

As well as a maximum length value, you can also specify minimum length values. By setting the two values as the same, you effectively impose an exact requirement for the number of arguments a tuple can have. This is very useful for creating tuples that are true to their mathematical form, which brings us on to...

Example Tuples

This package provides two pre-built tuples out-of-the box, Single and Pair these provide functionality for 1-tuple and 2-tuple objects, respectively. Using them is very simple

use simondeeley\Tuples\Single;
use simondeeley\Tuples\Pair;

$single = new Single('foo'); // Can only ever have one argument
$pair = new Pair(10, 20); // Can only ever have exactly two arguments

Testing Equality

The base tuple implements the TypeEquality interface from the simondeeley\Type package. Using this equality check we can compare two tuples. Following on from our Pair example above we can do the following

$foo = new Pair(1, 2);
$bar = new Pair(1, 2);
$baz = new Pair(2, 1);

$foo->equals($bar); // Returns true
$foo->equals($baz); // Returns false

Explore the source code to see how the comparisons are made or to see how the base tuple class is built.

simondeeley / tuple

Maintainers

Details