Collection Library.

Provides a Collection container with no dependencies on any framework code. The collection is a wrapper around a standard array with many helper methods. It sits somewhere between a Laravel Collection and the Doctrine ArrayCollection and takes ideas from both of those as well as others.

Article image for: Collection Library

Usage & Factories.

Usage & Factories

Github Print


Instantiate with an array or other collection of items:

$collection = MutableCollection::collect($items);

Freeze changes to a collection:

$locked = $collection->freeze();

// raises exception

Use a custom Immutable collection class:

$locked = $collection->freeze();

// raises exception

Dot Access

Dot access is available on:

  • 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:

  • 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.

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.

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.

Proxy Helpers

From 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.

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.

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.

The proxy can be called by:

  • $collection->proxy(<alias>)->someMethod()
  • $collection-><alias>->someMethod()

For example: to run the method setDateTo() on a collection of objects that have this method:

  • $collection->run->setDateTo(new DateTime()) or
  • $collection->proxy('run')->setDateTo(new DateTime())

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