Somnambulist Collection provides a framework for making collections and pseudo sets of your own. It has been completely re-worked from the previous versions into a set of behaviours (traits) and some common interfaces grouped around function.
The basic "Collection" is an interface that extends ArrayAccess, IteratorAggregate and Countable; and adds Arrayable and Jsonable as common requirements. The basic methods are:
public function all(): array; public function contains($value): bool; public function doesNotContain($value): bool; public function each(callable $callback); public function filter($criteria = null); public function first(); public function get($key, $default = null); public function has(...$key): bool; public function keys($search = null); public function last(); public function map(callable $callable); public function value($key, $default = null); public function values();
From this, additional functionality is added by interface and traits - or implement your own. The goal is to allow for a set of small, re-usable, well tested functions that can be combined to provide the functionality you need, instead of a single monolithic collection class that does everything and more.
Of course out of the box, several standard implementations are included.
This is heavily inspired by Doctrine ArrayCollection and of course Laravel Collection along with ideas from Lithium framework, ez Components, CakePHP and more.
If you see something missing or have suggestions for other methods, submit a PR or ticket! Adding functions is easy with the trait system and if you think that the groupings need work, suggest a better name!
For the change history, please see the library repository.
- PHP 7.4+
- ext-json for JSON export
Install using composer, or checkout / pull the files from github.com.
composer require somnambulist/collection
Contributions are more than welcome! Whether doc improvements, new methods or bug fixes. In all cases, fork the repository, make a branch then submit a PR - the usual GitHub flow.
Please consider the following:
- the minimum version of PHP is 7.4
- traits should not specify a return type but must include a docblock return type
- return types for the Collection must be `static` to allow runtime resolution
- all trait methods must have docblocks - these are converted to docs
- if a trait uses code from elsewhere, it should be attributed whenever possible
- consider the type of operation and if it will work in a Set or a Frozen collection
- tests should be included
Remember that the Collection could be a Set or Frozen, so often it is necessary to operate on the values and then create a new collection after processing. See the current implementations for examples.
There are several types of collection that all implement the Collection interface with varying levels of functionality:
- SimpleCollection - a very basic, Doctrine ArrayCollection like style collection
- MutableCollection - more like Laravel Collection, supports dot notation accessing
- FrozenCollection - more like a Symfony Frozen ParameterBag, but more, with dot notation
- MutableSet - a pseudo set that does not allow duplicate values, but does allow string keys.
There's no frozen set, but if you freeze a MutableSet; you have yourself a FrozenSet.