yvoyer / collection

Different implementation of collections in php.

collection

Master:

Develop:

Library that offer multiple implementations of collection.

Installation

To install the package using [composer] (https://getcomposer.org/), you just need to add the following lines to your composer.json file.

...
"require": {
    "star/collection": "~1.2"
}
...

Supported collection

Enumeration

Wrap an immutable array of values in an object. Ensuring that any value passed to the enumeration is supported by the instance.

$enumeration = new Enumeration(array(1,2,3));
$enumeration->getSelected(); // returns null
$enumeration->select(2);
$enumeration->getSelected(); // returns 2
$enumeration->select('invalid'); // Throw Exception

Typed Collection

Wraps a collection of a specific kind of object (class or interface). If a value not supported by the collection is given, the collection throws exceptions.

Basic usage

$collection = new TypedCollection('\stdClass');
$collection->add(2); // Throw exception
$collection->add(new \stdClass()); // works

$collection = new TypedCollection('\Countable');
$collection->add(2); // Throw exception
$collection->add(new ClassThatImplementsCountable()); // works

Advanced usage

Using composition

Lets say that you want a Car collection, you could just define it using the basic usage, but it would lead to code duplication. So a good practice would be to define a new class named CarCollection, and use composition instead of inheritance, and declare it like this:

class CarCollection
{
    private $collection;

    public function __construct()
    {
        $this->collection = new TypedCollection('tests\Star\Component\Collection\Example\Car');
    }
}

Declaring your collection like this will enable you to encapsulate logic relevant to the car collection at one place, instead of risking to expose the inner implementation to the outside world. That way, you can control what methods are available and avoid duplication.

Using this example, adding a Car to the collection would be easy by implementing the addCar method.

class CarCollection
{
    ...
    public function addCar(Car $car)
    {
        $this->collection->add($car);
    }
    ...
}

And, if you want to filter all the cars based on their color, you can internally use it like this:

class CarCollection
{
    ...
    public function findAllCarWithColor(Color $color)
    {
        $closure = function(Car $car) use ($color) {
            return $car->getColor() == $color;
        };

        return $this->collection->filter($closure)->toArray();
    }
    ...
}

The same could also be done for finding cars based on their name:

class CarCollection
{
    ...
    public function findAllWithName($name)
    {
        $expression = Criteria::expr()->eq('name', $name);
        $criteria = new Criteria($expression);

        return $this->collection->matching($criteria)->toArray();
    }
    ...
}

From now on, your collection is re-usable, and testable at one place, while avoiding the pitfalls of inheritance.

Using Inheritance

class PassengerCollection extends TypedCollection
{
    ...
    public function findAllWithName($name)
    {
        $expression = Criteria::expr()->eq('name', $name);
        $criteria = new Criteria($expression);

        return $this->matching($criteria)->toArray();
    }
    ...
}

Using Doctrine

This class can be used in conjunction with doctrine/dbal as an added functionality, but you need to make sure that the following steps are respected.

• The custom collection should inherit from the TypedCollection which implement the Doctrine\Common\Collections\Collection.

• The collection attribute will be replaced by a Doctrine\ORM\PersistentCollection when hydrated, instead of the CustomCollection, event thought the collection is instanciated in the construct. To bypass this feature, any method that sould return a CustomCollection should be implemented like this:

  class Entity { // CustomCollection that can be hydrated with a PersistentCollection by Doctrine private $myElements;

    public function __construct()
    {
        $this->myElements = new CustomCollection('stdClass');
    }
  
    public function getElements()
    {
        // At this point $this->myElements could be a Persistent collection
        return new CustomCollection($this->myElements->toArray());
    }
  

  }

collection's Issues

Typed collection

Instance of certain type only

Enumeration

Create a class that contains an array of fixed values.

Example of usage:

$collection = new ArrayCollection(array('val1', 'val2'));
$collection->add('val1'); // ok
$collection->add('val2'); // ok
$collection->add('val13); // Throw exception

Protected supported values

Read-only collection

No changes can be made, once the collection is locked

Add documentation on how to implement doctrine collection

When loading an entity with doctrine, the TypeCollection is not automaticly mapped.

Check the options to implement it the clean way.

• Use a lafecycle callback to recreate the collection with the type.

collection object protected getter into TypedCollection?

Hi,
Is it possible to add a protected getter of the "collection" attribute from the TypedCollection class? It'll be helpfull ;)
In fact, I can get a same object this way (if my class extends TypedCollection):
$collection = new ArrayCollection($this->getValues());

Add collection that can be extended easilly

Extending the TypedCollection means that we have to override the construct, doing so breaks the static creation on the filter, partition and matching methods.

We should have a way to specify the arguments on the contruct...

Ex.

SomeCollection
{
    public function __construct($dep1, $dep2, $dep3)
    {
        parent::__construct('SomeClass');
    }
}

SomeOtherCollection
{
    public function __construct($dep1)
    {
        parent::__construct('SomeClass');
    }
}

Both cases should work

Add a mapped item return anything else than Class

when using the TypedCollection::map() that returns anything else than the class, it silently filter out some rows. Instead of filtering out, it should throw an exception to explicitly tell the user the map do not support returning other values.

hash collection

String index

Array collection

Use our own interface

Set collection

Set