Simple collection class for added type safety where needed.

Installs: 2 332

Dependents: 1

Suggesters: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

3.0.1 2015-10-27 19:43 UTC


Simple collection class for added type safety where needed.


All of my components require PHP >= 5.5.


Use Composer to install: composer require ts/collection:~3.0

Using the default collection

Expected value type gets set when the first item is added to the default implementation:

use TS\Collection\Collection;

// Create collection
$coll = new Collection;

// Collection accepts only stdClass objects afterwards
$coll->add(new stdClass);

// Throws an Exception
$coll->add(new someClass);

// Create collections from arrays
$coll = Collection::fromArray([new stdClass, new stdClass]);

// Throws an Exception
$coll = Collection::fromArray([new stdClass, new someClass]);

Rolling your own: Extending the base collection

When extending the base collection class and expecting a certain type of items, overwrite the expectsType method, which should return the fully qualified class name of the type your collection should accept:

class MyCollection extends TS\Collection\Collection
    protected function expectsType()
        return 'stdClass';

$coll = new MyCollection;

// Still works fine
$coll->add(new stdClass);

// Throws an Exception
$coll->add(new someClass);

Strict typing

The collection class doesn't differentiate between base and child classes of a type by default.

To prevent child classes from being put into a collection, set the protected $mode property to one of the type safety modes defined in the TypeSafetyMode class:

use TS\Collection\Collection;
use TS\Collection\TypeSafetyMode;

class MyCollection extends Collection
    protected $expectedType = 'stdClass';

    protected $mode = TypeSafetyMode::STRICT;

// Note how this differs from the previous example:
// someClass extends stdClass this time and would be a valid parameter in the default type safety mode
class someClass extends stdClass {}

$coll = new MyCollection();

// Fine
$coll->add(new stdClass);

// Throws an Exception
$coll->add(new someClass);


use TS\Collection\Collection;

$john = (object) ['name' => 'John'];
$jane = (object) ['name' => 'Jane'];

$coll1 = new Collection;

$coll2 = new Collection;

$merged = $coll1->mergeWith($coll2);

$merged->contains($john); // true
$merged->contains($jane); // true


Collection::filter() expects a PHP callable with a collection item as its parameter.

use TS\Collection\Collection;

$john  = (object) ['name' => 'John'];
$james = (object) ['name' => 'James'];

$coll = new Collection;

$filtered = $coll->filter(
    function ($item) {
        if (strlen($item->name) <= 4) {
            return $item;

$filtered->contains($john);  // true
$filtered->contains($james); // false

Further manipulation

The collection class inherits from Doctrine's ArrayCollection, which offers even more functionality like partitioning, mapping, slicing and more, keeping the same interface, but adding type safety checks.