Collection
extends AbstractCollection
in package
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
}
Tags
Table of Contents
- $data : array<array-key, T>
- The items of this array.
- $collectionType : string
- The type of elements stored in this collection.
- __construct() : mixed
- Constructs a collection object of the specified type, optionally with the specified data.
- __serialize() : array<array-key, T>
- Returns data suitable for PHP serialization.
- __unserialize() : void
- Adds unserialized data to the object.
- add() : bool
- Ensures that this collection contains the specified element (optional operation).
- clear() : void
- Removes all items from this array.
- column() : array<int, mixed>
- Returns the values from the given property or method.
- contains() : bool
- Returns `true` if this collection contains the specified element.
- count() : int
- Returns the number of items in this array.
- diff() : CollectionInterface<string|int, T>
- Create a new collection with divergent items between current and given collection.
- filter() : CollectionInterface<string|int, T>
- Filter out items of the collection which don't match the criteria of given callback.
- first() : T
- Returns the first item of the collection.
- getIterator() : Traversable<array-key, T>
- Returns an iterator for this array.
- getType() : string
- intersect() : CollectionInterface<string|int, T>
- Create a new collection with intersecting item between current and given collection.
- isEmpty() : bool
- Returns `true` if this array is empty.
- last() : T
- Returns the last item of the collection.
- map() : CollectionInterface<string|int, TCallbackReturn>
- Apply a given callback method on each item of the collection.
- merge() : CollectionInterface<string|int, T>
- Merge current items and items of given collections into a new one.
- offsetExists() : bool
- Returns `true` if the given offset exists in this array.
- offsetGet() : T|null
- Returns the value at the specified offset.
- offsetSet() : void
- Sets the given value to the given offset in the array.
- offsetUnset() : void
- Removes the given offset and its value from the array.
- remove() : bool
- Removes a single instance of the specified element from this collection, if it is present.
- serialize() : string
- Returns a serialized string representation of this array object.
- sort() : CollectionInterface<string|int, T>
- Sort the collection by a property or method with the given sort order.
- toArray() : array<array-key, T>
- Returns a native PHP array representation of this array object.
- unserialize() : void
- Converts a serialized string representation into an instance object.
- where() : CollectionInterface<string|int, T>
- Create a new collection where items match the criteria of given callback.
- checkType() : bool
- Returns `true` if value is of the specified type.
- extractValue() : mixed
- Extracts the value of the given property or method from the object.
- toolValueToString() : string
- Returns a string representation of the value.
- compareCollectionTypes() : void
- getComparator() : Closure
Properties
$data
The items of this array.
protected
array<array-key, T>
$data
= []
$collectionType
The type of elements stored in this collection.
private
string
$collectionType
A collection's type is immutable once it is set. For this reason, this property is set private.
Methods
__construct()
Constructs a collection object of the specified type, optionally with the specified data.
public
__construct(string $collectionType[, array<array-key, T> $data = [] ]) : mixed
Parameters
- $collectionType : string
-
The type (FQCN) associated with this collection.
- $data : array<array-key, T> = []
-
The initial items to store in the collection.
Return values
mixed —__serialize()
Returns data suitable for PHP serialization.
public
__serialize() : array<array-key, T>
Tags
Return values
array<array-key, T> —__unserialize()
Adds unserialized data to the object.
public
__unserialize(array<array-key, T> $data) : void
Parameters
- $data : array<array-key, T>
Return values
void —add()
Ensures that this collection contains the specified element (optional operation).
public
add(mixed $element) : bool
Parameters
- $element : mixed
-
The element to add to the collection.
Tags
Return values
bool —true if this collection changed as a result of the call.
clear()
Removes all items from this array.
public
clear() : void
Return values
void —column()
Returns the values from the given property or method.
public
column(string $propertyOrMethod) : array<int, mixed>
Parameters
- $propertyOrMethod : string
-
The property or method name to filter by.
Tags
Return values
array<int, mixed> —contains()
Returns `true` if this collection contains the specified element.
public
contains(mixed $element[, bool $strict = true ]) : bool
Parameters
- $element : mixed
-
The element to check whether the collection contains.
- $strict : bool = true
-
Whether to perform a strict type check on the value.
Tags
Return values
bool —count()
Returns the number of items in this array.
public
count() : int
Tags
Return values
int —diff()
Create a new collection with divergent items between current and given collection.
public
diff(CollectionInterface $other) : CollectionInterface<string|int, T>
Parameters
- $other : CollectionInterface
-
The collection to check for divergent items.
Return values
CollectionInterface<string|int, T> —filter()
Filter out items of the collection which don't match the criteria of given callback.
public
filter(callable $callback) : CollectionInterface<string|int, T>
This will always leave the original collection untouched and will return a new one.
See the PHP array_filter() documentation
for examples of how the $callback parameter works.
Parameters
- $callback : callable
Return values
CollectionInterface<string|int, T> —first()
Returns the first item of the collection.
public
first() : T
Tags
Return values
T —getIterator()
Returns an iterator for this array.
public
getIterator() : Traversable<array-key, T>
Tags
Return values
Traversable<array-key, T> —getType()
public
getType() : string
Return values
string —intersect()
Create a new collection with intersecting item between current and given collection.
public
intersect(CollectionInterface $other) : CollectionInterface<string|int, T>
Parameters
- $other : CollectionInterface
-
The collection to check for intersecting items.
Return values
CollectionInterface<string|int, T> —isEmpty()
Returns `true` if this array is empty.
public
isEmpty() : bool
Return values
bool —last()
Returns the last item of the collection.
public
last() : T
Tags
Return values
T —map()
Apply a given callback method on each item of the collection.
public
map(callable $callback) : CollectionInterface<string|int, TCallbackReturn>
This will always leave the original collection untouched. The new collection is created by mapping the callback to each item of the original collection.
See the PHP array_map() documentation
for examples of how the $callback parameter works.
Parameters
- $callback : callable
Return values
CollectionInterface<string|int, TCallbackReturn> —merge()
Merge current items and items of given collections into a new one.
public
merge(CollectionInterface ...$collections) : CollectionInterface<string|int, T>
Parameters
- $collections : CollectionInterface
-
The collections to merge.
Return values
CollectionInterface<string|int, T> —offsetExists()
Returns `true` if the given offset exists in this array.
public
offsetExists(string|int $offset) : bool
Parameters
- $offset : string|int
-
The offset to check.
Tags
Return values
bool —offsetGet()
Returns the value at the specified offset.
public
offsetGet(string|int $offset) : T|null
Parameters
- $offset : string|int
-
The offset for which a value should be returned.
Tags
Return values
T|null —the value stored at the offset, or null if the offset does not exist.
offsetSet()
Sets the given value to the given offset in the array.
public
offsetSet(string|int|null $offset, T $value) : void
Parameters
- $offset : string|int|null
-
The offset to set. If
null, the value may be set at a numerically-indexed offset. - $value : T
-
The value to set at the given offset.
Tags
Return values
void —offsetUnset()
Removes the given offset and its value from the array.
public
offsetUnset(string|int $offset) : void
Parameters
- $offset : string|int
-
The offset to remove from the array.
Tags
Return values
void —remove()
Removes a single instance of the specified element from this collection, if it is present.
public
remove(mixed $element) : bool
Parameters
- $element : mixed
-
The element to remove from the collection.
Tags
Return values
bool —true if an element was removed as a result of this call.
serialize()
Returns a serialized string representation of this array object.
public
serialize() : string
Tags
Return values
string —a PHP serialized string.
sort()
Sort the collection by a property or method with the given sort order.
public
sort(string $propertyOrMethod[, string $order = self::SORT_ASC ]) : CollectionInterface<string|int, T>
This will always leave the original collection untouched and will return a new one.
Parameters
- $propertyOrMethod : string
-
The property or method to sort by.
- $order : string = self::SORT_ASC
-
The sort order for the resulting collection (one of this interface's
SORT_*constants).
Return values
CollectionInterface<string|int, T> —toArray()
Returns a native PHP array representation of this array object.
public
toArray() : array<array-key, T>
Tags
Return values
array<array-key, T> —unserialize()
Converts a serialized string representation into an instance object.
public
unserialize(string $serialized) : void
Parameters
- $serialized : string
-
A PHP serialized string to unserialize.
Tags
Return values
void —where()
Create a new collection where items match the criteria of given callback.
public
where(string $propertyOrMethod, mixed $value) : CollectionInterface<string|int, T>
Parameters
- $propertyOrMethod : string
-
The property or method to evaluate.
- $value : mixed
-
The value to match.
Return values
CollectionInterface<string|int, T> —checkType()
Returns `true` if value is of the specified type.
protected
checkType(string $type, mixed $value) : bool
Parameters
- $type : string
-
The type to check the value against.
- $value : mixed
-
The value to check.
Return values
bool —extractValue()
Extracts the value of the given property or method from the object.
protected
extractValue(mixed $object, string $propertyOrMethod) : mixed
Parameters
- $object : mixed
-
The object to extract the value from.
- $propertyOrMethod : string
-
The property or method for which the value should be extracted.
Tags
Return values
mixed —the value extracted from the specified property or method.
toolValueToString()
Returns a string representation of the value.
protected
toolValueToString(mixed $value) : string
- 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
- $value : mixed
-
the value to return as a string.
Return values
string —compareCollectionTypes()
private
compareCollectionTypes(CollectionInterface<string|int, T> $other) : void
Parameters
- $other : CollectionInterface<string|int, T>
Return values
void —getComparator()
private
getComparator() : Closure