chrisharrison/php-array-of

Implement an array of a defined type. Generics replacement for PHP.

1.1 2020-12-18 15:43 UTC

Requires

• php: ^7.1 || ^8.0

Requires (Dev)

• phpunit/phpunit: ^6.3 || ^9.3
• squizlabs/php_codesniffer: ^3.1

MIT

• Chris Harrison

README

Implement an array of a defined type. Generics replacement for PHP.

Requirements

Requires PHP >= 7.1

Installation

Through Composer, obviously:

composer require chrisharrison/php-array-of

Why?

PHP 7 has pretty good support for type declarations, both in arguments and returns. It now also handles primitives as well as class names. For example:

public function dealCard(string $cardName): Card;

One thing is still lacking. Array generics. There's an RFC for implementing 'Array Of'. It's been around for quite a while and was roundly rejected.

This library is a workaround for that. It allows you to make type declarations for arrays of a particular type.

Usage

Using an existing implementation

The library comes with ArrayOf implementations for all of the PHP scalar types. i.e.:

• ArrayOfInteger
• ArrayOfFloat
• ArrayOfString
• ArrayOfBoolean

These can then be used in a type declaration:

public function getIntegers(): ArrayOfInteger;

An ArrayOfInteger can be created:

$integers = new ArrayOfInteger([1,1,2,3,5,8,13]);

and used like an array:

$sum = $integers[5] + $integers[6]; // equals 21

Implementing your own type

You can create your own ArrayOfs for your own types.

final class ArrayOfCard extends ArrayOf
{
    protected function typeToEnforce(): string
    {
        return Card::class;
    }
}

An ArrayOfCard can be created thus:

$aceOfSpades = new Card('spades', 'ace');
$threeOfClubs = new Card('clubs', '3');

$cards = new ArrayOfCard([$aceOfSpades, $threeOfClubs]);

Other concerns

Enforcement

Members of an ArrayOf are enforced as being of the type specified in the typeToEnforce abstract method. This enforcement occurs on instantiation at runtime. If you try to instantiate with a member of a non-matching type, an exception will be thrown.

Permissible types

Only PHP scalars and objects can be members of an ArrayOf. So no callables and no arrays.

Immutability

ArrayOfs are mutable. This library provides the capability to define immutable objects in the form of ImmutableArrayOfs. These objects extend from ArrayOf and work in the same way except after the initial instantiation, no further changes can be made to the object. If you try to perform a write operation (e.g. unset) on it, an exception will be thrown. All of the scalar types are also provided in immutable form:

• ImmutableArrayOfInteger
• ImmutableArrayOfFloat
• ImmutableArrayOfString
• ImmutableArrayOfBoolean