vectorial1024/alof-lib

PHP array-like object functions library.

0.1.1 2024-11-05 08:05 UTC

Requires

• php: ^8.1

Requires (Dev)

• phpunit/phpunit: ^10

Suggests

• vectorial1024/transmutation: A "collections"-like library for array-like objects.

MIT

• Vectorial1024

• library
• utility
• arrayobject
• splfixedarray
• traversable
• ArrayAccess
• SplObjectStorage
• weakmap
• arrayiterator

README

(This is a WIP project!)

PHP array-like object functions library ("alof-lib"). Type-hinted functions for array-like objects, just like those for native arrays. Think of this library as a polyfill of those useful functions for array-like objects, so that you may write clean code with array-like objects.

An array-like object ("ALO") is defined to be implements ArrayAccess and implements Traversable. Examples include:

• ArrayObject (since PHP 5)
• ArrayIterator (since PHP 5)
• SplObjectStorage (since PHP 5.1)
• SplDoublyLinkedList (since PHP 5.3)
• SplFixedArray (since PHP 5.3)
• SplStack (since PHP 5.3)
• SplQueue (since PHP 5.3)
• WeakMap (since PHP 8)
• ... and perhaps more

A PHP array is NOT an ALO. It is still an array.

Latest version requires PHP 8.1+.

See the change log in the CHANGELOG.md file.

Want to easily process ALOs? See vectorial1024/transmutation here.

Notes and Disclaimers

• ALO functions aim to be faithful user-land reproductions of their array function counterparts, but there might be slight differences between both sides
• Some ALO functions may not make sense depending on your exact ALO implementation; use judgement before you use the ALO functions

Installation

via Composer:

composer require vectorial1024/alof_lib

Testing

This library uses PHPUnit for testing, which can be triggered from Composer. To test this library, run:

composer run-script test

Example Usage

Refer to the test cases under /tests for more examples, but for a minimal example:

use Vectorial1024\AlofLib\Alof;

$objKey = new stdClass();
$objKey->name = "foo";

// conveniently get the keys of the WeakMap (WeakMap becomes a "WeakHashSet" for objects)
$map = new WeakMap();
$map[$objKey] = "1";
$map[$objKey] = 2;
$map[$objKey] = "Hello World!";
$keys = Alof::alo_keys($map);
assert($keys === [$objKey]); // passes

// correctly get the keys of the SplObjectStorage (no more nasty foreach surprises!)
$splObjectStore = new SplObjectStorage();
$splObjectStore[$objKey] = "Hello World!";
$keys = Alof::alo_keys($splObjectStore);
assert($keys === [$objKey]); // passes

Relationship with transmutation

This library does the dirty work and ensures the correctness of ALO functions, while transmutation provides an easy-to-use API for ALO processing.