Русский
Español
- Profundizando
- Colecciones
Documentación de Laravel 10.x
Colecciones
Introducción
La clase Illuminate\Support\Collection proporciona un envoltorio fluido y conveniente para trabajar con arrays de datos. Por ejemplo, echa un vistazo al siguiente código. Usaremos la función collect para crear una nueva instancia de colección a partir del array, ejecutar la función strtoupper en cada elemento y luego eliminar todos los elementos vacíos:
$collection = collect(['taylor', 'abigail', null])->map(function (string $name) { return strtoupper($name);})->reject(function (string $name) { return empty($name);});Como puedes ver, la clase Collection te permite encadenar sus métodos para realizar un mapeo y reducción fluidos del array subyacente. En general, las colecciones son inmutables, lo que significa que cada método de Collection devuelve una instancia completamente nueva de Collection.
Creación de Colecciones
Como se mencionó anteriormente, la función auxiliar collect devuelve una nueva instancia de Illuminate\Support\Collection para el arreglo dado. Entonces, crear una colección es tan simple como:
$collection = collect([1, 2, 3]);Nota Los resultados de las consultas de Eloquent siempre se devuelven como instancias de
Collection.
Extensión de Colecciones
Las colecciones son "macroables", lo que te permite agregar métodos adicionales a la clase Collection en tiempo de ejecución. El método macro de la clase Illuminate\Support\Collection acepta un cierre que se ejecutará cuando se llame a tu macro. El cierre de la macro puede acceder a los otros métodos de la colección a través de $this, como si fuera un verdadero método de la clase de colección. Por ejemplo, el siguiente código agrega un método toUpper a la clase Collection:
use Illuminate\Support\Collection;use Illuminate\Support\Str; Collection::macro('toUpper', function () { return $this->map(function (string $value) { return Str::upper($value); });}); $collection = collect(['first', 'second']); $upper = $collection->toUpper(); // ['FIRST', 'SECOND']Normalmente, debes declarar macros de colección en el método boot de un proveedor de servicios.
Argumentos de Macro
Si es necesario, puedes definir macros que acepten argumentos adicionales:
use Illuminate\Support\Collection;use Illuminate\Support\Facades\Lang; Collection::macro('toLocale', function (string $locale) { return $this->map(function (string $value) use ($locale) { return Lang::get($value, [], $locale); });}); $collection = collect(['first', 'second']); $translated = $collection->toLocale('es');Métodos Disponibles
Para la mayoría de la documentación restante de la colección, discutiremos cada método disponible en la clase Collection. Recuerda, todos estos métodos se pueden encadenar para manipular fluídamente el array subyacente. Además, casi todos los métodos devuelven una nueva instancia de Collection, lo que te permite conservar la copia original de la colección cuando sea necesario:
all average avg chunk chunkWhile collapse collect combine concat contains containsOneItem containsStrict count countBy crossJoin dd diff diffAssoc diffAssocUsing diffKeys doesntContain dot dump duplicates duplicatesStrict each eachSpread ensure every except filter first firstOrFail firstWhere flatMap flatten flip forget forPage get groupBy has hasAny implode intersect intersectAssoc intersectByKeys isEmpty isNotEmpty join keyBy keys last lazy macro make map mapInto mapSpread mapToGroups mapWithKeys max median merge mergeRecursive min mode nth only pad partition percentage pipe pipeInto pipeThrough pluck pop prepend pull push put random range reduce reduceSpread reject replace replaceRecursive reverse search shift shuffle skip skipUntil skipWhile slice sliding sole some sort sortBy sortByDesc sortDesc sortKeys sortKeysDesc sortKeysUsing splice split splitIn sum take takeUntil takeWhile tap times toArray toJson transform undot union unique uniqueStrict unless unlessEmpty unlessNotEmpty unwrap value values when whenEmpty whenNotEmpty where whereStrict whereBetween whereIn whereInStrict whereInstanceOf whereNotBetween whereNotIn whereNotInStrict whereNotNull whereNull wrap zip
Listado de Métodos
all()
El método all devuelve el array subyacente representado por la colección:
collect([1, 2, 3])->all(); // [1, 2, 3]average()
Alias para el método avg.
avg()
El método avg devuelve el valor promedio de una clave dada:
$average = collect([ ['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->avg('foo'); // 20 $average = collect([1, 1, 2, 4])->avg(); // 2chunk()
El método chunk divide la colección en varias colecciones más pequeñas de un tamaño dado:
$collection = collect([1, 2, 3, 4, 5, 6, 7]); $chunks = $collection->chunk(4); $chunks->all(); // [[1, 2, 3, 4], [5, 6, 7]]Este método es especialmente útil en vistas cuando se trabaja con un sistema de cuadrícula como Bootstrap. Por ejemplo, imagina que tienes una colección de modelos Eloquent que deseas mostrar en una cuadrícula:
@foreach ($products->chunk(3) as $chunk) <div class="row"> @foreach ($chunk as $product) <div class="col-xs-4">{{ $product->name }}</div> @endforeach </div>@endforeachchunkWhile()
El método chunkWhile divide la colección en varias colecciones más pequeñas según la evaluación de la devolución de llamada dada. La variable $chunk pasada al cierre se puede usar para inspeccionar el elemento anterior:
$collection = collect(str_split('AABBCCCD')); $chunks = $collection->chunkWhile(function (string $value, int $key, Collection $chunk) { return $value === $chunk->last();}); $chunks->all(); // [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]collapse()
El método collapse colapsa una colección de arreglos en una sola colección plana:
$collection = collect([ [1, 2, 3], [4, 5, 6], [7, 8, 9],]); $collapsed = $collection->collapse(); $collapsed->all(); // [1, 2, 3, 4, 5, 6, 7, 8, 9]collect()
El método collect devuelve una nueva instancia de Collection con los elementos actuales en la colección:
$collectionA = collect([1, 2, 3]); $collectionB = $collectionA->collect(); $collectionB->all(); // [1, 2, 3]El método collect es principalmente útil para convertir colecciones perezosas en instancias estándar de Collection:
$lazyCollection = LazyCollection::make(function () { yield 1; yield 2; yield 3;}); $collection = $lazyCollection->collect(); $collection::class; // 'Illuminate\Support\Collection' $collection->all(); // [1, 2, 3]Nota El método
collectes especialmente útil cuando tienes una instancia deEnumerabley necesitas una instancia de colección no perezosa. Dado quecollect()forma parte del contratoEnumerable, puedes usarlo de manera segura para obtener una instancia deCollection.
combine()
El método combine combina los valores de la colección, como claves, con los valores de otro arreglo o colección:
$collection = collect(['name', 'age']); $combined = $collection->combine(['George', 29]); $combined->all(); // ['name' => 'George', 'age' => 29]concat()
El método concat agrega los valores del array o de la colección dada al final de otra colección:
$collection = collect(['John Doe']); $concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']); $concatenated->all(); // ['John Doe', 'Jane Doe', 'Johnny Doe']El método concat reindexa numéricamente las claves para los elementos concatenados a la colección original. Para mantener las claves en colecciones asociativas, consulta el método merge.
contains()
El método contains determina si la colección contiene un elemento dado. Puedes pasar un cierre al método contains para determinar si existe un elemento en la colección que coincida con una prueba de verdad dada:
$collection = collect([1, 2, 3, 4, 5]); $collection->contains(function (int $value, int $key) { return $value > 5;}); // falseAlternativamente, puedes pasar una cadena al método contains para determinar si la colección contiene un valor de elemento dado:
$collection = collect(['name' => 'Desk', 'price' => 100]); $collection->contains('Desk'); // true $collection->contains('New York'); // falseTambién puedes pasar un par clave/valor al método contains, que determinará si el par dado existe en la colección:
$collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 100],]); $collection->contains('product', 'Bookcase'); // falseEl método contains utiliza comparaciones "laxas" al verificar los valores de los elementos, lo que significa que una cadena con un valor entero se considerará igual a un entero del mismo valor. Utiliza el método containsStrict para filtrar usando comparaciones "estrictas".
Para la inversa de contains, consulta el método doesntContain.
containsOneItem()
El método containsOneItem determina si la colección contiene un solo elemento:
collect([])->containsOneItem(); // false collect(['1'])->containsOneItem(); // true collect(['1', '2'])->containsOneItem(); // falsecontainsStrict()
Este método tiene la misma firma que el método contains; sin embargo, todos los valores se comparan utilizando comparaciones "estrictas".
Nota El comportamiento de este método se modifica al usar Eloquent Collections.
count()
El método count devuelve el número total de elementos en la colección:
$collection = collect([1, 2, 3, 4]); $collection->count(); // 4countBy()
El método countBy cuenta las ocurrencias de valores en la colección. Por defecto, el método cuenta las ocurrencias de cada elemento, lo que te permite contar ciertos "tipos" de elementos en la colección:
$collection = collect([1, 2, 2, 2, 3]); $counted = $collection->countBy(); $counted->all(); // [1 => 1, 2 => 3, 3 => 1]Puedes pasar un cierre al método countBy para contar todos los elementos por un valor personalizado:
$counted = $collection->countBy(function (string $email) { return substr(strrchr($email, "@"), 1);}); $counted->all(); // ['gmail.com' => 2, 'yahoo.com' => 1]crossJoin()
El método crossJoin realiza una unión cruzada de los valores de la colección entre los arreglos o colecciones dados, devolviendo un producto cartesiano con todas las posibles permutaciones:
$collection = collect([1, 2]); $matrix = $collection->crossJoin(['a', 'b']); $matrix->all(); /* [ [1, 'a'], [1, 'b'], [2, 'a'], [2, 'b'], ]*/ $collection = collect([1, 2]); $matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']); $matrix->all(); /* [ [1, 'a', 'I'], [1, 'a', 'II'], [1, 'b', 'I'], [1, 'b', 'II'], [2, 'a', 'I'], [2, 'a', 'II'], [2, 'b', 'I'], [2, 'b', 'II'], ]*/dd()
El método dd muestra los elementos de la colección y finaliza la ejecución del script:
$collection = collect(['John Doe', 'Jane Doe']); $collection->dd(); /* Collection { #items: array:2 [ 0 => "John Doe" 1 => "Jane Doe" ] }*/Si no deseas detener la ejecución del script, utiliza el método dump en su lugar.
diff()
El método diff compara la colección con otra colección o un simple array de PHP basado en sus valores. Este método devolverá los valores en la colección original que no están presentes en la colección dada:
$collection = collect([1, 2, 3, 4, 5]); $diff = $collection->diff([2, 4, 6, 8]); $diff->all(); // [1, 3, 5]Nota El comportamiento de este método se modifica al usar Eloquent Collections.
diffAssoc()
El método diffAssoc compara la colección con otra colección o un simple array de PHP basado en sus claves y valores. Este método devolverá los pares clave/valor en la colección original que no están presentes en la colección dada:
$collection = collect([ 'color' => 'orange', 'type' => 'fruit', 'remain' => 6,]); $diff = $collection->diffAssoc([ 'color' => 'yellow', 'type' => 'fruit', 'remain' => 3, 'used' => 6,]); $diff->all(); // ['color' => 'orange', 'remain' => 6]diffAssocUsing()
A diferencia de diffAssoc, diffAssocUsing acepta una función de callback suministrada por el usuario para la comparación de índices:
$collection = collect([ 'color' => 'orange', 'type' => 'fruit', 'remain' => 6,]); $diff = $collection->diffAssocUsing([ 'Color' => 'yellow', 'Type' => 'fruit', 'Remain' => 3,], 'strnatcasecmp'); $diff->all(); // ['color' => 'orange', 'remain' => 6]El callback debe ser una función de comparación que devuelva un entero menor que, igual a, o mayor que cero. Para obtener más información, consulta la documentación de PHP sobre array_diff_uassoc, que es la función de PHP que utiliza internamente el método diffAssocUsing.
diffKeys()
El método diffKeys compara la colección con otra colección o un simple array de PHP basado en sus claves. Este método devolverá los pares clave/valor en la colección original que no están presentes en la colección dada:
$collection = collect([ 'one' => 10, 'two' => 20, 'three' => 30, 'four' => 40, 'five' => 50,]); $diff = $collection->diffKeys([ 'two' => 2, 'four' => 4, 'six' => 6, 'eight' => 8,]); $diff->all(); // ['one' => 10, 'three' => 30, 'five' => 50]doesntContain()
El método doesntContain determina si la colección no contiene un elemento dado. Puedes pasar un cierre al método doesntContain para determinar si un elemento no existe en la colección que coincide con una prueba de verdad dada:
$collection = collect([1, 2, 3, 4, 5]); $collection->doesntContain(function (int $value, int $key) { return $value < 5;}); // falseAlternativamente, puedes pasar una cadena al método doesntContain para determinar si la colección no contiene un valor de elemento dado:
$collection = collect(['name' => 'Desk', 'price' => 100]); $collection->doesntContain('Table'); // true $collection->doesntContain('Desk'); // falseTambién puedes pasar un par clave/valor al método doesntContain, que determinará si el par dado no existe en la colección:
$collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 100],]); $collection->doesntContain('product', 'Bookcase'); // trueEl método doesntContain utiliza comparaciones "laxas" al verificar los valores de los elementos, lo que significa que una cadena con un valor entero se considerará igual a un entero del mismo valor.
dot()
El método dot aplana una colección multidimensional en una colección de un solo nivel que utiliza la notación "punto" para indicar la profundidad:
$collection = collect(['products' => ['desk' => ['price' => 100]]]); $flattened = $collection->dot(); $flattened->all(); // ['products.desk.price' => 100]dump()
El método dump muestra los elementos de la colección:
$collection = collect(['John Doe', 'Jane Doe']); $collection->dump(); /* Collection { #items: array:2 [ 0 => "John Doe" 1 => "Jane Doe" ] }*/Si deseas detener la ejecución del script después de mostrar la colección, utiliza el método dd en su lugar.
duplicates()
El método duplicates recupera y devuelve valores duplicados de la colección:
$collection = collect(['a', 'b', 'a', 'c', 'b']); $collection->duplicates(); // [2 => 'a', 4 => 'b']Si la colección contiene arreglos u objetos, puedes pasar la clave de los atributos que deseas verificar para los valores duplicados:
$employees = collect([]); $employees->duplicates('position'); // [2 => 'Developer']duplicatesStrict()
Este método tiene la misma firma que el método duplicates; sin embargo, todos los valores se comparan utilizando comparaciones "estrictas".
each()
El método each itera sobre los elementos de la colección y pasa cada elemento a un cierre:
$collection = collect([1, 2, 3, 4]); $collection->each(function (int $item, int $key) { // ...});Si deseas detener la iteración a través de los elementos, puedes devolver false desde tu cierre:
$collection->each(function (int $item, int $key) { if (/* condition */) { return false; }});eachSpread()
El método eachSpread itera sobre los elementos de la colección, pasando cada valor anidado al callback dado:
$collection = collect([['John Doe', 35], ['Jane Doe', 33]]); $collection->eachSpread(function (string $name, int $age) { // ...});Puedes detener la iteración a través de los elementos devolviendo false desde el callback:
$collection->eachSpread(function (string $name, int $age) { return false;});ensure()
El método ensure se puede usar para verificar que todos los elementos de una colección son de un tipo dado. De lo contrario, se lanzará una excepción UnexpectedValueException:
return $collection->ensure(User::class);También se pueden especificar tipos primitivos como string, int, float, bool y array:
return $collection->ensure('int');Advertencia El método
ensureno garantiza que se agregarán elementos de diferentes tipos a la colección en un momento posterior.
every()
El método every se puede usar para verificar que todos los elementos de una colección pasen una prueba de verdad dada:
collect([1, 2, 3, 4])->every(function (int $value, int $key) { return $value > 2;}); // falseSi la colección está vacía, el método every devolverá true:
$collection = collect([]); $collection->every(function (int $value, int $key) { return $value > 2;}); // trueexcept()
El método except devuelve todos los elementos en la colección excepto aquellos con las claves especificadas:
$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]); $filtered = $collection->except(['price', 'discount']); $filtered->all(); // ['product_id' => 1]Para la inversa de except, consulta el método only.
Nota El comportamiento de este método se modifica al usar Eloquent Collections.
filter()
El método filter filtra la colección utilizando el callback dado, manteniendo solo aquellos elementos que pasan una prueba de verdad dada:
$collection = collect([1, 2, 3, 4]); $filtered = $collection->filter(function (int $value, int $key) { return $value > 2;}); $filtered->all(); // [3, 4]Si no se suministra un callback, se eliminarán todas las entradas de la colección que sean equivalentes a false:
$collection = collect([1, 2, 3, null, false, '', 0, []]); $collection->filter()->all(); // [1, 2, 3]Para la inversa de filter, consulta el método reject.
first()
El método first devuelve el primer elemento en la colección que pasa una prueba de verdad dada:
collect([1, 2, 3, 4])->first(function (int $value, int $key) { return $value > 2;}); // 3También puedes llamar al método first sin argumentos para obtener el primer elemento en la colección. Si la colección está vacía, se devolverá null:
collect([1, 2, 3, 4])->first(); // 1firstOrFail()
El método firstOrFail es idéntico al método first; sin embargo, si no se encuentra ningún resultado, se lanzará una excepción Illuminate\Support\ItemNotFoundException:
collect([1, 2, 3, 4])->firstOrFail(function (int $value, int $key) { return $value > 5;}); // Throws ItemNotFoundException...También puedes llamar al método firstOrFail sin argumentos para obtener el primer elemento en la colección. Si la colección está vacía, se lanzará una excepción Illuminate\Support\ItemNotFoundException:
collect([])->firstOrFail(); // Throws ItemNotFoundException...firstWhere()
El método firstWhere devuelve el primer elemento en la colección con el par clave/valor dado:
$collection = collect([ ['name' => 'Regena', 'age' => null], ['name' => 'Linda', 'age' => 14], ['name' => 'Diego', 'age' => 23], ['name' => 'Linda', 'age' => 84],]); $collection->firstWhere('name', 'Linda'); // ['name' => 'Linda', 'age' => 14]También puedes llamar al método firstWhere con un operador de comparación:
$collection->firstWhere('age', '>=', 18); // ['name' => 'Diego', 'age' => 23]Al igual que el método where, puedes pasar un argumento al método firstWhere. En este escenario, el método firstWhere devolverá el primer elemento donde el valor de la clave del elemento dado es "verdadero":
$collection->firstWhere('age'); // ['name' => 'Linda', 'age' => 14]flatMap()
El método flatMap itera sobre la colección y pasa cada valor al callback dado. El callback puede modificar el elemento y devolverlo, formando así una nueva colección de elementos modificados. Luego, el array se aplana en un solo nivel:
$collection = collect([ ['name' => 'Sally'], ['school' => 'Arkansas'], ['age' => 28]]); $flattened = $collection->flatMap(function (array $values) { return array_map('strtoupper', $values);}); $flattened->all(); // ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];flatten()
El método flatten aplana una colección multidimensional en una sola dimensión:
$collection = collect([ 'name' => 'taylor', 'languages' => [ 'php', 'javascript' ]]); $flattened = $collection->flatten(); $flattened->all(); // ['taylor', 'php', 'javascript'];Si es necesario, puedes pasar al método flatten un argumento de "profundidad":
$collection = collect([ 'Apple' => [ [ 'name' => 'iPhone 6S', 'brand' => 'Apple' ], ], 'Samsung' => [ [ 'name' => 'Galaxy S7', 'brand' => 'Samsung' ], ],]); $products = $collection->flatten(1); $products->values()->all(); /* [ ['name' => 'iPhone 6S', 'brand' => 'Apple'], ['name' => 'Galaxy S7', 'brand' => 'Samsung'], ]*/En este ejemplo, llamar a flatten sin proporcionar la profundidad también habría aplanado los arrays anidados, dando como resultado ['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']. Proporcionar una profundidad te permite especificar el número de niveles que se aplanarán en los arrays anidados.
flip()
El método flip intercambia las claves de la colección con sus valores correspondientes:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']); $flipped = $collection->flip(); $flipped->all(); // ['taylor' => 'name', 'laravel' => 'framework']forget()
El método forget elimina un elemento de la colección por su clave:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']); $collection->forget('name'); $collection->all(); // ['framework' => 'laravel']Advertencia A diferencia de la mayoría de los otros métodos de colección,
forgetno devuelve una nueva colección modificada; modifica la colección en la que se llama.
forPage()
El método forPage devuelve una nueva colección que contiene los elementos que estarían presentes en un número de página dado. El método acepta el número de página como su primer argumento y el número de elementos para mostrar por página como su segundo argumento:
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]); $chunk = $collection->forPage(2, 3); $chunk->all(); // [4, 5, 6]get()
El método get devuelve el elemento en una clave dada. Si la clave no existe, se devuelve null:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']); $value = $collection->get('name'); // taylorOpcionalmente, puedes pasar un valor predeterminado como segundo argumento:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']); $value = $collection->get('age', 34); // 34Incluso puedes pasar un cierre como valor predeterminado del método. Se devolverá el resultado del cierre si la clave especificada no existe:
$collection->get('email', function () {}); groupBy()
El método groupBy agrupa los elementos de la colección por una clave dada:
$collection = collect([ ['account_id' => 'account-x10', 'product' => 'Chair'], ['account_id' => 'account-x10', 'product' => 'Bookcase'], ['account_id' => 'account-x11', 'product' => 'Desk'],]); $grouped = $collection->groupBy('account_id'); $grouped->all(); /* [ 'account-x10' => [ ['account_id' => 'account-x10', 'product' => 'Chair'], ['account_id' => 'account-x10', 'product' => 'Bookcase'], ], 'account-x11' => [ ['account_id' => 'account-x11', 'product' => 'Desk'], ], ]*/En lugar de pasar una key como string, puedes pasar un cierre. El cierre debe devolver el valor por el que deseas agrupar:
$grouped = $collection->groupBy(function (array $item, int $key) { return substr($item['account_id'], -3);}); $grouped->all(); /* [ 'x10' => [ ['account_id' => 'account-x10', 'product' => 'Chair'], ['account_id' => 'account-x10', 'product' => 'Bookcase'], ], 'x11' => [ ['account_id' => 'account-x11', 'product' => 'Desk'], ], ]*/Se pueden pasar varios criterios de agrupación como un array. Cada elemento del array se aplicará al nivel correspondiente dentro de un array multidimensional:
$data = new Collection([ 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']], 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']], 30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']], 40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],]); $result = $data->groupBy(['skill', function (array $item) { return $item['roles'];}], preserveKeys: true); /*[ 1 => [ 'Role_1' => [ 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']], 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']], ], 'Role_2' => [ 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']], ], 'Role_3' => [ 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']], ], ], 2 => [ 'Role_1' => [ 30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']], ], 'Role_2' => [ 40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']], ], ],];*/has()
El método has determina si una clave dada existe en la colección:
$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]); $collection->has('product'); // true $collection->has(['product', 'amount']); // true $collection->has(['amount', 'price']); // falsehasAny()
El método hasAny determina si alguna de las claves dadas existe en la colección:
$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]); $collection->hasAny(['product', 'price']); // true $collection->hasAny(['name', 'price']); // falseimplode()
El método implode une los elementos de una colección. Sus argumentos dependen del tipo de elementos en la colección. Si la colección contiene arrays u objetos, debes pasar la clave de los atributos que deseas unir y la cadena "glue" que deseas colocar entre los valores:
$collection = collect([ ['account_id' => 1, 'product' => 'Desk'], ['account_id' => 2, 'product' => 'Chair'],]); $collection->implode('product', ', '); // Desk, ChairSi la colección contiene cadenas simples o valores numéricos, debes pasar el "glue" como único argumento del método:
collect([1, 2, 3, 4, 5])->implode('-'); // '1-2-3-4-5'Puedes pasar un cierre al método implode si deseas dar formato a los valores que se están uniendo:
$collection->implode(function (array $item, int $key) { return strtoupper($item['product']);}, ', '); // DESK, CHAIRintersect()
El método intersect elimina cualquier valor de la colección original que no esté presente en el array o colección dado. La colección resultante conservará las claves de la colección original:
$collection = collect(['Desk', 'Sofa', 'Chair']); $intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']); $intersect->all(); // [0 => 'Desk', 2 => 'Chair']Nota El comportamiento de este método se modifica al usar Eloquent Collections.
intersectAssoc()
El método intersectAssoc compara la colección original con otra colección o array, devolviendo los pares clave/valor que están presentes en todas las colecciones dadas:
$collection = collect([ 'color' => 'red', 'size' => 'M', 'material' => 'cotton']); $intersect = $collection->intersectAssoc([ 'color' => 'blue', 'size' => 'M', 'material' => 'polyester']); $intersect->all(); // ['size' => 'M']intersectByKeys()
El método intersectByKeys elimina cualquier clave y su valor correspondiente de la colección original que no esté presente en el array o colección dado:
$collection = collect([ 'serial' => 'UX301', 'type' => 'screen', 'year' => 2009,]); $intersect = $collection->intersectByKeys([ 'reference' => 'UX404', 'type' => 'tab', 'year' => 2011,]); $intersect->all(); // ['type' => 'screen', 'year' => 2009]isEmpty()
El método isEmpty devuelve true si la colección está vacía; de lo contrario, se devuelve false:
collect([])->isEmpty(); // trueisNotEmpty()
El método isNotEmpty devuelve true si la colección no está vacía; de lo contrario, se devuelve false:
collect([])->isNotEmpty(); // falsejoin()
El método join une los valores de la colección con una cadena. Usando el segundo argumento de este método, también puedes especificar cómo se debe agregar el elemento final a la cadena:
collect(['a', 'b', 'c'])->join(', '); // 'a, b, c'collect(['a', 'b', 'c'])->join(', ', ', and '); // 'a, b, and c'collect(['a', 'b'])->join(', ', ' and '); // 'a and b'collect(['a'])->join(', ', ' and '); // 'a'collect([])->join(', ', ' and '); // ''keyBy()
El método keyBy indexa la colección por la clave dada. Si varios elementos tienen la misma clave, solo aparecerá el último en la nueva colección:
$collection = collect([ ['product_id' => 'prod-100', 'name' => 'Desk'], ['product_id' => 'prod-200', 'name' => 'Chair'],]); $keyed = $collection->keyBy('product_id'); $keyed->all(); /* [ 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'], 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'], ]*/También puedes pasar un cierre al método. El cierre debe devolver el valor por el cual deseas indexar la colección:
$keyed = $collection->keyBy(function (array $item, int $key) { return strtoupper($item['product_id']);}); $keyed->all(); /* [ 'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'], 'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'], ]*/keys()
El método keys devuelve todas las claves de la colección:
$collection = collect([ 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'], 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],]); $keys = $collection->keys(); $keys->all(); // ['prod-100', 'prod-200']last()
El método last devuelve el último elemento de la colección que pasa una prueba de verdad dada:
collect([1, 2, 3, 4])->last(function (int $value, int $key) { return $value < 3;}); // 2También puedes llamar al método last sin argumentos para obtener el último elemento de la colección. Si la colección está vacía, se devuelve null:
collect([1, 2, 3, 4])->last(); // 4lazy()
El método lazy devuelve una nueva instancia de LazyCollection desde el array subyacente de elementos:
$lazyCollection = collect([1, 2, 3, 4])->lazy(); $lazyCollection::class; // Illuminate\Support\LazyCollection $lazyCollection->all(); // [1, 2, 3, 4]Esto es especialmente útil cuando necesitas realizar transformaciones en una Collection enorme que contiene muchos elementos:
$count = $hugeCollection ->lazy() ->where('country', 'FR') ->where('balance', '>', '100') ->count();Al convertir la colección a una LazyCollection, evitamos tener que asignar una tonelada de memoria adicional. Aunque la colección original todavía mantiene sus valores en memoria, los filtros posteriores no lo harán. Por lo tanto, prácticamente no se asignará memoria adicional al filtrar los resultados de la colección.
macro()
El método estático macro te permite agregar métodos a la clase Collection en tiempo de ejecución. Consulta la documentación sobre extender colecciones para obtener más información.
make()
El método estático make crea una nueva instancia de colección. Consulta la sección Creating Collections.
map()
El método map itera a través de la colección y pasa cada valor al callback proporcionado. El callback es libre de modificar el elemento y devolverlo, formando así una nueva colección de elementos modificados:
$collection = collect([1, 2, 3, 4, 5]); $multiplied = $collection->map(function (int $item, int $key) { return $item * 2;}); $multiplied->all(); // [2, 4, 6, 8, 10]Advertencia Al igual que la mayoría de los otros métodos de colección,
mapdevuelve una nueva instancia de colección; no modifica la colección en la que se llama. Si deseas transformar la colección original, utiliza el métodotransform.
mapInto()
El método mapInto() itera sobre la colección, creando una nueva instancia de la clase dada pasando el valor al constructor:
class Currency{ /** * Create a new currency instance. */ function __construct( public string $code ) {}} $collection = collect(['USD', 'EUR', 'GBP']); $currencies = $collection->mapInto(Currency::class); $currencies->all(); // [Currency('USD'), Currency('EUR'), Currency('GBP')]mapSpread()
El método mapSpread itera sobre los elementos de la colección, pasando cada valor anidado al cierre proporcionado. El cierre es libre de modificar el elemento y devolverlo, formando así una nueva colección de elementos modificados:
$collection = collect([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); $chunks = $collection->chunk(2); $sequence = $chunks->mapSpread(function (int $even, int $odd) { return $even + $odd;}); $sequence->all(); // [1, 5, 9, 13, 17]mapToGroups()
El método mapToGroups agrupa los elementos de la colección según el cierre proporcionado. El cierre debe devolver un array asociativo que contenga un solo par clave/valor, formando así una nueva colección de valores agrupados:
$collection = collect([ [ 'name' => 'John Doe', 'department' => 'Sales', ], [ 'name' => 'Jane Doe', 'department' => 'Sales', ], [ 'name' => 'Johnny Doe', 'department' => 'Marketing', ]]); $grouped = $collection->mapToGroups(function (array $item, int $key) { return [$item['department'] => $item['name']];}); $grouped->all(); /* [ 'Sales' => ['John Doe', 'Jane Doe'], 'Marketing' => ['Johnny Doe'], ]*/ $grouped->get('Sales')->all(); // ['John Doe', 'Jane Doe']mapWithKeys()
El método mapWithKeys itera a través de la colección y pasa cada valor al cierre proporcionado. El cierre debe devolver un array asociativo que contenga un solo par clave/valor:
$collection = collect([ [ 'name' => 'John', 'department' => 'Sales', ], [ 'name' => 'Jane', 'department' => 'Marketing', ]]); $keyed = $collection->mapWithKeys(function (array $item, int $key) { return [$item['email'] => $item['name']];}); $keyed->all(); /* [ '[email protected]' => 'John', '[email protected]' => 'Jane', ]*/max()
El método max devuelve el valor máximo de una clave dada:
$max = collect([ ['foo' => 10], ['foo' => 20]])->max('foo'); // 20 $max = collect([1, 2, 3, 4, 5])->max(); // 5median()
El método median devuelve el valor de la mediana de una clave dada:
$median = collect([ ['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->median('foo'); // 15 $median = collect([1, 1, 2, 4])->median(); // 1.5merge()
El método merge fusiona el array o colección dado con la colección original. Si una clave de cadena en los elementos dados coincide con una clave de cadena en la colección original, el valor del elemento dado sobrescribirá el valor en la colección original:
$collection = collect(['product_id' => 1, 'price' => 100]); $merged = $collection->merge(['price' => 200, 'discount' => false]); $merged->all(); // ['product_id' => 1, 'price' => 200, 'discount' => false]Si las claves del elemento dado son numéricas, los valores se añadirán al final de la colección:
$collection = collect(['Desk', 'Chair']); $merged = $collection->merge(['Bookcase', 'Door']); $merged->all(); // ['Desk', 'Chair', 'Bookcase', 'Door']mergeRecursive()
El método mergeRecursive fusiona el array o colección dado recursivamente con la colección original. Si una clave de cadena en los elementos dados coincide con una clave de cadena en la colección original, los valores para estas claves se fusionan en un array, y esto se hace de forma recursiva:
$collection = collect(['product_id' => 1, 'price' => 100]); $merged = $collection->mergeRecursive([ 'product_id' => 2, 'price' => 200, 'discount' => false]); $merged->all(); // ['product_id' => [1, 2], 'price' => [100, 200], 'discount' => false]min()
El método min devuelve el valor mínimo de una clave dada:
$min = collect([['foo' => 10], ['foo' => 20]])->min('foo'); // 10 $min = collect([1, 2, 3, 4, 5])->min(); // 1mode()
El método mode devuelve el valor de la moda de una clave dada:
$mode = collect([ ['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->mode('foo'); // [10] $mode = collect([1, 1, 2, 4])->mode(); // [1] $mode = collect([1, 1, 2, 2])->mode(); // [1, 2]nth()
El método nth crea una nueva colección que consiste en cada elemento n-ésimo:
$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']); $collection->nth(4); // ['a', 'e']Opcionalmente, puedes pasar un desplazamiento inicial como segundo argumento:
$collection->nth(4, 1); // ['b', 'f']only()
El método only devuelve los elementos en la colección con las claves especificadas:
$collection = collect([ 'product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]); $filtered = $collection->only(['product_id', 'name']); $filtered->all(); // ['product_id' => 1, 'name' => 'Desk']Para la inversa de only, consulta el método except.
Nota El comportamiento de este método se modifica al usar Eloquent Collections.
pad()
El método pad llenará el array con el valor dado hasta que el array alcance el tamaño especificado. Este método se comporta como la función array_pad de PHP.
Para rellenar a la izquierda, debes especificar un tamaño negativo. No se realizará ningún relleno si el valor absoluto del tamaño dado es menor o igual a la longitud del array:
$collection = collect(['A', 'B', 'C']); $filtered = $collection->pad(5, 0); $filtered->all(); // ['A', 'B', 'C', 0, 0] $filtered = $collection->pad(-5, 0); $filtered->all(); // [0, 0, 'A', 'B', 'C']partition()
El método partition puede combinarse con la destrucción de arrays de PHP para separar los elementos que pasan una prueba de verdad dada de aquellos que no lo hacen:
$collection = collect([1, 2, 3, 4, 5, 6]); [$underThree, $equalOrAboveThree] = $collection->partition(function (int $i) { return $i < 3;}); $underThree->all(); // [1, 2] $equalOrAboveThree->all(); // [3, 4, 5, 6]percentage()
El método percentage se puede utilizar para determinar rápidamente el porcentaje de elementos en la colección que pasan una prueba de verdad dada:
$collection = collect([1, 1, 2, 2, 2, 3]); $percentage = $collection->percentage(fn ($value) => $value === 1); // 33.33De forma predeterminada, el porcentaje se redondeará a dos decimales. Sin embargo, puedes personalizar este comportamiento proporcionando un segundo argumento al método:
$percentage = $collection->percentage(fn ($value) => $value === 1, precision: 3); // 33.333pipe()
El método pipe pasa la colección al cierre dado y devuelve el resultado del cierre ejecutado:
$collection = collect([1, 2, 3]); $piped = $collection->pipe(function (Collection $collection) { return $collection->sum();}); // 6pipeInto()
El método pipeInto crea una nueva instancia de la clase dada y pasa la colección al constructor:
class ResourceCollection{ /** * Create a new ResourceCollection instance. */ public function __construct( public Collection $collection, ) {}} $collection = collect([1, 2, 3]); $resource = $collection->pipeInto(ResourceCollection::class); $resource->collection->all(); // [1, 2, 3]pipeThrough()
El método pipeThrough pasa la colección al array dado de cierres y devuelve el resultado de los cierres ejecutados:
use Illuminate\Support\Collection; $collection = collect([1, 2, 3]); $result = $collection->pipeThrough([ function (Collection $collection) { return $collection->merge([4, 5]); }, function (Collection $collection) { return $collection->sum(); },]); // 15pluck()
El método pluck recupera todos los valores de una clave dada:
$collection = collect([ ['product_id' => 'prod-100', 'name' => 'Desk'], ['product_id' => 'prod-200', 'name' => 'Chair'],]); $plucked = $collection->pluck('name'); $plucked->all(); // ['Desk', 'Chair']También puedes especificar cómo deseas que se clave la colección resultante:
$plucked = $collection->pluck('name', 'product_id'); $plucked->all(); // ['prod-100' => 'Desk', 'prod-200' => 'Chair']El método pluck también admite la recuperación de valores anidados mediante notación "dot":
$collection = collect([ [ 'name' => 'Laracon', 'speakers' => [ 'first_day' => ['Rosa', 'Judith'], ], ], [ 'name' => 'VueConf', 'speakers' => [ 'first_day' => ['Abigail', 'Joey'], ], ],]); $plucked = $collection->pluck('speakers.first_day'); $plucked->all(); // [['Rosa', 'Judith'], ['Abigail', 'Joey']]Si existen claves duplicadas, se insertará en la colección extraída el último elemento coincidente:
$collection = collect([ ['brand' => 'Tesla', 'color' => 'red'], ['brand' => 'Pagani', 'color' => 'white'], ['brand' => 'Tesla', 'color' => 'black'], ['brand' => 'Pagani', 'color' => 'orange'],]); $plucked = $collection->pluck('color', 'brand'); $plucked->all(); // ['Tesla' => 'black', 'Pagani' => 'orange']pop()
El método pop elimina y devuelve el último elemento de la colección:
$collection = collect([1, 2, 3, 4, 5]); $collection->pop(); // 5 $collection->all(); // [1, 2, 3, 4]Puedes pasar un entero al método pop para eliminar y devolver varios elementos del final de una colección:
$collection = collect([1, 2, 3, 4, 5]); $collection->pop(3); // collect([5, 4, 3]) $collection->all(); // [1, 2]prepend()
El método prepend agrega un elemento al principio de la colección:
$collection = collect([1, 2, 3, 4, 5]); $collection->prepend(0); $collection->all(); // [0, 1, 2, 3, 4, 5]También puedes pasar un segundo argumento para especificar la clave del elemento agregado al principio:
$collection = collect(['one' => 1, 'two' => 2]); $collection->prepend(0, 'zero'); $collection->all(); // ['zero' => 0, 'one' => 1, 'two' => 2]pull()
El método pull elimina y devuelve un elemento de la colección por su clave:
$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']); $collection->pull('name'); // 'Desk' $collection->all(); // ['product_id' => 'prod-100']push()
El método push agrega un elemento al final de la colección:
$collection = collect([1, 2, 3, 4]); $collection->push(5); $collection->all(); // [1, 2, 3, 4, 5]put()
El método put establece la clave y el valor dados en la colección:
$collection = collect(['product_id' => 1, 'name' => 'Desk']); $collection->put('price', 100); $collection->all(); // ['product_id' => 1, 'name' => 'Desk', 'price' => 100]random()
El método random devuelve un elemento aleatorio de la colección:
$collection = collect([1, 2, 3, 4, 5]); $collection->random(); // 4 - (retrieved randomly)Puedes pasar un entero a random para especificar cuántos elementos te gustaría recuperar aleatoriamente. Siempre se devuelve una colección de elementos cuando se pasa explícitamente el número de elementos que deseas recibir:
$random = $collection->random(3); $random->all(); // [2, 4, 5] - (retrieved randomly)Si la instancia de colección tiene menos elementos de los solicitados, el método random lanzará una InvalidArgumentException.
El método random también acepta un cierre, que recibirá la instancia de colección actual:
use Illuminate\Support\Collection; $random = $collection->random(fn (Collection $items) => min(10, count($items))); $random->all(); // [1, 2, 3, 4, 5] - (retrieved randomly)range()
El método range devuelve una colección que contiene enteros entre el rango especificado:
$collection = collect()->range(3, 6); $collection->all(); // [3, 4, 5, 6]reduce()
El método reduce reduce la colección a un solo valor, pasando el resultado de cada iteración a la siguiente iteración:
$collection = collect([1, 2, 3]); $total = $collection->reduce(function (?int $carry, int $item) { return $carry + $item;}); // 6El valor para $carry en la primera iteración es null; sin embargo, puedes especificar su valor inicial pasando un segundo argumento a reduce:
$collection->reduce(function (int $carry, int $item) { return $carry + $item;}, 4); // 10El método reduce también pasa las claves de la matriz en colecciones asociativas al cierre dado:
$collection = collect([ 'usd' => 1400, 'gbp' => 1200, 'eur' => 1000,]); $ratio = [ 'usd' => 1, 'gbp' => 1.37, 'eur' => 1.22,]; $collection->reduce(function (int $carry, int $value, int $key) use ($ratio) { return $carry + ($value * $ratio[$key]);}); // 4264reduceSpread()
El método reduceSpread reduce la colección a una matriz de valores, pasando los resultados de cada iteración a la siguiente iteración. Este método es similar al método reduce; sin embargo, puede aceptar múltiples valores iniciales:
[$creditsRemaining, $batch] = Image::where('status', 'unprocessed') ->get() ->reduceSpread(function (int $creditsRemaining, Collection $batch, Image $image) { if ($creditsRemaining >= $image->creditsRequired()) { $batch->push($image); $creditsRemaining -= $image->creditsRequired(); } return [$creditsRemaining, $batch]; }, $creditsAvailable, collect());reject()
El método reject filtra la colección usando el cierre dado. El cierre debe devolver true si el elemento debe eliminarse de la colección resultante:
$collection = collect([1, 2, 3, 4]); $filtered = $collection->reject(function (int $value, int $key) { return $value > 2;}); $filtered->all(); // [1, 2]Para la inversa del método reject, consulta el método filter.
replace()
El método replace se comporta de manera similar a merge; sin embargo, además de sobrescribir elementos coincidentes que tienen claves de cadena, el método replace también sobrescribirá elementos en la colección que tienen claves numéricas coincidentes:
$collection = collect(['Taylor', 'Abigail', 'James']); $replaced = $collection->replace([1 => 'Victoria', 3 => 'Finn']); $replaced->all(); // ['Taylor', 'Victoria', 'James', 'Finn']replaceRecursive()
Este método funciona como replace, pero se adentrará en arrays y aplicará el mismo proceso de reemplazo a los valores internos:
$collection = collect([ 'Taylor', 'Abigail', [ 'James', 'Victoria', 'Finn' ]]); $replaced = $collection->replaceRecursive([ 'Charlie', 2 => [1 => 'King']]); $replaced->all(); // ['Charlie', 'Abigail', ['James', 'King', 'Finn']]reverse()
El método reverse invierte el orden de los elementos de la colección, preservando las claves originales:
$collection = collect(['a', 'b', 'c', 'd', 'e']); $reversed = $collection->reverse(); $reversed->all(); /* [ 4 => 'e', 3 => 'd', 2 => 'c', 1 => 'b', 0 => 'a', ]*/search()
El método search busca en la colección el valor dado y devuelve su clave si se encuentra. Si no se encuentra el elemento, se devuelve false:
$collection = collect([2, 4, 6, 8]); $collection->search(4); // 1La búsqueda se realiza utilizando una comparación "loose", lo que significa que una cadena con un valor entero se considerará igual a un entero del mismo valor. Para usar una comparación "strict", pasa true como segundo argumento al método:
collect([2, 4, 6, 8])->search('4', $strict = true); // falseAlternativamente, puedes proporcionar tu propio cierre para buscar el primer elemento que pase una prueba de verdad dada:
collect([2, 4, 6, 8])->search(function (int $item, int $key) { return $item > 5;}); // 2shift()
El método shift elimina y devuelve el primer elemento de la colección:
$collection = collect([1, 2, 3, 4, 5]); $collection->shift(); // 1 $collection->all(); // [2, 3, 4, 5]Puedes pasar un entero al método shift para eliminar y devolver varios elementos desde el principio de una colección:
$collection = collect([1, 2, 3, 4, 5]); $collection->shift(3); // collect([1, 2, 3]) $collection->all(); // [4, 5]shuffle()
El método shuffle mezcla aleatoriamente los elementos de la colección:
$collection = collect([1, 2, 3, 4, 5]); $shuffled = $collection->shuffle(); $shuffled->all(); // [3, 2, 5, 1, 4] - (generated randomly)skip()
El método skip devuelve una nueva colección, con el número dado de elementos eliminados desde el principio de la colección:
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); $collection = $collection->skip(4); $collection->all(); // [5, 6, 7, 8, 9, 10]skipUntil()
El método skipUntil salta sobre los elementos de la colección hasta que el cierre dado devuelve true y luego devuelve los elementos restantes en la colección como una nueva instancia de colección:
$collection = collect([1, 2, 3, 4]); $subset = $collection->skipUntil(function (int $item) { return $item >= 3;}); $subset->all(); // [3, 4]También puedes pasar un valor simple al método skipUntil para omitir todos los elementos hasta que se encuentre el valor dado:
$collection = collect([1, 2, 3, 4]); $subset = $collection->skipUntil(3); $subset->all(); // [3, 4]Advertencia Si no se encuentra el valor dado o el callback nunca devuelve
true, el métodoskipUntildevolverá una colección vacía.
skipWhile()
El método skipWhile salta sobre los elementos de la colección mientras el cierre dado devuelve true y luego devuelve los elementos restantes en la colección como una nueva colección:
$collection = collect([1, 2, 3, 4]); $subset = $collection->skipWhile(function (int $item) { return $item <= 3;}); $subset->all(); // [4]Advertencia Si el callback nunca devuelve
false, el métodoskipWhiledevolverá una colección vacía.
slice()
El método slice devuelve una porción de la colección a partir del índice dado:
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); $slice = $collection->slice(4); $slice->all(); // [5, 6, 7, 8, 9, 10]Si deseas limitar el tamaño de la porción devuelta, pasa el tamaño deseado como segundo argumento al método:
$slice = $collection->slice(4, 2); $slice->all(); // [5, 6]La porción devuelta preservará las claves de forma predeterminada. Si no deseas preservar las claves originales, puedes usar el método values para reindexarlas.
sliding()
El método sliding devuelve una nueva colección de fragmentos que representan una vista de "ventana deslizante" de los elementos en la colección:
$collection = collect([1, 2, 3, 4, 5]); $chunks = $collection->sliding(2); $chunks->toArray(); // [[1, 2], [2, 3], [3, 4], [4, 5]]Esto es especialmente útil junto con el método eachSpread:
$transactions->sliding(2)->eachSpread(function (Collection $previous, Collection $current) { $current->total = $previous->total + $current->amount;});Opcionalmente, puedes pasar un segundo valor de "paso" que determine la distancia entre el primer elemento de cada fragmento:
$collection = collect([1, 2, 3, 4, 5]); $chunks = $collection->sliding(3, step: 2); $chunks->toArray(); // [[1, 2, 3], [3, 4, 5]]sole()
El método sole devuelve el primer elemento en la colección que pasa una prueba de verdad dada, pero solo si la prueba de verdad coincide exactamente con un elemento:
collect([1, 2, 3, 4])->sole(function (int $value, int $key) { return $value === 2;}); // 2También puedes pasar un par clave/valor al método sole, que devolverá el primer elemento en la colección que coincida con el par dado, pero solo si exactamente un elemento coincide:
$collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 100],]); $collection->sole('product', 'Chair'); // ['product' => 'Chair', 'price' => 100]Alternativamente, también puedes llamar al método sole sin argumentos para obtener el primer elemento en la colección si hay solo un elemento:
$collection = collect([ ['product' => 'Desk', 'price' => 200],]); $collection->sole(); // ['product' => 'Desk', 'price' => 200]Si no hay elementos en la colección que deban devolverse por el método sole, se lanzará una excepción \Illuminate\Collections\ItemNotFoundException. Si hay más de un elemento que debe devolverse, se lanzará una \Illuminate\Collections\MultipleItemsFoundException.
some()
Alias para el método contains.
sort()
El método sort ordena la colección. La colección ordenada mantiene las claves originales del array, así que en el siguiente ejemplo usaremos el método values para restablecer las claves a índices consecutivos:
$collection = collect([5, 3, 1, 2, 4]); $sorted = $collection->sort(); $sorted->values()->all(); // [1, 2, 3, 4, 5]Si tus necesidades de ordenación son más avanzadas, puedes pasar un cierre a sort con tu propio algoritmo. Consulta la documentación de PHP sobre uasort, que es lo que utiliza internamente el método sort de la colección.
Nota Si necesitas ordenar una colección de arrays u objetos anidados, consulta los métodos
sortByysortByDesc.
sortBy()
El método sortBy ordena la colección por la clave dada. La colección ordenada conserva las claves originales del array, así que en el siguiente ejemplo usaremos el método values para restablecer las claves a índices consecutivos:
$collection = collect([ ['name' => 'Desk', 'price' => 200], ['name' => 'Chair', 'price' => 100], ['name' => 'Bookcase', 'price' => 150],]); $sorted = $collection->sortBy('price'); $sorted->values()->all(); /* [ ['name' => 'Chair', 'price' => 100], ['name' => 'Bookcase', 'price' => 150], ['name' => 'Desk', 'price' => 200], ]*/El método sortBy acepta banderas de ordenación como segundo argumento:
$collection = collect([ ['title' => 'Item 1'], ['title' => 'Item 12'], ['title' => 'Item 3'],]); $sorted = $collection->sortBy('title', SORT_NATURAL); $sorted->values()->all(); /* [ ['title' => 'Item 1'], ['title' => 'Item 3'], ['title' => 'Item 12'], ]*/Alternativamente, puedes pasar tu propio cierre para determinar cómo ordenar los valores de la colección:
$collection = collect([ ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']], ['name' => 'Chair', 'colors' => ['Black']], ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],]); $sorted = $collection->sortBy(function (array $product, int $key) { return count($product['colors']);}); $sorted->values()->all(); /* [ ['name' => 'Chair', 'colors' => ['Black']], ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']], ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']], ]*/Si deseas ordenar tu colección por múltiples atributos, puedes pasar un array de operaciones de ordenación al método sortBy. Cada operación de ordenación debe ser un array que conste del atributo por el que deseas ordenar y la dirección de la ordenación deseada:
$collection = collect([ ['name' => 'Taylor Otwell', 'age' => 34], ['name' => 'Abigail Otwell', 'age' => 30], ['name' => 'Taylor Otwell', 'age' => 36], ['name' => 'Abigail Otwell', 'age' => 32],]); $sorted = $collection->sortBy([ ['name', 'asc'], ['age', 'desc'],]); $sorted->values()->all(); /* [ ['name' => 'Abigail Otwell', 'age' => 32], ['name' => 'Abigail Otwell', 'age' => 30], ['name' => 'Taylor Otwell', 'age' => 36], ['name' => 'Taylor Otwell', 'age' => 34], ]*/Al ordenar una colección por múltiples atributos, también puedes proporcionar cierres que definan cada operación de ordenación:
$collection = collect([ ['name' => 'Taylor Otwell', 'age' => 34], ['name' => 'Abigail Otwell', 'age' => 30], ['name' => 'Taylor Otwell', 'age' => 36], ['name' => 'Abigail Otwell', 'age' => 32],]); $sorted = $collection->sortBy([ fn (array $a, array $b) => $a['name'] <=> $b['name'], fn (array $a, array $b) => $b['age'] <=> $a['age'],]); $sorted->values()->all(); /* [ ['name' => 'Abigail Otwell', 'age' => 32], ['name' => 'Abigail Otwell', 'age' => 30], ['name' => 'Taylor Otwell', 'age' => 36], ['name' => 'Taylor Otwell', 'age' => 34], ]*/sortByDesc()
Este método tiene la misma firma que el método sortBy, pero ordenará la colección en el orden opuesto.
sortDesc()
Este método ordenará la colección en el orden opuesto al método sort:
$collection = collect([5, 3, 1, 2, 4]); $sorted = $collection->sortDesc(); $sorted->values()->all(); // [5, 4, 3, 2, 1]A diferencia de sort, no puedes pasar un cierre a sortDesc. En su lugar, debes usar el método sort e invertir tu comparación.
sortKeys()
El método sortKeys ordena la colección por las claves del array asociativo subyacente:
$collection = collect([ 'id' => 22345, 'first' => 'John', 'last' => 'Doe',]); $sorted = $collection->sortKeys(); $sorted->all(); /* [ 'first' => 'John', 'id' => 22345, 'last' => 'Doe', ]*/sortKeysDesc()
Este método tiene la misma firma que el método sortKeys, pero ordenará la colección en el orden opuesto.
sortKeysUsing()
El método sortKeysUsing ordena la colección por las claves del array asociativo subyacente mediante un cierre:
$collection = collect([ 'ID' => 22345, 'first' => 'John', 'last' => 'Doe',]); $sorted = $collection->sortKeysUsing('strnatcasecmp'); $sorted->all(); /* [ 'first' => 'John', 'ID' => 22345, 'last' => 'Doe', ]*/El cierre debe ser una función de comparación que devuelva un entero menor que, igual a o mayor que cero. Para obtener más información, consulta la documentación de PHP sobre uksort, que es la función de PHP que utiliza internamente el método sortKeysUsing.
splice()
El método splice elimina y devuelve una porción de elementos a partir del índice especificado:
$collection = collect([1, 2, 3, 4, 5]); $chunk = $collection->splice(2); $chunk->all(); // [3, 4, 5] $collection->all(); // [1, 2]Puedes pasar un segundo argumento para limitar el tamaño de la colección resultante:
$collection = collect([1, 2, 3, 4, 5]); $chunk = $collection->splice(2, 1); $chunk->all(); // [3] $collection->all(); // [1, 2, 4, 5]Además, puedes pasar un tercer argumento que contenga los nuevos elementos para reemplazar los elementos eliminados de la colección:
$collection = collect([1, 2, 3, 4, 5]); $chunk = $collection->splice(2, 1, [10, 11]); $chunk->all(); // [3] $collection->all(); // [1, 2, 10, 11, 4, 5]split()
El método split divide una colección en el número dado de grupos:
$collection = collect([1, 2, 3, 4, 5]); $groups = $collection->split(3); $groups->all(); // [[1, 2], [3, 4], [5]]splitIn()
El método splitIn divide una colección en el número dado de grupos, llenando completamente los grupos no terminales antes de asignar el resto al grupo final:
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); $groups = $collection->splitIn(3); $groups->all(); // [[1, 2, 3, 4], [5, 6, 7, 8], [9, 10]]sum()
El método sum devuelve la suma de todos los elementos de la colección:
collect([1, 2, 3, 4, 5])->sum(); // 15Si la colección contiene arrays u objetos anidados, debes pasar una clave que se utilizará para determinar qué valores sumar:
$collection = collect([ ['name' => 'JavaScript: The Good Parts', 'pages' => 176], ['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],]); $collection->sum('pages'); // 1272Además, puedes pasar tu propio cierre para determinar qué valores de la colección sumar:
$collection = collect([ ['name' => 'Chair', 'colors' => ['Black']], ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']], ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],]); $collection->sum(function (array $product) { return count($product['colors']);}); // 6take()
El método take devuelve una nueva colección con el número especificado de elementos:
$collection = collect([0, 1, 2, 3, 4, 5]); $chunk = $collection->take(3); $chunk->all(); // [0, 1, 2]También puedes pasar un entero negativo para tomar el número especificado de elementos desde el final de la colección:
$collection = collect([0, 1, 2, 3, 4, 5]); $chunk = $collection->take(-2); $chunk->all(); // [4, 5]takeUntil()
El método takeUntil devuelve elementos en la colección hasta que el cierre dado devuelve true:
$collection = collect([1, 2, 3, 4]); $subset = $collection->takeUntil(function (int $item) { return $item >= 3;}); $subset->all(); // [1, 2]También puedes pasar un valor simple al método takeUntil para obtener los elementos hasta que se encuentre el valor dado:
$collection = collect([1, 2, 3, 4]); $subset = $collection->takeUntil(3); $subset->all(); // [1, 2]Advertencia Si no se encuentra el valor dado o el callback nunca devuelve
true, el métodotakeUntildevolverá todos los elementos de la colección.
takeWhile()
El método takeWhile devuelve elementos en la colección hasta que la devolución de llamada dada devuelve false:
$collection = collect([1, 2, 3, 4]); $subset = $collection->takeWhile(function (int $item) { return $item < 3;}); $subset->all(); // [1, 2]Advertencia Si el callback nunca devuelve
false, el métodotakeWhiledevolverá todos los elementos de la colección.
tap()
El método tap pasa la colección a la devolución de llamada dada, permitiéndote "intervenir" en la colección en un punto específico y hacer algo con los elementos sin afectar la colección misma. La colección luego es devuelta por el método tap:
collect([2, 4, 3, 1, 5]) ->sort() ->tap(function (Collection $collection) { Log::debug('Values after sorting', $collection->values()->all()); }) ->shift(); // 1times()
El método estático times crea una nueva colección invocando la devolución de llamada dada un número especificado de veces:
$collection = Collection::times(10, function (int $number) { return $number * 9;}); $collection->all(); // [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]toArray()
El método toArray convierte la colección en un arreglo PHP plano. Si los valores de la colección son modelos Eloquent, los modelos también se convertirán a arreglos:
$collection = collect(['name' => 'Desk', 'price' => 200]); $collection->toArray(); /* [ ['name' => 'Desk', 'price' => 200], ]*/Advertencia
toArraytambién convierte todos los objetos anidados de la colección que son una instancia deArrayablea un array. Si deseas obtener el array sin procesar que subyace a la colección, utiliza el métodoallen su lugar.
toJson()
El método toJson convierte la colección en una cadena JSON serializada:
$collection = collect(['name' => 'Desk', 'price' => 200]); $collection->toJson(); // '{"name":"Desk", "price":200}'transform()
El método transform itera sobre la colección y llama a la devolución de llamada dada con cada elemento en la colección. Los elementos en la colección serán reemplazados por los valores devueltos por la devolución de llamada:
$collection = collect([1, 2, 3, 4, 5]); $collection->transform(function (int $item, int $key) { return $item * 2;}); $collection->all(); // [2, 4, 6, 8, 10]Advertencia A diferencia de la mayoría de los otros métodos de colección,
transformmodifica la colección misma. Si deseas crear una nueva colección en su lugar, utiliza el métodomap.
undot()
El método undot expande una colección unidimensional que utiliza notación "punto" en una colección multidimensional:
$person = collect([ 'name.first_name' => 'Marie', 'name.last_name' => 'Valentine', 'address.line_1' => '2992 Eagle Drive', 'address.line_2' => '', 'address.suburb' => 'Detroit', 'address.state' => 'MI', 'address.postcode' => '48219']); $person = $person->undot(); $person->toArray(); /* [ "name" => [ "first_name" => "Marie", "last_name" => "Valentine", ], "address" => [ "line_1" => "2992 Eagle Drive", "line_2" => "", "suburb" => "Detroit", "state" => "MI", "postcode" => "48219", ], ]*/union()
El método union agrega el arreglo dado a la colección. Si el arreglo dado contiene claves que ya están en la colección original, se preferirán los valores de la colección original:
$collection = collect([1 => ['a'], 2 => ['b']]); $union = $collection->union([3 => ['c'], 1 => ['d']]); $union->all(); // [1 => ['a'], 2 => ['b'], 3 => ['c']]unique()
El método unique devuelve todos los elementos únicos en la colección. La colección devuelta mantiene las claves originales del arreglo, por lo que en el siguiente ejemplo usaremos el método values para restablecer las claves a índices consecutivos:
$collection = collect([1, 1, 2, 2, 3, 4, 2]); $unique = $collection->unique(); $unique->values()->all(); // [1, 2, 3, 4]Cuando se trata con arreglos u objetos anidados, puedes especificar la clave utilizada para determinar la unicidad:
$collection = collect([ ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'], ['name' => 'iPhone 5', 'brand' => 'Apple', 'type' => 'phone'], ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'], ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'], ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],]); $unique = $collection->unique('brand'); $unique->values()->all(); /* [ ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'], ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'], ]*/Finalmente, también puedes pasar tu propia devolución de llamada al método unique para especificar qué valor debe determinar la unicidad de un elemento:
$unique = $collection->unique(function (array $item) { return $item['brand'].$item['type'];}); $unique->values()->all(); /* [ ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'], ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'], ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'], ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'], ]*/El método unique utiliza comparaciones "laxas" al verificar los valores de los elementos, lo que significa que una cadena con un valor entero se considerará igual a un entero del mismo valor. Utiliza el método uniqueStrict para filtrar usando comparaciones "estrictas".
Nota El comportamiento de este método se modifica al usar Eloquent Collections.
uniqueStrict()
Este método tiene la misma firma que el método unique; sin embargo, todos los valores se comparan utilizando comparaciones "estrictas".
unless()
El método unless ejecutará la devolución de llamada dada a menos que el primer argumento dado al método se evalúe como true:
$collection = collect([1, 2, 3]); $collection->unless(true, function (Collection $collection) { return $collection->push(4);}); $collection->unless(false, function (Collection $collection) { return $collection->push(5);}); $collection->all(); // [1, 2, 3, 5]Se puede pasar un segundo callback al método unless. El segundo callback se ejecutará cuando el primer argumento dado al método unless se evalúe como true:
$collection = collect([1, 2, 3]); $collection->unless(true, function (Collection $collection) { return $collection->push(4);}, function (Collection $collection) { return $collection->push(5);}); $collection->all(); // [1, 2, 3, 5]Para la inversa de unless, consulta el método when.
unlessEmpty()
Alias para el método whenNotEmpty.
unlessNotEmpty()
Alias para el método whenEmpty.
unwrap()
El método estático unwrap devuelve los elementos subyacentes de la colección desde el valor dado cuando sea aplicable:
Collection::unwrap(collect('John Doe')); // ['John Doe'] Collection::unwrap(['John Doe']); // ['John Doe'] Collection::unwrap('John Doe'); // 'John Doe'value()
El método value obtiene un valor dado del primer elemento de la colección:
$collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Speaker', 'price' => 400],]); $value = $collection->value('price'); // 200values()
El método values devuelve una nueva colección con las claves restablecidas a enteros consecutivos:
$collection = collect([ 10 => ['product' => 'Desk', 'price' => 200], 11 => ['product' => 'Desk', 'price' => 200],]); $values = $collection->values(); $values->all(); /* [ 0 => ['product' => 'Desk', 'price' => 200], 1 => ['product' => 'Desk', 'price' => 200], ]*/when()
El método when ejecutará la devolución de llamada dada cuando el primer argumento dado al método se evalúe como true. La instancia de la colección y el primer argumento dado al método when se proporcionarán a la devolución de llamada:
$collection = collect([1, 2, 3]); $collection->when(true, function (Collection $collection, int $value) { return $collection->push(4);}); $collection->when(false, function (Collection $collection, int $value) { return $collection->push(5);}); $collection->all(); // [1, 2, 3, 4]Se puede pasar un segundo callback al método when. El segundo callback se ejecutará cuando el primer argumento dado al método when se evalúe como false:
$collection = collect([1, 2, 3]); $collection->when(false, function (Collection $collection, int $value) { return $collection->push(4);}, function (Collection $collection) { return $collection->push(5);}); $collection->all(); // [1, 2, 3, 5]Para la inversa de when, consulta el método unless.
whenEmpty()
El método whenEmpty ejecutará la devolución de llamada dada cuando la colección esté vacía:
$collection = collect(['Michael', 'Tom']); $collection->whenEmpty(function (Collection $collection) { return $collection->push('Adam');}); $collection->all(); // ['Michael', 'Tom'] $collection = collect(); $collection->whenEmpty(function (Collection $collection) { return $collection->push('Adam');}); $collection->all(); // ['Adam']Se puede pasar un segundo cierre al método whenEmpty que se ejecutará cuando la colección no esté vacía:
$collection = collect(['Michael', 'Tom']); $collection->whenEmpty(function (Collection $collection) { return $collection->push('Adam');}, function (Collection $collection) { return $collection->push('Taylor');}); $collection->all(); // ['Michael', 'Tom', 'Taylor']Para la inversa de whenEmpty, consulta el método whenNotEmpty.
whenNotEmpty()
El método whenNotEmpty ejecutará la devolución de llamada dada cuando la colección no esté vacía:
$collection = collect(['michael', 'tom']); $collection->whenNotEmpty(function (Collection $collection) { return $collection->push('adam');}); $collection->all(); // ['michael', 'tom', 'adam'] $collection = collect(); $collection->whenNotEmpty(function (Collection $collection) { return $collection->push('adam');}); $collection->all(); // []Se puede pasar un segundo cierre al método whenNotEmpty que se ejecutará cuando la colección esté vacía:
$collection = collect(); $collection->whenNotEmpty(function (Collection $collection) { return $collection->push('adam');}, function (Collection $collection) { return $collection->push('taylor');}); $collection->all(); // ['taylor']Para la inversa de whenNotEmpty, consulta el método whenEmpty.
where()
El método where filtra la colección por un par clave/valor dado:
$collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 100], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Door', 'price' => 100],]); $filtered = $collection->where('price', 100); $filtered->all(); /* [ ['product' => 'Chair', 'price' => 100], ['product' => 'Door', 'price' => 100], ]*/El método where utiliza comparaciones "laxas" al verificar los valores de los elementos, lo que significa que una cadena con un valor entero se considerará igual a un entero del mismo valor. Utiliza el método whereStrict para filtrar usando comparaciones "estrictas".
Opcionalmente, puedes pasar un operador de comparación como segundo parámetro. Los operadores admitidos son: '===', '!==', '!=', '==', '=', '<>', '>', '<', '>=', y '<=':
$collection = collect([ ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'], ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'], ['name' => 'Sue', 'deleted_at' => null],]); $filtered = $collection->where('deleted_at', '!=', null); $filtered->all(); /* [ ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'], ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'], ]*/whereStrict()
Este método tiene la misma firma que el método where; sin embargo, todos los valores se comparan utilizando comparaciones "estrictas".
whereBetween()
El método whereBetween filtra la colección determinando si el valor de un elemento especificado está dentro de un rango dado:
$collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 80], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Pencil', 'price' => 30], ['product' => 'Door', 'price' => 100],]); $filtered = $collection->whereBetween('price', [100, 200]); $filtered->all(); /* [ ['product' => 'Desk', 'price' => 200], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Door', 'price' => 100], ]*/whereIn()
El método whereIn elimina elementos de la colección que no tienen un valor de elemento especificado que esté contenido en el arreglo dado:
$collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 100], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Door', 'price' => 100],]); $filtered = $collection->whereIn('price', [150, 200]); $filtered->all(); /* [ ['product' => 'Desk', 'price' => 200], ['product' => 'Bookcase', 'price' => 150], ]*/El método whereIn utiliza comparaciones "laxas" al verificar los valores de los elementos, lo que significa que una cadena con un valor entero se considerará igual a un entero del mismo valor. Utiliza el método whereInStrict para filtrar usando comparaciones "estrictas".
whereInStrict()
Este método tiene la misma firma que el método whereIn; sin embargo, todos los valores se comparan utilizando comparaciones "estrictas".
whereInstanceOf()
El método whereInstanceOf filtra la colección por un tipo de clase dado:
use App\Models\User;use App\Models\Post; $collection = collect([ new User, new User, new Post,]); $filtered = $collection->whereInstanceOf(User::class); $filtered->all(); // [App\Models\User, App\Models\User]whereNotBetween()
El método whereNotBetween filtra la colección determinando si el valor de un elemento especificado está fuera de un rango dado:
$collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 80], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Pencil', 'price' => 30], ['product' => 'Door', 'price' => 100],]); $filtered = $collection->whereNotBetween('price', [100, 200]); $filtered->all(); /* [ ['product' => 'Chair', 'price' => 80], ['product' => 'Pencil', 'price' => 30], ]*/whereNotIn()
El método whereNotIn elimina elementos de la colección que tienen un valor de elemento especificado que está contenido en el arreglo dado:
$collection = collect([ ['product' => 'Desk', 'price' => 200], ['product' => 'Chair', 'price' => 100], ['product' => 'Bookcase', 'price' => 150], ['product' => 'Door', 'price' => 100],]); $filtered = $collection->whereNotIn('price', [150, 200]); $filtered->all(); /* [ ['product' => 'Chair', 'price' => 100], ['product' => 'Door', 'price' => 100], ]*/El método whereNotIn utiliza comparaciones "laxas" al verificar los valores de los elementos, lo que significa que una cadena con un valor entero se considerará igual a un entero del mismo valor. Utiliza el método whereNotInStrict para filtrar usando comparaciones "estrictas".
whereNotInStrict()
Este método tiene la misma firma que el método whereNotIn; sin embargo, todos los valores se comparan utilizando comparaciones "estrictas".
whereNotNull()
El método whereNotNull devuelve elementos de la colección donde la clave dada no es null:
$collection = collect([ ['name' => 'Desk'], ['name' => null], ['name' => 'Bookcase'],]); $filtered = $collection->whereNotNull('name'); $filtered->all(); /* [ ['name' => 'Desk'], ['name' => 'Bookcase'], ]*/whereNull()
El método whereNull devuelve elementos de la colección donde la clave dada es null:
$collection = collect([ ['name' => 'Desk'], ['name' => null], ['name' => 'Bookcase'],]); $filtered = $collection->whereNull('name'); $filtered->all(); /* [ ['name' => null], ]*/wrap()
El método estático wrap envuelve el valor dado en una colección cuando sea aplicable:
use Illuminate\Support\Collection; $collection = Collection::wrap('John Doe'); $collection->all(); // ['John Doe'] $collection = Collection::wrap(['John Doe']); $collection->all(); // ['John Doe'] $collection = Collection::wrap(collect('John Doe')); $collection->all(); // ['John Doe']zip()
El método zip fusiona los valores del arreglo dado con los valores de la colección original en su índice correspondiente:
$collection = collect(['Chair', 'Desk']); $zipped = $collection->zip([100, 200]); $zipped->all(); // [['Chair', 100], ['Desk', 200]]Mensajes de Orden Superior
Las colecciones también proporcionan soporte para "mensajes de orden superior", que son atajos para realizar acciones comunes en colecciones. Los métodos de colección que proporcionan mensajes de orden superior son: average, avg, contains, each, every, filter, first, flatMap, groupBy, keyBy, map, max, min, partition, reject, skipUntil, skipWhile, some, sortBy, sortByDesc, sum, takeUntil, takeWhile, y unique.
Cada mensaje de orden superior se puede acceder como una propiedad dinámica en una instancia de colección. Por ejemplo, usemos el mensaje de orden superior each para llamar a un método en cada objeto dentro de una colección:
use App\Models\User; $users = User::where('votes', '>', 500)->get(); $users->each->markAsVip();Del mismo modo, podemos usar el mensaje de orden superior sum para recopilar el número total de "votos" para una colección de usuarios:
$users = User::where('group', 'Development')->get(); return $users->sum->votes;Colecciones Lazy
Introducción
Advertencia Antes de aprender más sobre las colecciones perezosas de Laravel, tómate un tiempo para familiarizarte con los generadores de PHP.
Para complementar la ya poderosa clase Collection, la clase LazyCollection aprovecha los generadores de PHP para permitirte trabajar con conjuntos de datos muy grandes manteniendo bajos los niveles de uso de memoria.
Por ejemplo, imagina que tu aplicación necesita procesar un archivo de registro de varios gigabytes aprovechando los métodos de colección de Laravel para analizar los registros. En lugar de leer todo el archivo en memoria de una vez, las colecciones perezosas se pueden utilizar para mantener solo una pequeña parte del archivo en memoria en un momento dado:
use App\Models\LogEntry;use Illuminate\Support\LazyCollection; LazyCollection::make(function () { $handle = fopen('log.txt', 'r'); while (($line = fgets($handle)) !== false) { yield $line; }})->chunk(4)->map(function (array $lines) { return LogEntry::fromLines($lines);})->each(function (LogEntry $logEntry) { // Procesar la entrada del registro...});O, imagina que necesitas iterar a través de 10,000 modelos Eloquent. Cuando usas colecciones de Laravel tradicionales, los 10,000 modelos Eloquent deben cargarse en memoria al mismo tiempo:
use App\Models\User; $users = User::all()->filter(function (User $user) { return $user->id > 500;});Sin embargo, el método cursor del constructor de consultas devuelve una instancia de LazyCollection. Esto te permite seguir ejecutando una sola consulta contra la base de datos, pero también mantener solo un modelo Eloquent cargado en memoria a la vez. En este ejemplo, el callback de filter no se ejecuta hasta que realmente iteramos sobre cada usuario individualmente, lo que permite una reducción drástica en el uso de memoria:
use App\Models\User; $users = User::cursor()->filter(function (User $user) { return $user->id > 500;}); foreach ($users as $user) { echo $user->id;}Creación de Colecciones Lazy
Para crear una instancia de colección perezosa, debes pasar una función generadora de PHP al método make de la colección:
use Illuminate\Support\LazyCollection; LazyCollection::make(function () { $handle = fopen('log.txt', 'r'); while (($line = fgets($handle)) !== false) { yield $line; }});El Contrato Enumerable
Casi todos los métodos disponibles en la clase Collection también están disponibles en la clase LazyCollection. Ambas clases implementan el contrato Illuminate\Support\Enumerable, que define los siguientes métodos:
all average avg chunk chunkWhile collapse collect combine concat contains containsStrict count countBy crossJoin dd diff diffAssoc diffKeys dump duplicates duplicatesStrict each eachSpread every except filter first firstOrFail firstWhere flatMap flatten flip forPage get groupBy has implode intersect intersectAssoc intersectByKeys isEmpty isNotEmpty join keyBy keys last macro make map mapInto mapSpread mapToGroups mapWithKeys max median merge mergeRecursive min mode nth only pad partition pipe pluck random reduce reject replace replaceRecursive reverse search shuffle skip slice sole some sort sortBy sortByDesc sortKeys sortKeysDesc split sum take tap times toArray toJson union unique uniqueStrict unless unlessEmpty unlessNotEmpty unwrap values when whenEmpty whenNotEmpty where whereStrict whereBetween whereIn whereInStrict whereInstanceOf whereNotBetween whereNotIn whereNotInStrict wrap zip
Advertencia Los métodos que mutan la colección (como
shift,pop,prepend, etc.) no están disponibles en la claseLazyCollection.
Métodos de Colecciones Lazy
Además de los métodos definidos en el contrato Enumerable, la clase LazyCollection contiene los siguientes métodos:
takeUntilTimeout()
El método takeUntilTimeout devuelve una nueva colección perezosa que enumerará valores hasta el tiempo especificado. Después de ese tiempo, la colección dejará de enumerar:
$lazyCollection = LazyCollection::times(INF) ->takeUntilTimeout(now()->addMinute()); $lazyCollection->each(function (int $number) { dump($number); sleep(1);}); // 1// 2// ...// 58// 59Para ilustrar el uso de este método, imagina una aplicación que envía facturas desde la base de datos utilizando un cursor. Podrías definir una tarea programada que se ejecuta cada 15 minutos y solo procesa facturas durante un máximo de 14 minutos:
use App\Models\Invoice;use Illuminate\Support\Carbon; Invoice::pending()->cursor() ->takeUntilTimeout( Carbon::createFromTimestamp(LARAVEL_START)->add(14, 'minutes') ) ->each(fn (Invoice $invoice) => $invoice->submit());tapEach()
Mientras que el método each llama al callback dado para cada elemento en la colección de inmediato, el método tapEach solo llama al callback dado a medida que los elementos se extraen de la lista uno por uno:
// Hasta ahora no se ha volcado nada...$lazyCollection = LazyCollection::times(INF)->tapEach(function (int $value) { dump($value);}); // Se han volcado tres elementos...$array = $lazyCollection->take(3)->all(); // 1// 2// 3remember()
El método remember devuelve una nueva colección perezosa que recordará cualquier valor que ya se haya enumerado y no los recuperará nuevamente en enumeraciones posteriores:
// Todavía no se ha ejecutado ninguna consulta...$users = User::cursor()->remember(); // Se ejecuta la consulta...// Los primeros 5 usuarios se hidratan desde la base de datos...$users->take(5)->all(); // Los primeros 5 usuarios provienen de la caché de la colección...// El resto se hidrata desde la base de datos...$users->take(20)->all();