1. class
  2. Ramsey
  3. \
  4. Collection
  5. \
  6. Collection

Collection

class Collection extends AbstractCollection (View source)

A collection represents a group of objects.

Each object in the collection is of a specific, defined type.

This is a direct implementation of CollectionInterface, provided for the sake of convenience.

Example usage:

$collection = new \Ramsey\Collection\Collection('My\\Foo');
$collection->add(new \My\Foo());
$collection->add(new \My\Foo());

foreach ($collection as $foo) {
    // Do something with $foo
}

It is preferable to subclass AbstractCollection to create your own typed collections. For example:

namespace My\Foo;

class FooCollection extends \Ramsey\Collection\AbstractCollection
{
    public function getType()
    {
        return 'My\\Foo';
    }
}

And then use it similarly to the earlier example:

$fooCollection = new \My\Foo\FooCollection();
$fooCollection->add(new \My\Foo());
$fooCollection->add(new \My\Foo());

foreach ($fooCollection as $foo) {
    // Do something with $foo
}

The benefit with this approach is that you may do type-checking on the collection object:

if ($collection instanceof \My\Foo\FooCollection) {
    // the collection is a collection of My\Foo objects
}

Traits

TypeTrait
Provides functionality to check values for specific types.
ValueToStringTrait
Provides functionality to express a value as string
ValueExtractorTrait
Provides functionality to extract the value of a property or method from an object.

Properties

protected array $data The items of this array. from AbstractArray

Methods

__construct(string $collectionType, array $data = [])

Constructs a collection object of the specified type, optionally with the specified data.

Traversable
getIterator()

Returns an iterator for this array.

from AbstractArray
bool
offsetExists(mixed $offset)

Returns true if the given offset exists in this array.

from AbstractArray
mixed|null
offsetGet(mixed $offset)

Returns the value at the specified offset.

from AbstractArray
void
offsetSet(mixed|null $offset, mixed $value)

Sets the given value to the given offset in the array.

from AbstractCollection
void
offsetUnset(mixed $offset)

Removes the given offset and its value from the array.

from AbstractArray
string
serialize()

Returns a serialized string representation of this array object.

from AbstractArray
void
unserialize(string $serialized)

Converts a serialized string representation into an instance object.

from AbstractCollection
int
count()

Returns the number of items in this array.

from AbstractArray
void
clear()

Removes all items from this array.

from AbstractArray
array
toArray()

Returns a native PHP array representation of this array object.

from AbstractArray
bool
isEmpty()

Returns true if this array is empty.

from AbstractArray
bool
checkType(string $type, mixed $value)

Returns true if value is of the specified type.

from TypeTrait
string
toolValueToString(mixed $value)

Returns a string representation of the value.

from ValueToStringTrait
mixed
extractValue(object $object, string $propertyOrMethod)

Extracts the value of the given property or method from the object.

from ValueExtractorTrait
bool
add(mixed $element)

Ensures that this collection contains the specified element.

from AbstractCollection
bool
contains(mixed $element, bool $strict = true)

Returns true if this collection contains the specified element.

from AbstractCollection
bool
remove(mixed $element)

Removes a single instance of the specified element from this collection, if it is present.

from AbstractCollection
array
column(string $propertyOrMethod)

Returns the values from given property or method.

from AbstractCollection
mixed
first()

Returns the first item of the collection.

from AbstractCollection
mixed
last()

Returns the last item of the collection.

from AbstractCollection
CollectionInterface
sort(string $propertyOrMethod, string $order = self::SORT_ASC)

Returns a sorted collection.

from AbstractCollection
CollectionInterface
filter(callable $callback)

Returns a filtered collection.

from AbstractCollection
CollectionInterface
where(string $propertyOrMethod, mixed $value)

Returns a collection of matching items.

from AbstractCollection
CollectionInterface
map(callable $callback)

Applies a callback to each item of the collection.

from AbstractCollection
CollectionInterface
diff(CollectionInterface $other)

Create a new collection with divergent items between current and given collection.

from AbstractCollection
CollectionInterface
intersect(CollectionInterface $other)

Create a new collection with intersecting item between current and given collection.

from AbstractCollection
CollectionInterface
merge(CollectionInterface ...$collections)

Merge current items and items of given collections into a new one.

from AbstractCollection
string
getType()

Returns the type associated with this collection.

Details

at line 93
__construct(string $collectionType, array $data = [])

Constructs a collection object of the specified type, optionally with the specified data.

Parameters

string $collectionType The type (FQCN) associated with this collection.
array $data The initial items to add to this array.

in AbstractArray at line 51
Traversable getIterator()

Returns an iterator for this array.

Return Value

Traversable

in AbstractArray at line 65
bool offsetExists(mixed $offset)

Returns true if the given offset exists in this array.

Parameters

mixed $offset The offset to check.

Return Value

bool

in AbstractArray at line 80
mixed|null offsetGet(mixed $offset)

Returns the value at the specified offset.

Parameters

mixed $offset The offset for which a value should be returned.

Return Value

mixed|null the value stored at the offset, or null if the offset does not exist.

in AbstractCollection at line 75
void offsetSet(mixed|null $offset, mixed $value)

Sets the given value to the given offset in the array.

Parameters

mixed|null $offset The offset to set. If null, the value may be set at a numerically-indexed offset.
mixed $value The value to set at the given offset.

Return Value

void

Exceptions

InvalidArgumentException when the value does not match the specified type for this collection.

in AbstractArray at line 110
void offsetUnset(mixed $offset)

Removes the given offset and its value from the array.

Parameters

mixed $offset The offset to remove from the array.

Return Value

void

in AbstractArray at line 122
string serialize()

Returns a serialized string representation of this array object.

Return Value

string a PHP serialized string.

in AbstractCollection at line 336
void unserialize(string $serialized)

Converts a serialized string representation into an instance object.

Parameters

string $serialized A PHP serialized string to unserialize.

Return Value

void

in AbstractArray at line 146
int count()

Returns the number of items in this array.

Return Value

int

in AbstractArray at line 154
void clear()

Removes all items from this array.

Return Value

void

in AbstractArray at line 164
array toArray()

Returns a native PHP array representation of this array object.

Return Value

array

in AbstractArray at line 174
bool isEmpty()

Returns true if this array is empty.

Return Value

bool

in TypeTrait at line 30
protected bool checkType(string $type, mixed $value)

Returns true if value is of the specified type.

Parameters

string $type The type to check the value against.
mixed $value The value to check.

Return Value

bool

in ValueToStringTrait at line 38
protected string toolValueToString(mixed $value)

Returns a string representation of the value.

  • null value: 'NULL'
  • boolean: 'TRUE', 'FALSE'
  • array: 'Array'
  • scalar: converted-value
  • resource: '(type resource #number)'
  • object with __toString(): result of __toString()
  • object DateTime: ISO 8601 date
  • object: '(className Object)'
  • anonymous function: same as object

Parameters

mixed $value the value to return as a string.

Return Value

string

in ValueExtractorTrait at line 35
protected mixed extractValue(object $object, string $propertyOrMethod)

Extracts the value of the given property or method from the object.

Parameters

object $object The object to extract the value from.
string $propertyOrMethod The property or method for which the value should be extracted.

Return Value

mixed the value extracted from the specified property or method.

Exceptions

ValueExtractionException if the method or property is not defined.

in AbstractCollection at line 46
bool add(mixed $element)

Ensures that this collection contains the specified element.

Parameters

mixed $element The element to add to the collection.

Return Value

bool true if this collection changed as a result of the call.

Exceptions

InvalidArgumentException when the element does not match the specified type for this collection.

in AbstractCollection at line 61
bool contains(mixed $element, bool $strict = true)

Returns true if this collection contains the specified element.

Parameters

mixed $element The element to check whether the collection contains.
bool $strict Whether to perform a strict type check on the value.

Return Value

bool

in AbstractCollection at line 95
bool remove(mixed $element)

Removes a single instance of the specified element from this collection, if it is present.

Parameters

mixed $element The element to remove from the collection.

Return Value

bool true if an element was removed as a result of this call.

in AbstractCollection at line 115
array column(string $propertyOrMethod)

Returns the values from given property or method.

Parameters

string $propertyOrMethod The property or method name to filter by.

Return Value

array

Exceptions

ValueExtractionException if property or method is not defined.

in AbstractCollection at line 133
mixed first()

Returns the first item of the collection.

Return Value

mixed

Exceptions

OutOfBoundsException when the collection is empty.

in AbstractCollection at line 151
mixed last()

Returns the last item of the collection.

Return Value

mixed

Exceptions

OutOfBoundsException when the collection is empty.

in AbstractCollection at line 178
CollectionInterface sort(string $propertyOrMethod, string $order = self::SORT_ASC)

Returns a sorted collection.

{@inheritdoc}

Parameters

string $propertyOrMethod The property or method to sort by.
string $order The sort order for the resulting collection (one of this interface's SORT_* constants).

Return Value

CollectionInterface

Exceptions

InvalidSortOrderException if neither "asc" nor "desc" was given as the order.
ValueExtractionException if property or method is not defined.

in AbstractCollection at line 205
CollectionInterface filter(callable $callback)

Returns a filtered collection.

{@inheritdoc}

Parameters

callable $callback A callable to use for filtering elements.

Return Value

CollectionInterface

in AbstractCollection at line 225
CollectionInterface where(string $propertyOrMethod, mixed $value)

Returns a collection of matching items.

{@inheritdoc}

Parameters

string $propertyOrMethod The property or method to evaluate.
mixed $value The value to match.

Return Value

CollectionInterface

Exceptions

ValueExtractionException if property or method is not defined.

in AbstractCollection at line 244
CollectionInterface map(callable $callback)

Applies a callback to each item of the collection.

{@inheritdoc}

Parameters

callable $callback A callable to apply to each item of the collection.

Return Value

CollectionInterface

in AbstractCollection at line 264
CollectionInterface diff(CollectionInterface $other)

Create a new collection with divergent items between current and given collection.

Parameters

CollectionInterface $other The collection to check for divergent items.

Return Value

CollectionInterface

Exceptions

CollectionMismatchException if the given collection is not of the same type.

in AbstractCollection at line 292
CollectionInterface intersect(CollectionInterface $other)

Create a new collection with intersecting item between current and given collection.

Parameters

CollectionInterface $other The collection to check for intersecting items.

Return Value

CollectionInterface

Exceptions

CollectionMismatchException if the given collection is not of the same type.

in AbstractCollection at line 314
CollectionInterface merge(CollectionInterface ...$collections)

Merge current items and items of given collections into a new one.

Parameters

CollectionInterface ...$collections The collections to merge.

Return Value

CollectionInterface

Exceptions

CollectionMismatchException if any of the given collections are not of the same type.

at line 104
string getType()

Returns the type associated with this collection.

Return Value

string