Illuminate Collections

https://github.com/illuminate/collections
Admin
Illuminate Collections is a Laravel package providing a fluent, chainable wrapper for working with...
Tokens:156,571
Snippets:1,132
Trust Score:7.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### get() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Demonstrates get() with existing keys, null values, missing keys with a fallback, and a lazy closure default. Keys with null values are still returned because get() uses array_key_exists.

```php
$c = new Collection(['name' => 'Ada', 'meta' => null]);
$c->get('name');                    // 'Ada'
$c->get('meta');                    // null (key exists)
$c->get('missing', 'fallback');     // 'fallback'
$c->get('missing', fn () => expensiveDefault()); // lazy
```

--------------------------------

### Usage examples for static factories

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Shows example calls to times, fromJson, and wrap, demonstrating their output.

```php
Collection::times(3, fn ($i) => $i ** 2);     // [1, 4, 9]
Collection::fromJson('{"a":1}');              // ['a' => 1]
LazyCollection::wrap('single');               // LazyCollection(['single'])
```

--------------------------------

### End-to-end collection querying example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

End-to-end example of querying a collection: filtering with where(), counting, summing, retrieving a single item with sole(), and using get() with fallback. Also shows catching ItemNotFoundException when sole() finds no match.

```php
use Illuminate\Support\Collection;

$orders = new Collection([
    ['id' => 1, 'user' => 'ada', 'total' => 100],
    ['id' => 2, 'user' => 'grace', 'total' => 250],
    ['id' => 3, 'user' => 'ada', 'total' => 75],
]);

$adaInvoices = $orders->where('user', 'ada');          // where() is trait-provided
$adaInvoices->count();                                  // 2
$adaInvoices->sum('total');                             // 175
$order = $orders->sole('id', 2);                        // Grace's order
$missing = $orders->get(0) ?? $orders->first();         // first order

try {
    $orders->sole('user', 'nobody');
} catch (\Illuminate\Support\ItemNotFoundException) {
    // zero matches
}
```

--------------------------------

### Dot-notation access usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Arr.md

Usage example for dot-notation access. Demonstrates `get`, `set`, `has`, `pull`, and `forget` on a nested config array. `pull` returns the value and removes the key; `forget` removes the key.

```php
$config = ['database' => ['host' => 'localhost']];
Arr::get($config, 'database.host');              // 'localhost'
Arr::get($config, 'missing.key', 'fallback');    // 'fallback'
Arr::set($config, 'database.port', 5432);
Arr::has($config, ['database.host', 'database.port']); // true
$host = Arr::pull($config, 'database.host');     // 'localhost'; key removed
Arr::forget($config, 'database.port');
```

--------------------------------

### data_get() usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Helpers.md

Example usage of data_get() with wildcard, dot-notation, default value, and {first} segment.

```php
$data = ['users' => [['name' => 'Ada'], ['name' => 'Grace']], 'meta' => ['page' => 1]];
data_get($data, 'users.*.name');        // ['Ada', 'Grace']
data_get($data, 'meta.page');           // 1
data_get($data, 'missing', 'fallback'); // 'fallback'
data_get($data, 'users.{first}.name');  // 'Ada'
```

--------------------------------

### Collection constructor usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection.md

Usage examples for the Collection constructor. Shows creating from an array, from null (empty collection), and from an object (cast to array).

```php
use Illuminate\Support\Collection;

// From an array or iterable
$orders = new Collection([
    ['id' => 1, 'total' => 450.0],
    ['id' => 2, 'total' => 129.5],
]);

// From an Arrayable (e.g. an Eloquent model's toArray), or null for empty
$empty = new Collection(null);
$fromObject = new Collection((object) ['a' => 1]); // Arr::from casts object → ['a' => 1]
```

--------------------------------

### Partition usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Shows how to split a collection into passed and failed groups using a callback, with the resulting arrays.

```php
[$passed, $failed] = (new Collection([1, 2, 3]))->partition(fn ($n) => $n % 2 === 0);
// $passed = [2], $failed = [1, 3]
```

--------------------------------

### map() example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Example of using map() to double each value in a collection. The callback receives each value and returns the new value; keys are preserved.

```php
$c = new Collection([1, 2, 3]);
$doubled = $c->map(fn ($n) => $n * 2);   // [2, 4, 6]
```

--------------------------------

### Where filtering usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Example collection of products and usage of `where`, `whereNull`, `whereBetween`, and `whereIn` with expected results. Demonstrates filtering by price, null stock, price range, and name inclusion.

```php
$products = new Collection([
    ['name' => 'Desk', 'price' => 200, 'stock' => 5],
    ['name' => 'Chair', 'price' => 100, 'stock' => null],
    ['name' => 'Lamp', 'price' => 40, 'stock' => null],
]);
$products->where('price', '>', 50);          // Desk, Chair
$products->whereNull('stock');               // Chair, Lamp
$products->whereBetween('price', [40, 150]); // Chair, Lamp
$products->whereIn('name', ['Desk', 'Lamp']); // Desk, Lamp
```

--------------------------------

### collapse() and collapseWithKeys() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Examples of collapse() merging nested arrays into a list and collapseWithKeys() flattening one level while preserving outer keys.

```php
(new Collection([[1, 2], [3, 4]]))->collapse();                 // [1, 2, 3, 4]
(new Collection(['a' => [1], 'b' => [2]]))->collapseWithKeys(); // ['a' => 1, 'b' => 2]
```

--------------------------------

### mapToDictionary() and mapWithKeys() example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Example showing the difference between mapToDictionary() and mapWithKeys(). mapToDictionary groups values by the returned key, while mapWithKeys uses the returned key as the new key with the value as the new value.

```php
$users = new Collection([['id' => 1, 'role' => 'admin'], ['id' => 2, 'role' => 'admin'], ['id' => 3, 'role' => 'dev']]);
$users->mapToDictionary(fn ($u) => [$u['role'] => $u['id']]); // ['admin' => [1, 2], 'dev' => [3]]
$users->mapWithKeys(fn ($u) => [$u['id'] => $u['role']]);     // [1 => 'admin', 2 => 'admin', 3 => 'dev']
```

--------------------------------

### pluck() examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Example of pluck() with a dot-notation path, with re-keying, and with a closure. The closure receives each item and returns the value to extract.

```php
$items = new Collection([['id' => 1, 'meta' => ['slug' => 'a']], ['id' => 2, 'meta' => ['slug' => 'b']]]);
$items->pluck('meta.slug');                 // ['a', 'b']
$items->pluck('meta.slug', 'id');           // [1 => 'a', 2 => 'b']
$items->pluck(fn ($i) => strtoupper($i['meta']['slug'])); // ['A', 'B']
```

--------------------------------

### Map family usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Demonstrates mapSpread with a sum callback and mapInto with SplStack, showing the resulting collections.

```php
(new Collection([[1, 2], [3, 4]]))->mapSpread(fn ($a, $b) => $a + $b);  // [3, 7]
(new Collection([1, 2]))->mapInto(\SplStack::class);          // two SplStack instances
```

--------------------------------

### Collection transformation examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Example demonstrating keyBy, map, groupBy, pluck, implode, values, and pad methods on a Collection of associative arrays. Shows how to re-key, compute totals, group, flatten, and pad.

```php
use Illuminate\Support\Collection;

$rows = new Collection([
    ['sku' => 'A1', 'qty' => 2, 'price' => 10],
    ['sku' => 'B2', 'qty' => 1, 'price' => 25],
]);

$bySku = $rows->keyBy('sku');                                   // re-keyed
$totals = $bySku->map(fn ($r) => $r['qty'] * $r['price']);      // ['A1' => 20, 'B2' => 25]
$lines = $bySku->groupBy(fn ($r) => $r['qty'] > 1 ? 'multi' : 'single');
$flat  = $rows->pluck('sku')->implode('-');                     // 'A1-B2'
$padded = $totals->values()->pad(3, 0);                         // [20, 25, 0]
```

--------------------------------

### collect() usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Helpers.md

Example usage of collect() to create a collection and chain filter() and sum().

```php
$prices = collect([199, 299, 499]);
$total = $prices->filter(fn ($p) => $p > 200)->sum();   // 798
```

--------------------------------

### nth method signature and usage

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Shows the nth method signature with its docblock and usage examples. Yields every $step-th item starting after $offset. Throws InvalidArgumentException('Step value must be at least 1.') when $step < 1.

```php
/**
 * @return ($step is positive-int ? static : never)
 * @throws \InvalidArgumentException
 */
public function nth($step, $offset = 0)
```

```php
(new Collection([1, 2, 3, 4, 5, 6]))->nth(2);      // [1, 3, 5]
(new Collection([1, 2, 3, 4, 5, 6]))->nth(2, 1);   // [2, 4, 6]
```

--------------------------------

### LazyCollection usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/LazyCollection.md

Three examples showing how to create a LazyCollection: with a generator function, a fatal attempt with a Generator instance, and an array-backed collection.

```php
use Illuminate\Support\LazyCollection;

// 1. A generator function — note: NOT a Generator instance
$lazy = new LazyCollection(function () {
    $file = fopen('huge.csv', 'r');
    while (($row = fgetcsv($file)) !== false) {
        yield $row;
    }
    fclose($file);
});

// 2. Fatal: passing a fresh Generator throws
// $lazy = new LazyCollection((function () { yield 1; })());  // InvalidArgumentException

// 3. Array-backed
$fromArray = new LazyCollection([1, 2, 3]);
```

--------------------------------

### keyBy usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Example of re-keying a collection by the 'id' field. The resulting collection uses the id values as keys.

```php
$users->keyBy('id');   // [1 => ['id' => 1, ...], 2 => [...], ...]
```

--------------------------------

### Conditional application example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Example chaining `when`, `unlessNotEmpty`, and `whenNotEmpty` on a collection. `when` pushes 'no flash' if `$flash` is empty, `unlessNotEmpty` pushes 'empty!' if the collection is empty, and `whenNotEmpty` calls `values()` if not empty.

```php
$collection
    ->when(empty($flash), fn ($c) => $c->push('no flash'))
    ->unlessNotEmpty(fn ($c) => $c->push('empty!'))
    ->whenNotEmpty(fn ($c) => $c->values());
```

--------------------------------

### Aggregation usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Example of using avg, percentage, and max on a Collection. avg returns 20, percentage returns 66.67, max returns 30.

```php
$c = new Collection([10, 20, 30]);
$c->avg();                     // 20
$c->percentage(fn ($n) => $n > 15);   // 66.67
$c->max();                     // 30
```

--------------------------------

### Collection::range usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection.md

Usage examples for Collection::range. Shows ascending and descending ranges with a step.

```php
Collection::range(1, 5);            // [1, 2, 3, 4, 5]
Collection::range(5, 1, 2);         // [5, 3, 1]
```

--------------------------------

### unique() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Examples of unique() removing duplicates while preserving first-match keys.

```php
(new Collection([1, 1, 2, 2, 3]))->unique();          // [1, 2, 3]
(new Collection(['a' => 1, 'b' => 2, 'c' => 2]))->unique(); // ['a' => 1, 'b' => 2]
```

--------------------------------

### data_set() usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Helpers.md

Example usage of data_set() to set nested dot-notation keys.

```php
$config = [];
data_set($config, 'db.host', 'localhost');
data_set($config, 'db.port', 5432);
// $config === ['db' => ['host' => 'localhost', 'port' => 5432]]
```

--------------------------------

### when() usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Helpers.md

Example usage of when() with a boolean condition and a closure condition.

```php
$role = when($user->isAdmin(), 'admin', 'member');
when(env('APP_DEBUG'), fn () => error_reporting(E_ALL));
```

--------------------------------

### Reduce and reduceSpread usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Demonstrates reduce to sum values and reduceSpread to accumulate sum and product, yielding [10, 24].

```php
$c = new Collection([1, 2, 3, 4]);
$c->reduce(fn ($carry, $n) => $carry + $n, 0);               // 10
$c->reduceSpread(fn ($sum, $prod, $n) => [$sum + $n, $prod * $n], 0, 1); // [10, 24]
```

--------------------------------

### crossJoin usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-set-operations.md

Usage example for crossJoin. Produces the cartesian product of the collection and the given list.

```php
(new Collection([1, 2]))->crossJoin(['a', 'b']);
// [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
```

--------------------------------

### select() example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-set-operations.md

Creates a collection of product arrays and uses select() to pick only the 'name' and 'price' keys from each item, producing a new collection of filtered arrays.

```php
$products = new Collection([
    ['name' => 'Desk', 'price' => 200, 'secret' => 1],
    ['name' => 'Chair', 'price' => 100, 'secret' => 2],
]);
$products->select(['name', 'price']);
// [['name' => 'Desk', 'price' => 200], ['name' => 'Chair', 'price' => 100]]
```

--------------------------------

### Usage examples for property and method proxying

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/HigherOrderCollectionProxy.md

Demonstrates using the proxy for property access (map->name, first->name, keyBy->age, sum->age) and method calls (each->notify, filter->isAdmin).

```php
use Illuminate\Support\Collection;

$users = new Collection([
    (object) ['name' => 'Ada',  'age' => 36],
    (object) ['name' => 'Grace', 'age' => 44],
]);

$names = $users->map->name;                 // ['Ada', 'Grace']
$first = $users->first->name;               // 'Ada'
$byAge = $users->keyBy->age;                // [36 => user, 44 => user]
$sum   = $users->sum->age;                  // 80

// Method proxying onto items
$users->each->notify('welcome');            // each(fn ($u) => $u->notify('welcome'))
$users->filter->isAdmin();                  // filter(fn ($u) => $u->isAdmin())
```

--------------------------------

### Sorting examples with sort, sortByDesc, sortKeysDesc, and sortBy

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-iteration.md

Examples showing basic sorting, descending sort, key sort descending, and sorting by a computed value. The first block shows sort, sortByDesc, and sortKeysDesc on a simple associative array. The second block shows sortBy with a path string. The third block shows sortBy with an array of comparisons for multi-key sorting.

```php
$c = new Collection(['b' => 2, 'a' => 1, 'c' => 3]);
$c->sort();                                    // ['a' => 1, 'b' => 2, 'c' => 3]
$c->sortByDesc();                              // ['c' => 3, 'b' => 2, 'a' => 1]
$c->sortKeysDesc();                            // ['c' => 3, 'b' => 2, 'a' => 1]
```

```php
(new Collection([
    ['name' => 'Desk', 'price' => 200],
    ['name' => 'Chair', 'price' => 100],
]))->sortBy('price')->all();
// [['name' => 'Chair', 'price' => 100], ['name' => 'Desk', 'price' => 200]]
```

```php
(new Collection([
    ['name' => 'Desk', 'price' => 200],
    ['name' => 'Desk', 'price' => 100],
]))->sortBy([['name', 'asc'], ['price', 'desc']])->all();
// [['name' => 'Desk', 'price' => 200], ['name' => 'Desk', 'price' => 100]]
```

--------------------------------

### transform() usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Example usage of transform() with a callback that multiplies each item by 10. The collection is modified in place and the same instance is returned.

```php
$c = new Collection([1, 2]);
$c->transform(fn ($n) => $n * 10);
// $c is now [10, 20]; returns $c (same instance)
```

--------------------------------

### first() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Demonstrates first() with no callback, a callback, and a default value. The default may be a closure.

```php
$c = new Collection([10, 20, 30]);
$c->first();                        // 10
$c->first(fn ($v) => $v > 15);      // 20
$c->first(fn ($v) => $v > 99, 0);   // 0
```

--------------------------------

### take, skip, takeUntil, takeWhile, skipWhile usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-iteration.md

Demonstrates the behavior of take, skip, takeUntil, takeWhile, and skipWhile on a sample collection.

```php
$c = new Collection([1, 2, 3, 4, 5]);
$c->take(2);              // [1, 2]
$c->take(-2);             // [4, 5]  (last two)
$c->skip(2);              // [3, 4, 5]
$c->takeUntil(4);         // [1, 2, 3]
$c->takeWhile(fn ($n) => $n < 3); // [1, 2]
$c->skipWhile(fn ($n) => $n < 3); // [3, 4, 5]
```

--------------------------------

### groupBy usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Example of grouping a collection by a string key and by a callback. The first call groups by the 'type' field, the second uses a callback to produce custom keys ('sweet' or 'savory').

```php
$items = new Collection([
    ['type' => 'fruit', 'name' => 'apple'],
    ['type' => 'fruit', 'name' => 'pear'],
    ['type' => 'veg', 'name' => 'onion'],
]);
$items->groupBy('type');
// ['fruit' => [['type' => 'fruit', 'name' => 'apple'], [...]], 'veg' => [...]]
$items->groupBy(fn ($i) => $i['type'] === 'fruit' ? 'sweet' : 'savory'); // custom keys
```

--------------------------------

### Serialization usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Example calls showing the output of toJson(), toPrettyJson(), and the string cast. The toJson() output is shown as '[{"a":1}]', toPrettyJson() produces pretty-printed JSON, and the string cast yields '[1,2]'.

```php
collect([['a' => 1]])->toJson();            // '[{"a":1}]'
collect([['a' => 1]])->toPrettyJson();      // pretty-printed
(string) collect([1, 2]);                   // '[1,2]'
```

--------------------------------

### zip, pad, combine, multiply method signatures and usage

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Shows the method signatures for zip, pad, combine, and multiply, followed by usage examples with expected outputs. zip creates pairwise tuples, pad uses array_pad semantics (negative size pads left), combine uses items as keys, and multiply repeats items.

```php
public function zip($items)                    // Collection.php:1861
public function pad($size, $value)             // Collection.php:1879
public function combine($values)               // Collection.php:917
public function multiply(int $multiplier)      // Collection.php:898
```

```php
(new Collection([1, 2, 3]))->zip([4, 5]);      // [[1, 4], [2, 5], [3, null]]
(new Collection([1, 2]))->pad(4, 0);           // [1, 2, 0, 0]
(new Collection(['a', 'b']))->combine([1, 2]); // ['a' => 1, 'b' => 2]
(new Collection([1, 2]))->multiply(2);         // [1, 2, 1, 2]
```

--------------------------------

### Using toResourceCollection with explicit and auto-resolved resources

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-TransformsToResourceCollection.md

Usage example showing explicit resource class and auto-resolution with try/catch for LogicException when no resource can be resolved.

```php
use Illuminate\Support\Collection;

// Explicit resource
$collection->toResourceCollection(OrderResource::class);

// Auto-resolve from Eloquent model attributes / guessResourceName()
try {
    $resource = Order::all()->toResourceCollection();
} catch (\LogicException $e) {
    // no resource could be resolved for the model class
}
```

--------------------------------

### Pipe and pipeThrough usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Chains pipe and pipeThrough to sum values, multiply by 2, and add 1, resulting in 13.

```php
$result = collect([1, 2, 3])
    ->pipe(fn ($c) => $c->sum())
    ->pipeThrough([fn ($v) => $v * 2, fn ($v) => $v + 1]);   // 13
```

--------------------------------

### dot and undot usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Examples of dot and undot. dot flattens a nested array into dot-keys; undot expands dot-keys back into nested arrays.

```php
(new Collection(['user' => ['name' => 'Ada']]))->dot();  // ['user.name' => 'Ada']
(new Collection(['user.name' => 'Ada']))->undot();       // ['user' => ['name' => 'Ada']]
```

--------------------------------

### Using firstOrFail with exception handling

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Example of using firstOrFail with a where-style filter and catching the ItemNotFoundException when no item matches.

```php
try {
    $order = $orders->firstOrFail('status', 'pending');
} catch (\Illuminate\Support\ItemNotFoundException) {
    // handle absence
}
```

--------------------------------

### Callback-driven predicate usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Example of using every, firstWhere, and value on a collection of associative arrays. every returns true, firstWhere returns the first matching array, value returns the id of the first item.

```php
$orders = new Collection([['status' => 'paid', 'id' => 1], ['status' => 'new', 'id' => 2]]);
$orders->every('status', '!=', 'cancelled');          // true
$orders->firstWhere('status', 'paid');                // ['status' => 'paid', 'id' => 1]
$orders->value('id');                                 // 1
```

--------------------------------

### ArrayAccess usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection.md

Demonstrates using ArrayAccess on a Collection: assigning by key, appending with null offset, checking existence, and unsetting.

```php
$c = new Collection();
$c['name'] = 'Ada';        // offsetSet with key
$c[] = 'extra';            // offsetSet with null → append
isset($c['name']);         // true (offsetExists)
unset($c['name']);         // offsetUnset
```

--------------------------------

### join() and implode() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Demonstrates join() with a final glue and implode() with a key and glue. join separates only the last element when finalGlue is provided.

```php
(new Collection(['a', 'b', 'c']))->join(', ', ' and ');   // 'a, b and c'
(new Collection([['x' => 1], ['x' => 2]]))->implode('x', '-'); // '1-2'
```

--------------------------------

### countBy() usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection.md

Demonstrates grouping and counting with countBy(), including a callback that maps values to custom keys.

```php
$stats = new Collection(['a', 'b', 'a', 'c', 'b', 'b']);
$stats->countBy();            // ['a' => 2, 'b' => 3, 'c' => 1]
$stats->countBy(fn ($v) => $v === 'b' ? 'bee' : 'other'); // ['bee' => 3, 'other' => 3]
```

--------------------------------

### Higher-order proxy access example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection.md

Shows higher-order proxy access via __get, which returns a HigherOrderCollectionProxy for allowed properties or throws an exception otherwise.

```php
$users->map->name;                 // map(fn ($u) => $u->name)
$users->filter->isActive();        // filter(fn ($u) => $u->isActive())
```

--------------------------------

### Collection stack/queue mutation example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-iteration.md

Demonstrates the stack/queue mutation methods on an Illuminate Collection: push, prepend, put, pop, shift, pull, and add. Shows chaining and return types: push/prepend/put/add return $this, pop returns a value when count is 1, shift returns a collection when count > 1, and pull removes and returns the value.

```php
$c = new Collection([1, 2]);
$c->push(3)->push(4);          // [1, 2, 3, 4] ($this chained)
$c->prepend(0);                // [0, 1, 2, 3, 4]
$c->put('key', 'v');           // ['key' => 'v', 0 => 0, 1 => 1, ...]
$popped = $c->pop();           // 'v'; collection loses it
$shifted = $c->shift(2);       // [1, 2] removed, returned as collection
$pulled = $c->pull(0);         // 0 removed and returned
$c->add('tail');               // appended
```

--------------------------------

### splice() usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-iteration.md

Demonstrates removing a slice with splice(1, 2) and inserting with splice(1, 0, [9, 9]).

```php
$c = new Collection([1, 2, 3, 4, 5]);
$removed = $c->splice(1, 2);      // removed: [2, 3]; $c is now [1, 4, 5]
$c->splice(1, 0, [9, 9]);         // insert: $c is [1, 9, 9, 4, 5]
```

--------------------------------

### has() and hasAny() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Demonstrates has() and hasAny() with a sample collection. has('a') returns true, has(['a', 'missing']) returns false because 'missing' is absent, and hasAny(['a', 'missing']) returns true because 'a' exists.

```php
$c = new Collection(['a' => 1, 'b' => 2]);
$c->has('a');                    // true
$c->has(['a', 'missing']);      // false
$c->hasAny(['a', 'missing']);   // true
```

--------------------------------

### ensure() usage example with exception handling

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Shows how to call ensure() with an invalid type, catching the UnexpectedValueException. The exception message indicates the expected and found types.

```php
try {
    (new Collection([1, 'two']))->ensure('int');
} catch (\UnexpectedValueException $e) {
    // "Collection should only include [int] items, but 'string' found at position 1."
}
```

--------------------------------

### random() usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-iteration.md

Demonstrates calling random() with no arguments, an integer, and an excessive count that throws InvalidArgumentException.

```php
$deck = new Collection(range(1, 52));
$card = $deck->random();                     // int
$hand  = $deck->random(5);                   // Collection of 5
try {
    $deck->random(100);
} catch (\InvalidArgumentException $e) {
    // requested more than available
}
```

--------------------------------

### get() method signature with docblock

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Shows the signature and docblock for Collection::get(). The default can be a closure, invoked lazily when the key is missing. A null key is normalized to an empty string.

```php
/**
 * @template TGetDefault
 * @param  TKey|null  $key
 * @param  TGetDefault|(\Closure(): TGetDefault)  $default
 * @return TValue|TGetDefault
 */
public function get($key, $default = null)
```

--------------------------------

### Using sole with exception handling

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Example of using sole with a key/operator/value filter and catching the two possible exceptions. The MultipleItemsFoundException provides a getCount() method to know how many items matched.

```php
try {
    $user = $users->sole('email', 'ada@example.com');
} catch (\Illuminate\Support\ItemNotFoundException) {
    // no matching user
} catch (\Illuminate\Support\MultipleItemsFoundException $e) {
    // $e->getCount() — how many matched
}
```

--------------------------------

### Arr::pluck, dot, and undot usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Arr.md

Shows usage of Arr::pluck with dot-notation paths and an optional key, plus Arr::dot and Arr::undot for flattening and expanding nested arrays. The comments show the expected output for each call.

```php
$rows = [['id' => 1, 'user' => ['name' => 'Ada']], ['id' => 2, 'user' => ['name' => 'Grace']]];
Arr::pluck($rows, 'user.name');                  // ['Ada', 'Grace']
Arr::pluck($rows, 'user.name', 'id');            // [1 => 'Ada', 2 => 'Grace']
Arr::dot(['user' => ['name' => 'Ada']]);         // ['user.name' => 'Ada']
Arr::undot(['user.name' => 'Ada']);              // ['user' => ['name' => 'Ada']]
```

--------------------------------

### median() and mode() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Demonstrates median() and mode() on a collection. median returns the middle value (or average of two middles), mode returns the sorted list of most frequent values.

```php
$c = new Collection([1, 2, 2, 3, 3]);
$c->median();   // 2
$c->mode();     // [2, 3]
```

--------------------------------

### contains() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Demonstrates contains() with a key, a key-value pair, and a callable. The first returns true for existence, the second uses where-style comparison, and the third uses a predicate.

```php
$c = new Collection(['product' => 'Desk', 'price' => 200]);
$c->contains('product');                       // true (existence)
$c->contains('product', 'Desk');               // true (price … where-style)
$c->contains(fn ($v) => $v > 100);             // true
```

--------------------------------

### getOrPut() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Demonstrates getOrPut() returning an existing value and storing a new value when the key is missing. The closure value is resolved and stored.

```php
$c = new Collection(['count' => 1]);
$c->getOrPut('count', 99);     // 1 — key existed
$c->getOrPut('other', fn () => 42); // 42 — stored; $c->get('other') === 42
```

--------------------------------

### before() and after() usage

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-querying.md

Demonstrates the before() and after() methods. They return the item at the previous or next position relative to the given value, or null if the value is not found or is at the boundary.

```php
$c = new Collection(['a', 'b', 'c']);
$c->before('b');   // 'a'
$c->after('b');    // 'c'
$c->before('a');   // null
```

--------------------------------

### Register a custom proxy

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/HigherOrderCollectionProxy.md

Shows how to register a custom proxy method using Collection::proxy, then use it in a chain.

```php
// Register a custom proxy
Collection::proxy('sortByName');
$items->sortByName->all();                  // resolves property 'sortByName' → proxy… (custom userland method chain)
```

--------------------------------

### filter() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-transformation.md

Examples of filter() without a callback (removes falsy values) and with a callback (keeps items where the callback returns true). Keys are preserved.

```php
(new Collection([0, 1, 2, null, 'a']))->filter();        // [1, 2, 'a']
(new Collection([1, 2, 3]))->filter(fn ($n) => $n > 1);  // [2, 3]
```

--------------------------------

### replace and replaceRecursive usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-set-operations.md

Usage examples for replace and replaceRecursive. replace uses array_replace, replaceRecursive uses array_replace_recursive. Unlike merge, numeric keys are replaced positionally.

```php
(new Collection([1, 2]))->replace([9]);             // [9, 2]
(new Collection(['a' => ['x' => 1]]))->replaceRecursive(['a' => ['y' => 2]]); // ['a' => ['x' => 1, 'y' => 2]]
```

--------------------------------

### merge and mergeRecursive usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-set-operations.md

Usage examples for merge and mergeRecursive. merge overwrites string keys and re-indexes numeric keys; mergeRecursive merges nested arrays recursively.

```php
(new Collection(['a' => 1]))->merge(['a' => 2, 'b' => 3]);  // ['a' => 2, 'b' => 3]
(new Collection(['a' => [1]]))->mergeRecursive(['a' => [2]]); // ['a' => [1, 2]]
```

--------------------------------

### Arr::toCssClasses usage example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Arr.md

Example call to `Arr::toCssClasses` with a mix of numeric and boolean-constrained entries. The output is `'p-4 bg-red'` when `$isError` is true, and `'hidden'` is omitted when `$isHidden` is false.

```php
Arr::toCssClasses(['p-4', 'bg-red' => $isError, 'hidden' => $isHidden]);
// 'p-4 bg-red' when $isError true — 'hidden' omitted when false
```

--------------------------------

### LazyCollection flatten and sortDesc example

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/LazyCollection-operations.md

Shows that flatten streams lazily while sortDesc is eager, producing a sorted array. The example creates a LazyCollection from nested arrays and calls flatten()->sortDesc()->all().

```php
$lazy = new LazyCollection([[2, 1], [4, 3]]);
$lazy->flatten()->sortDesc()->all();      // [4, 3, 2, 1] — flatten streams, sort is eager
```

--------------------------------

### duplicates and duplicatesStrict usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-set-operations.md

Usage examples for duplicates and duplicatesStrict. The first returns duplicate values keyed by original key; the second with strict mode returns empty because 'a' and 'A' are different cases.

```php
(new Collection([1, 2, 1, 3, 2]))->duplicates();        // [2 => 1, 4 => 2]
(new Collection(['a', 'A']))->duplicates(null, true);   // [] (strict — different case)
```

--------------------------------

### LazyCollection::range() usage examples

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/LazyCollection.md

Shows two example calls to LazyCollection::range(). The first demonstrates lazy generation without allocating an array; the second shows a descending range with a step of 2, producing 10, 8, 6, 4, 2.

```php
LazyCollection::range(1, 1_000_000);      // lazy — no array allocated
LazyCollection::range(10, 1, 2);          // 10, 8, 6, 4, 2
```

--------------------------------

### __get equivalent closure

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/HigherOrderCollectionProxy.md

Shows the equivalent implementation of __get: calls the proxied method with a closure that accesses the key on each item.

```php
$collection->{$this->method}(function ($value) use ($key) {
    return is_array($value) ? $value[$key] : $value->{$key};
});
```

--------------------------------

### takeWhile($value)

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-iteration.md

Returns items from the start while a condition holds true.

```APIDOC
## takeWhile($value)

### Description
Returns a new collection containing items from the beginning while the given value or callback condition is true. Implemented through `LazyCollection` for streaming.

### Method
takeWhile($value)

### Parameters
- **$value** (mixed|callable) - Required - A value to match, or a callback `callable(TValue, TKey): bool` that returns true to continue.

### Return Value
- **static** - A new collection with the taken items.

### Example
```php
$c = new Collection([1, 2, 3, 4, 5]);
$c->takeWhile(fn ($n) => $n < 3); // [1, 2]
```
```

--------------------------------

### Catching the Singularity Exceptions

Source: https://github.com/illuminate/collections/blob/master/_autodocs/errors.md

Example of catching both singularity exceptions in a try-catch block.

```APIDOC
## Catching the Singularity Exceptions

### Description
Both custom exceptions extend `RuntimeException`, so you can catch them individually or together.

### Example
```php
use Illuminate\Support\ItemNotFoundException;
use Illuminate\Support\MultipleItemsFoundException;

try {
    $item = collect($items)->sole('sku', 'AB-1');
} catch (MultipleItemsFoundException $e) {
    // $e->getMessage();   // "2 items were found."
    // $e->getCount();     // 2 — use to disambiguate
} catch (ItemNotFoundException) {
    // zero matches
}
```

### Note
Both extend `RuntimeException`, so `catch (\RuntimeException)` also works if you don't need the distinction.
```

--------------------------------

### pipeThrough($callbacks)

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Pipes the collection through an array of callbacks, reducing over them starting from the collection.

```APIDOC
## pipeThrough($callbacks)

### Description
Pipes the collection through an array of callbacks, reducing over them starting from the collection.

### Method
pipeThrough

### Parameters
- **$callbacks** (array) - Required - An array of callables to apply sequentially.

### Returns
The result after applying all callbacks.

### Example
```php
$result = collect([1, 2, 3])->pipeThrough([fn ($v) => $v * 2, fn ($v) => $v + 1]); // 13
```
```

--------------------------------

### takeUntil($value)

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-iteration.md

Returns items from the start until a given value or callback condition is met.

```APIDOC
## takeUntil($value)

### Description
Returns a new collection containing items from the beginning until the given value or until the callback returns true. Implemented through `LazyCollection` for streaming.

### Method
takeUntil($value)

### Parameters
- **$value** (mixed|callable) - Required - A value to stop at, or a callback `callable(TValue, TKey): bool` that returns true to stop.

### Return Value
- **static** - A new collection with the taken items.

### Example
```php
$c = new Collection([1, 2, 3, 4, 5]);
$c->takeUntil(4); // [1, 2, 3]
```
```

--------------------------------

### slice($offset, $length = null)

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Collection-iteration.md

Returns a slice of the collection starting at the given offset.

```APIDOC
## slice($offset, $length = null)

### Description
Returns a new collection containing a slice of the original collection starting at the given offset, with an optional length. Keys are preserved.

### Method
slice($offset, $length = null)

### Parameters
- **$offset** (int) - Required - The starting position.
- **$length** (int|null) - Optional - The number of items to include. If null, includes all items from the offset to the end.

### Return Value
- **static** - A new collection with the sliced items, keys preserved.

### Example
```php
$collection = new Collection([1, 2, 3, 4, 5]);
$slice = $collection->slice(1, 2); // [2, 3]
```
```

--------------------------------

### reduceWithKeys(callable $callback, $initial = null)

Source: https://github.com/illuminate/collections/blob/master/_autodocs/api-reference/Trait-EnumeratesValues.md

Identical to reduce, but always passes the key to the callback.

```APIDOC
## reduceWithKeys(callable $callback, $initial = null)

### Description
Identical to reduce, but always passes the key to the callback.

### Method
reduceWithKeys

### Parameters
- **$callback** (callable) - Required - The callback with signature ($carry, $value, $key).
- **$initial** (mixed) - Optional - The initial carry value.

### Returns
The reduced value.

### Example
```php
$c = new Collection(['a' => 1, 'b' => 2]);
$c->reduceWithKeys(fn ($carry, $value, $key) => $carry + $value, 0); // 3
```
```

--------------------------------

### Illuminate\Support\ItemNotFoundException

Source: https://github.com/illuminate/collections/blob/master/_autodocs/errors.md

Documentation for the custom exception class ItemNotFoundException, including its trigger conditions and usage example.

```APIDOC
## Class: Illuminate\Support\ItemNotFoundException

### Description
Exception thrown when a `sole()` or `firstOrFail()` operation finds zero matching items.

### Extends
`\RuntimeException`

### Message
None set by the class (default `''`).

### Public Members
None.

### Thrown By
- `Collection::sole()`
- `Collection::firstOrFail()`
- `LazyCollection::sole()`
- `LazyCollection::firstOrFail()`
- `Arr::sole()`

### Trigger Conditions
- `Collection::sole()` — zero items pass the (optional) filter.
- `Collection::firstOrFail()` — no item matches.
- `LazyCollection::sole()` — streamed `take(2)` yields nothing (delegates to `Collection::sole()` after materializing).
- `LazyCollection::firstOrFail()` — no item matches.
- `Arr::sole($array, ?callable $callback = null)` — zero items match.

### Example
```php
use Illuminate\Support\ItemNotFoundException;

try {
    $item = collect($items)->sole('sku', 'AB-1');
} catch (ItemNotFoundException) {
    // zero matches
}
```
```

--------------------------------

### take($limit)

Source: https://github.com/illuminate/collections/blob/master/_autodocs/types.md

Returns a new collection with the specified number of items from the beginning.

```APIDOC
## take($limit)

### Description
Returns a new collection with the specified number of items from the beginning of the collection.

### Method
`take`

### Signature
`take($limit): static`

### Parameters
- **$limit** (int) - Required - The number of items to take.

### Return Value
Returns a new collection instance with the specified number of items.
```
Tokens:
Raw