Somnambulist Collection Library
, (*1)
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., (*2)
The basic "Collection" is an interface that extends ArrayAccess, IteratorAggregate and Countable;
and adds Arrayable and Jsonable as common requirements. Then the basic methods are:, (*3)
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., (*4)
Of course out of the box, several standard implementations are included., (*5)
This is heavily inspired by Doctrine ArrayCollection and of course Laravel Collection along
with ideas from Lithium framework, ez Components, CakePHP and more., (*6)
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!, (*7)
Change History
Requirements
- PHP 8.0+
- ext-json for JSON export
Installation
Install using composer, or checkout / pull the files from github.com., (*8)
- composer require somnambulist/collection
Contributing
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., (*9)
Please consider the following:, (*10)
- the minimum version of PHP is 8.0
- 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., (*11)
Built-in Collections
There are several types of collection that all implement the Collection interface with varying
levels of functionality:, (*12)
- 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., (*13)
Usage
Instantiate with an array or other collection of items:, (*14)
$collection = MutableCollection::collect($items);
$collection->map()->filter()...
Freeze changes to a collection:, (*15)
$locked = $collection->freeze();
// raises exception
$locked->shift();
Use a custom Immutable collection class:, (*16)
MutableCollection::setFreezeableClass();
$locked = $collection->freeze();
// raises exception
$locked->shift();
Dot Access
Dot access is available on:, (*17)
- has*
- get
- extract
- aggregate functions
For example: users.*.name would fetch the name from all elements in the users key space. Dot access
can call into:, (*18)
- arrays
- Collections
- public object properties
- object return methods e.g.:
name would be translated to name()
- object
get methods e.g: name would be translated to getName()
If the key name uses snake casing e.g.: user_address, this will be converted to UserAddress for method
access checks., (*19)
A default can be supplied with get() that if the specified key does not exist, it will be used instead.
The default can be a closure. Note: that this will be called for all elements e.g: users.*.age with a
default that returned 0, would return 0 for all matching users without an age present., (*20)
Key walking is implemented in a standalone class allowing it to be re-used in other classes. This functionality
is based on Laravel's data_get() and Arr::pluck(), modified to support getter methods and default handling
when extracting from objects., (*21)
Proxy Helpers
New in v4 is an expansion of the run/map proxies used to make operations across the set. Now additional
proxies can be bound to virtual properties that can be accessed at runtime. This allows for additional
custom behaviour or the creation of mini Domain Specific Languages within the collection., (*22)
It is recommended when adding additional proxy options, that this is done in a child class of the collection
so that the options can be documented using @property-read declarations in the class docblock. By default
run and map are pre-bound in the built-in collections, however these can be overridden if necessary., (*23)
Proxies are lazy instantiated when accessed so should have a minimal impact on performance. For most cases
the proxy is mapped by the full qualified class name to an alias, but for more complex construction a closure
can be used., (*24)
The proxy can be called by:, (*25)
$collection->proxy(<alias>)->someMethod()$collection-><alias>->someMethod()
For example: to run the method setDateTo() on a collection of objects that have this method:, (*26)
-
$collection->run->setDateTo(new DateTime()) or
$collection->proxy('run')->setDateTo(new DateTime())
Method Index
The collection behaviour docs are generated from the source code and are available in the docs folder., (*27)
Factory Methods
On the collection class
-
collect() create a new Collection statically
-
create() create a new Collection statically
As helpers in the FactoryUtils
-
createFromIniString() create a Collection from an ini style string
-
createFromString() split an encoded string into a Collection
-
createFromUrl() given a URL returns a Collection after using parse_url()
-
createFromUrlQuery() converts a URL query string to a Collection using parse_str()
-
createWithNestedArrayFromKey converts a key like user.addresses.home to a nested collection
-
explode() explode a string into a Collection
Methods by Group
| Aggregates |
Assertable |
Comparable |
Exportable |
Filterable |
Mappable |
| average |
assert |
diff |
jsonSerialize |
filter |
collapse |
| max |
diffUsing |
toArray |
matching |
flatMap |
| median |
diffAssoc |
toJson |
notMatching |
flatten |
| min |
diffAssocUsing |
toQueryString |
reject |
map |
| modal |
diffKeys |
toString |
except |
mapInto |
| sum |
diffKeysUsing |
serialize |
has |
reduce |
| countBy |
intersect |
unserialize |
hasAllOf |
| intersectByKeys |
hasAnyOf |
| hasNoneOf |
| keys |
| keysMatching |
| only |
| with |
| without |
| matchingRule |
| Mutable |
Partitionable |
Queryable |
Runnable |
String Helpers |
| add |
groupBy |
all |
each |
capitalize |
| append |
partition |
contains |
pipe |
lower |
| concat |
slice |
doesNotContain |
pipeline |
trim |
| combine |
splice |
extract |
run |
upper |
| clear |
find |
| combine |
findLast |
| fill |
first |
| fillKeysWith |
get |
| flip |
last |
| merge |
has |
| pad |
random |
| pop |
removeEmpty |
| prepend |
removeNulls |
| push |
sort |
| remapKeys |
sortBy |
| remove |
value |
| replace |
values |
| replaceRecursively |
| reverse |
| set |
| shift |
| shuffle |
| union |
| unset |
| when |
Magic Methods & PHP Interface Methods
- getIterator
- offsetGet
- offsetExists
- offsetSet
- offsetUnset
- __get
- __isset
- __set
- __set_state
- __unset
Wallogit.com
