Collections make easy to work with array of items. They have fluent interface and most of their methods return an entirely new collection instance.
Represents a collection of a set of key and value pairs. Values can be mixed.
Interfaces implemented:
use Yosymfony\Collection\MixedCollection;
$collection = new MixedCollection([
'users' => [
'victor' => [
'name' => 'Víctor',
'age' => 30,
],
],
]);
$name = $collection->getDot('users.victor.age');
// 30You can use collections as if they were arrays:
$collection = new MixedCollection([1,2,3]);
print $collection[0];
// 1
foreach($collection as $number) {
print $number;
}
// 1
// 2
// 3Adds a new key to the collection.
$collection = new MixedCollection(['user' => 'Victor']);
$collection->add('github-user', 'yosymfony')->all();
// ['user' => 'Victor', 'github-user' => 'yosymfony']An exception KeyAddedPreviouslyException will be thrown if the key was added previously.
Related methods: addValue, addRangeOfValues.
Adds a value to the collection.
$collection = new MixedCollection(['a']);
$collection->addValue('b')->all();
// ['a', 'b']Related methods: add, addRangeOfValues.
Adds a range of values to the collection.
$collection = new MixedCollection(['a']);
$collection->addRangeOfValues(['b', 'c'])->all();
// ['a', 'b', 'c']Related methods: add, addValue.
Returns all the items in the collection.
$collection = new MixedCollection([1,2,3]);
$collection->all();
// [1,2,3]Finds out if at least one item in the collection pass the given test expressed as a callback.
$collection = new MixedCollection([1,2,3]);
$collection->any(function ($item) {
return > 0;
});
// trueThe callback function has the following signature: function (mixed $item) : bool
Related methods: every, where.
Clears all elements in this collection.
$collection = new MixedCollection([1,2,3]);
$collection->clear()->all();
// []Related method: remove.
Creates a new collection instance. If an item is a Collection, its copy method will be invoked.
$collection = new MixedCollection([1,2,3]);
$newCollection = $collection->copy();
// [1,2,3]Finds out if all items pass the given test expressed as a callback.
$collection = new MixedCollection([1,2,3]);
$collection->every(function ($item) {
return > 2;
});
// falseThe callback function has the following signature: function (mixed $item) : bool
Returns a collection with all items except for those with specified keys.
$collection = new MixedCollection(['user' => 'victor', 'last_change' => '2018-10-14', 'role' => 'user']);
$filtered = $collection->except(['last_change', 'role']);
$fileted->all();
// ['user' => 'victor'] Returns the first element in the collection or the default value if the collection is empty.
$collection = new MixedCollection(['user' => 'victor', 'role' => 'user']);
$value = $collection->first();
// 'victor'The default value is null. You may optionally pass a default value as argument:
$collection = new MixedCollection();
$value = $collection->first('default-value');
// 'default-value'Related method: last.
Returns the value associated with the key.
$collection = new MixedCollection(['user' => 'victor', 'github-user' => 'yosymfony']);
$value = $collection->get('user');
// victorIf the key is not register in the collection a KeyNotFoundException will be thrown.
If you want to get a default value in case the key does not exists in the collection, use the method getOrDefault.
Related methods: getOnly, getOrDefault, getDot.
Returns a new collection with the items associated with the specified keys. If a key does not exists in the collection, it will be ignored.
$collection = new MixedCollection(['user' => 'victor', 'github-user' => 'yosymfony', 'country' => 'Spain']);
$values = $collection->getOnly(['user', 'country']);
$values->all();
// ['user' => 'victor', 'country' => 'Spain']Related methods: get, getOrDefault, getDot.
Returns the value associated with the key or default value in case the key does not exists.
$collection = new MixedCollection(['user' => 'victor', 'github-user' => 'yosymfony']);
$value = $collection->getOrDefault('user');
// victorYou may optionally pass a default value as the second argument:
$collection = new MixedCollection(['user' => 'victor', 'github-user' => 'yosymfony']);
$value = $collection->getOrDefault('foo', 'default-value');
// default-valueRelated methods: get, getOnly, getDot.
Returns the value at the end of the path or the default value if an element of the path is missing.
$collection = new MixedCollection([
'users' => [
'victor' => new MixedCollection([
'name' => 'Víctor',
'country' => 'Spain',
]),
'alex' => [
'name' => 'Alex',
'country' => 'Spain',
],
],
]);
$victorCountry = $collection->getDot('users.victor.country'));
$alexName = $collection->getDot('users.alex.name'));
// Spain
// AlexYou may optionally pass a default value as the second argument:
$collection = new MixedCollection([
'users' => [
'victor' => new MixedCollection([
'name' => 'Víctor',
'country' => 'Spain',
]),
]
]);
$value = $collection->getDot('users.jack.country', 'unknown-country'));
// unknown-countryRelated methods: get, getOnly, getOrDefault.
Returns a read-only collection.
$collection = new MixedCollection([1,2,3]);
$readOnlyCollection = $collection->getReadOnlyCollection();
$readOnlyCollection->all();
// [1,2,3]Determines if the item with the key exists in the collection.
$collection = new MixedCollection(['user' => 'victor', 'github-user' => 'yosymfony']);
$result = $collection->has('user');
// trueReturns true if the collection is empty.
$collection = new MixedCollection();
$result = $collection->isEmpty();
// trueReturns the intersection of the collection with the given items or collection. The resulting collection will preserve the original collection's keys:
$collection = new MixedCollection(['car', 'bike', 'scooter']);
$intersect = $collection->intersect(['car', 'scooter']);
$intersect->all();
// [0 => 'car', 2 => 'scooter']Related method: union.
Returns a the keys of the collection items.
$collection = new MixedCollection(['user' => 'victor', 'github-user' => 'yosymfony']);
$keys = $collection->keys();
$keys->all();
// ['user', 'github-user']Related method: values.
Returns the last element in the collection or default if the collection is empty.
$collection = new MixedCollection(['user' => 'victor', 'role' => 'user']);
$value = $collection->last();
// 'user'The default value is null. You may optionally pass a default value as argument:
$collection = new MixedCollection();
$value = $collection->last('default-value');
// 'default-value'Related method: firt.
Iterates through the collection and passes each value to the given callback. The callback function can return modify item.
$collection = new MixedCollection([1,2,3]);
$values = $collection->map(function ($item) {
return $item + 1;
});
// [2,3,4]The callback function has the following signature: function(mixed $item) : mixed
Related method: reduce.
Reduces the collection to a single value. The initial value of $carry is null. However, you may
set its value by passing a second argument to reduce.
$collection = new MixedCollection([1,2,3]);
$value = $collection->reduce(function ($carry, $item) {
return $carry + $item;
}, 0);
// 6The callback function has the following signature:
function (mixed $carry, mixed $item, bool $isFirstItem, bool $isLastItem) : mixed
$isFirstItem and $isLastItem let you know when you are handling the first and the last item of the collection.
For example, $isLastItem is useful in case of making a simplification to return the final result.
Related method: map.
Removes an item from the collection.
$collection = new MixedCollection(['user' => 'Victor', 'github-user' => 'yosymfony']);
$collection->remove('github-user');
$collection->all();
// ['user' => 'Victor']Related methods: clear, except.
Returns a new collection with reversed items. This method preserves the original keys.
$collection = new MixedCollection(['a', 'b', 'c']);
$reversed = $collection->reverse();
// [2 => 'c', 1 => 'b', 0 => 'a']Return and removes the first item from the collection.
$collection = new MixedCollection([1,2,3]);
$value = $collection->shift();
// 1
$collection->all();
// [2,3]Sets the given key and value in the collection.
$collection = new MixedCollection(['user' => 'Victor']);
$collection->set('github-user', 'yosymfony');
$collection->all();
// ['user' => 'Victor', 'github-user' => 'yosymfony']Iterates over the collection and calls the given callback with each item in the collection. The items in the collection will be replaced by the values returned by the callback.
$collection = new MixedCollection([1,2,3]);
$collection->transform(function ($item) {
return $item + 1;
});
$collection->all();
// [2,3,4]The callback function has the following signature: function(mixed $item) : mixed
Converts the collection into a plain array.
$collection = new MixedCollection(['a', 'b', 'c']);
$values = $collection->toArray();
// ['a', 'b', 'c']If the collection contains another collections, they will be also converted to array:
$collection = new MixedCollection([
'a',
'b',
'c',
new MixedCollection(['d', 'e']),
]);
$values = $collection->toArray();
// ['a', 'b', 'c', 'd', 'e']Returns the collection of item as JSON.
$collection = new MixedCollection(['name' => 'Victor']);
$value = $collection->toJson();
// '{"name":"Victor"}'Returns the union of the collection with the given items or collection. If the given items contains keys that are already in the original collection, the original collection's values will be preferred.
$collection = new MixedCollection([0 => 'car', 1 => 'bike', 2 => 'scooter']);
$union = $collection->union([0 =>'car', 1 => 'scooter']);
$union->all();
// [0 => 'car', 1 => 'bike' 2 => 'scooter']Related method: intersect.
Returns the values of the collection.
$collection = new MixedCollection(['user' => 'victor', 'github-user' => 'yosymfony']);
$values = $collection->values();
$values->all();
// ['victor', 'yosymfony']Related method: keys.
Filter the collection using the given callback. This method preserves the original keys.
$collection = new MixedCollection(['user' => 'victor', 'github-user' => 'yosymfony']);
$filtered = $collection->where(function ($item, $key){
return $key === 'user' && $item == 'victor';
});
$filtered->all();
// ['user' => 'victor']The callback function has the following signature: function (mixed $item, mixed $key) : bool