versatile collections
New Major Release
A collection package that can be extended to implement things such as a Dependency Injection Container, RecordSet objects for housing database records, a bag of http cookies, or technically any collection of items that can be looped over and whose items can each be accessed using array-access syntax or object property syntax.
You can:
This package provides optional strict-typing of collection items and strives for 100 % unit-test coverage.
Via composer: (Requires PHP 7.4+ or PHP 8.0+).
Switch to the 3.X branch to read the documentation for the 3.X version.
Switch to the 4.X branch to read the documentation for the 4.X version.
Switch to the 5.x branch to read the documentation for the 5.x version.
Switch to the master branch to read the documentation for the latest version.
composer require rotexsoft/versatile-collections
If you are simply looking to store items of the same or differing types in a collection you can use simply use the GenericCollection class like so:
<?php
use VersatileCollectionsGenericCollection;
// items to be stored in your collection
$item1 = ['yabadoo']; // an array
$item2 = function(){ echo 'Hello World!'; }; // a callable
$item3 = 777.888; // a float
$item4 = 777; // an int
$item5 = new stdClass(); // an object
$item6 = new ArrayObject([]); // another object
$item7 = tmpfile(); // a resource
$item8 = true; // a boolean
$item9 = "true"; // a string
// Technique 1: pass the items to the constructor of the collection class
$collection = new VersatileCollectionsGenericCollection(
$item1, $item2, $item3, $item4, $item5, $item6, $item7, $item8, $item9
);
// Technique 2: pass the items in an array using argument unpacking
// to the constructor of the collection class
$collection = new GenericCollection(
...[$item1, $item2, $item3, $item4, $item5, $item6, $item7, $item8, $item9]
);
// Technique 3: pass the items in an iterable (such as an array) to the static makeNew helper method
// available in all collection classes
$collection = GenericCollection::makeNew(
[$item1, $item2, $item3, $item4, $item5, $item6, $item7, $item8, $item9]
);
// Technique 4: create an empty collection object and subsequently add each
// item to the collection via array assignment syntax or object
// property assignment syntax or using the appendItem($item),
// prependItem($item, $key=null), push($item) or put($key, $value)
// methods
$collection = new GenericCollection(); // empty collection
// OR
$collection = GenericCollection::makeNew(); // empty collection
$collection[] = $item1; // array assignment syntax without key
// the item is automatically assigned
// the next available integer key. In
// this case 0
$collection[] = $item2; // array assignment syntax without key
// the next available integer key in this
// case is 1
$collection['some_key'] = $item3; // array assignment syntax with specified key `some_key`
$collection->some_key = $item4; // object property assignment syntax with specified property
// `some_key`. This will update $collection['some_key']
// changing its value from $item3 to $item4
$collection->appendItem($item3) // same effect as:
->appendItem($item5); // $collection[] = $item3;
// $collection[] = $item5;
// Adds an item to the end of the collection
// You can chain the method calls
$collection->prependItem($item6, 'new_key'); // adds an item with the optional
// specified key to the front of
// collection.
// You can chain the method calls
$collection->push($item7); // same effect as:
// $collection[] = $item7;
// Adds an item to the end of the collection
// You can chain the method calls
$collection->put('eight_item', $item8) // same effect as:
->put('ninth_item', $item9); // $collection['eight_item'] = $item8;
// $collection['ninth_item'] = $item9;
// Adds an item with the specified key to
// the collection. If the specified key
// already exists in the collection the
// item previously associated with the
// key is overwritten with the new item.
// You can chain the method callsYou can also make any class in your application behave exactly like VersatileCollectionsGenericCollection by implementing VersatileCollectionsCollectionInterface and using VersatileCollectionsCollectionInterfaceImplementationTrait in such classes.
If you want to enforce strict-typing, the following Collection classes are provided in this package:
To implement a custom collection that only contains objects that are instances of a specific class (for example PDO), your custom collection class must adhere to the following requirements:
Your custom collection class must implement VersatileCollectionsStrictlyTypedCollectionInterface which currently contains the methods below:
$item is of the expected type or false otherwiseYour custom collection class should use VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait (which contains implementation of the methods in VersatileCollectionsStrictlyTypedCollectionInterface). If you choose not to use VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait, then you will have to implement all the methods specified in VersatileCollectionsStrictlyTypedCollectionInterface and make sure you call the checkType(mixed $item) method in every method where you add items to or modify items in the collection such as offsetSet($key, $val) and throw an VersatileCollectionsExceptionsInvalidItemException exception whenever checkType(mixed $item) returns false. If you use VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait in your custom collection class but add new methods that also add items to or modify items in the collection you can use the helper method isRightTypeOrThrowInvalidTypeException($item, $calling_functions_name) provided in VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait to validate items (it will automatically throw an exception for you if the item you are validating is of the wrong type; see VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait::offsetSet($key, $val) for an example of how this helper method should be used).
You can optionally override StrictlyTypedCollectionInterfaceImplementationTrait::__construct(mixed ...$arr_objs) with a constructor with the same signature but with the specific type. For example, __construct(PDO ...$pdo_objs) ensures that only instances of PDO can be injected into the constructor via argument unpacking.
The code example below shows how a custom collection class called PdoCollection, that only stores items that are instances of PDO, can be implemented:
<?php
use VersatileCollectionsStrictlyTypedCollectionInterface;
class PdoCollection implements StrictlyTypedCollectionInterface { //1. Implement interface
use VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait; //2. Use trait
public function __construct(PDO ...$pdo_objs) { //3. Optionally override the constructor with a type
// specific one
$this->versatile_collections_items = $pdo_objs;
}
/**
*
* @return bool true if $item is of the expected type, else false
*
*/
public function checkType(mixed $item): bool { //4. implement interface methods not implemented in trait above
return ($item instanceof PDO);
}
/**
*
* @return string|array a string or array of strings of type name(s)
* for items acceptable in instances of this
* collection class
*
*/
public function getTypes(): VersatileCollectionsStringsCollection { //4. implement interface methods not implemented in trait above
return new VersatileCollectionsStringsCollection(PDO::class);
}
}You can declare your custom typed collection classes as final so that users of your classes will not be able to extend them and thereby circumvent the type-checking being enforced at construct time and item addition time.
NOTE: If you only want to store items that are only instances of a specific class or its sub-classes in a collection and don't want to have to create a custom collection class for that purpose, simply use SpecificObjectsCollection
Methods Glossary by Category
Methods Descriptions with Examples
Generic Collections
Strictly Typed Collections
Laravel Collection Methods Equivalence
Please submit an issue or a pull request if you find any issues with the documentation.
