https://github.com/simondeeley/tuple
Extendable, reusable PHP tuple object
https://github.com/simondeeley/tuple
immutable php php7 tuple
Last synced: 8 months ago
JSON representation
Extendable, reusable PHP tuple object
- Host: GitHub
- URL: https://github.com/simondeeley/tuple
- Owner: simondeeley
- License: gpl-3.0
- Created: 2017-11-26T12:14:52.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2017-12-04T17:34:10.000Z (about 8 years ago)
- Last Synced: 2024-11-22T17:49:08.287Z (about 1 year ago)
- Topics: immutable, php, php7, tuple
- Language: PHP
- Size: 40 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Reusable tuple object for PHP
==================================
[](https://packagist.org/packages/simondeeley/tuple) [](https://packagist.org/packages/simondeeley/tuple) [](https://packagist.org/packages/simondeeley/tuple) [](https://packagist.org/packages/simondeeley/tuple) [](https://travis-ci.org/simondeeley/tuple) [](https://scrutinizer-ci.com/g/simondeeley/tuple/?branch=master) [](https://scrutinizer-ci.com/g/simondeeley/tuple/?branch=master)
This package provides a tuple type object for PHP. It is based off [simondeeley\Type](https://github.com/simondeeley/type) package which provides immutable objects.
> In [mathematics](https://en.wikipedia.org/wiki/Mathematics) a **tuple** is a finite ordered list (sequence) of [elements](https://en.wikipedia.org/wiki/Element_(mathematics)). An **_n_-tuple** is a [sequence](https://en.wikipedia.org/wiki/Sequence) (or ordered list) of _n_ elements, where _n_ is a non-negative integer.
>
> –_[Wikipedia](https://en.wikipedia.org/wiki/Tuple)_
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
```php
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](http://php.net/manual/en/reserved.constants.php) 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.
```php
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...
```php
$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`](https://github.com/simondeeley/type/blob/master/src/Tuples/Single.php) and [`Pair`](https://github.com/simondeeley/type/blob/master/src/Tuples/Pair.php) these provide functionality for _1_-tuple and _2_-tuple objects, respectively. Using them is very simple
```php
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`](https://github.com/simondeeley/type/blob/master/src/Type/TypeEquality.php) interface from the [simondeeley\Type](https://github.com/simondeeley/type) package. Using this equality check we can compare two tuples. Following on from our Pair example above we can do the following
```php
$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.