chrisharrison / php-array-of
Implement an array of a defined type. Generics replacement for PHP.
Installs: 491 137
Dependents: 3
Suggesters: 0
Security: 0
Stars: 10
Watchers: 2
Forks: 3
Open Issues: 0
Requires
- php: ^7.1 || ^8.0
Requires (Dev)
- phpunit/phpunit: ^6.3 || ^9.3
- squizlabs/php_codesniffer: ^3.1
This package is auto-updated.
Last update: 2024-10-25 19:23:34 UTC
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 ArrayOf
s 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 callable
s and no array
s.
Immutability
ArrayOf
s are mutable. This library provides the capability to define immutable objects in the form of ImmutableArrayOf
s. 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