Ramsey Collection

https://github.com/ramsey/collection
Admin
Ramsey Collection is a PHP library for representing and manipulating collections, arrays, sets,...
Tokens:52,595
Snippets:391
Trust Score:10
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install ramsey/collection via Composer

Source: https://github.com/ramsey/collection/blob/main/README.md

Install the library as a dependency using Composer from the command line. This is the standard installation step.

```bash
composer require ramsey/collection
```

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

### Install dependencies with Composer

Source: https://github.com/ramsey/collection/blob/main/CONTRIBUTING.md

Run these commands after cloning the repository to install project dependencies. Requires PHP 8.1 or greater and Composer.

```bash
cd /path/to/repository
composer install
```

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

### Queue basic usage example

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/queue.md

Demonstrates basic queue operations: add, offer, peek, element, poll, and remove, with expected return values.

```php
use Ramsey\Collection\Queue;

$queue = new Queue('int');

$queue->add(1);      // true
$queue->offer(2);    // true
$queue->add(3);      // true

$queue->peek();      // 1 (head, not removed)
$queue->element();   // 1 (head, not removed)

$queue->poll();      // 1 (removed)
$queue->remove();    // 2 (removed)
$queue->poll();      // 3 (removed)
$queue->poll();      // null — queue empty
```

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

### Usage Example with Collection

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/sort.md

Shows how to use `Sort` with `Collection::sort()` to sort ascending or descending, and how to sort by a property. Cloning means the original collection is unchanged.

```php
use Ramsey\Collection\Collection;
use Ramsey\Collection\Sort;

$collection = new Collection('int', [3, 1, 2]);

$asc = $collection->sort();                       // Sort::Ascending by default
$asc->toArray();                                  // [1, 2, 3]

$desc = $collection->sort(null, Sort::Descending);
$desc->toArray();                                 // [3, 2, 1]

// Sorting by element property/method/array-key in a specific order:
$byNameDesc = $collection->sort('name', Sort::Descending);
```

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

### TypedMap usage example

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/typed-map.md

Shows how to create a TypedMap with string keys and Foo values, assign values using array syntax and put(), iterate, and initialize with data using integer keys.

```php
use Ramsey\Collection\Map\TypedMap;

$map = new TypedMap('string', Foo::class);

$map['x'] = new Foo();           // OK
$map->put('y', new Foo());       // OK

foreach ($map as $key => $value) {
    // $key is string; $value is Foo
}

// initialize directly with contents (note: numeric keys here)
$map = new TypedMap('int', Foo::class, [
    new Foo(), new Foo(),
]);
```

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

### Set

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/set.md

Documentation for the Set class, including its constructor, getType method, usage examples, and error handling.

```APIDOC
## Set

### Description
A concrete typed set that extends `AbstractSet`. It enforces a single type for all elements and skips duplicate values when adding items.

### Constructor

#### `__construct(string $setType, array $data = [])`

- **$setType** (string) - Required - The type or class name associated with this set.
- **$data** (array<array-key, T>) - Optional - Initial items to store in the set; duplicates are skipped.

### Methods

#### `getType(): string`

Returns the constructor `$setType` string.

### Usage Examples

```php
use Ramsey\Collection\Set;

$foo = new Foo();
$set = new Set(Foo::class);

$set->add($foo);    // true  — element does not exist
$set->add($foo);    // false — element already exists (strict ===)

$bar = new Foo();   // $bar !== $foo
$set->add($bar);    // true  — different object instance
$set->count();      // 2

// duplicate data passed to the constructor is dropped
$set = new Set('int', [1, 2, 2, 3, 2]);
$set->toArray();    // [0 => 1, 1 => 2, 2 => 3]
```

### Error Handling

```php
use Ramsey\Collection\Exception\InvalidArgumentException;
use Ramsey\Collection\Set;

$set = new Set('int', [1, 2, 3]);

try {
    $set->add('not-an-int');
} catch (InvalidArgumentException $e) {
    // 'Value must be of type int; value is not-an-int'
}

// offsetSet never throws for duplicates, but still type-checks:
$set[10] = 3;       // duplicate → silently ignored, set unchanged
$set[10] = 4;       // not a duplicate → stored (offset 10)

// standard collection ops work on sets too:
$other = new Set('int', [3, 4, 5]);
$unionLike = $set->merge($other);       // [1, 2, 3, 4, 5]
$common = $set->intersect($other);      // [3]
$missing = $set->diff($other);          // symmetric difference [1, 2, 4, 5]
```
```

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

### Set usage example with duplicate handling

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/set.md

Demonstrates creating a Set with a class type, adding objects, and observing duplicate behavior. Also shows that duplicate data passed to the constructor is dropped.

```php
use Ramsey\Collection\Set;

$foo = new Foo();
$set = new Set(Foo::class);

$set->add($foo);    // true  — element does not exist
$set->add($foo);    // false — element already exists (strict ===)

$bar = new Foo();   // $bar !== $foo
$set->add($bar);    // true  — different object instance
$set->count();      // 2

// duplicate data passed to the constructor is dropped
$set = new Set('int', [1, 2, 2, 3, 2]);
$set->toArray();    // [0 => 1, 1 => 2, 2 => 3]
```

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

### Queue error handling example

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/queue.md

Shows how offer() swallows type errors while add() throws InvalidArgumentException, and remove() throws NoSuchElementException when empty.

```php
use Ramsey\Collection\Exception\InvalidArgumentException;
use Ramsey\Collection\Exception\NoSuchElementException;
use Ramsey\Collection\Queue;

$queue = new Queue(Person::class, [new Person('Jane')]);

$queue->offer('not-a-person');   // false — type mismatch caught internally
$queue->count();                 // 1 — unchanged

try {
    $queue->add('not-a-person'); // throws
} catch (InvalidArgumentException $e) {
    // 'Value must be of type Ramsey\Collection\Test\Mock\Person; value is not-a-person'
}

$queue->poll();   // Person('Jane')
try {
    $queue->remove();            // throws — empty
} catch (NoSuchElementException $e) {
    // 'Can't return element from Queue. Queue is empty.'
}
```

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

### Using AbstractMap with a custom subclass

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/map.md

Shows how to create a concrete subclass of AbstractMap and use its methods. Demonstrates put, get, containsKey, containsValue, keys, putIfAbsent, replace, replaceIf, removeIf, remove, and toArray. Note that putIfAbsent returns the existing value and does not replace it, replaceIf returns false on strict mismatch, and removeIf returns true when removed.

```php
use Ramsey\Collection\Map\AbstractMap;

// AbstractMap is abstract; use a concrete subclass or your own:
class StringMap extends AbstractMap {}          // @extends AbstractMap<string, mixed>

$map = new StringMap(['foo' => 'bar']);

$map->put('baz', 'qux');        // null (no previous value)
$map->put('foo', 'updated');    // 'bar' (previous value)
$map->get('foo');               // 'updated'
$map->get('missing');           // null
$map->get('missing', 'fallback'); // 'fallback'

$map->containsKey('foo');       // true
$map->containsValue('qux');     // true
$map->keys();                   // ['foo', 'baz']

$map->putIfAbsent('baz', 'ignored');  // 'qux' — existing, not replaced
$map->replace('baz', 'new-val');      // 'qux' (previous)
$map->replaceIf('baz', 'other', 'x'); // false — strict mismatch
$map->removeIf('baz', 'new-val');     // true — removed
$map->remove('foo');                  // 'updated'
$map->toArray();                      // []
```

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

### Run all tests and coding standards checks

Source: https://github.com/ramsey/collection/blob/main/CONTRIBUTING.md

Executes the full test suite and coding standards checks. This must pass before a pull request is accepted; failure results in a complete build failure. Requires `composer install` to have been run first.

```bash
composer test
```

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

### Create and use NamedParameterMap

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/named-parameter-map.md

Creates a NamedParameterMap with a type map and initial data. Shows how to retrieve values, get the named parameters, and set values via put() or array assignment, with validation applied.

```php
use Ramsey\Collection\Map\NamedParameterMap;

$map = new NamedParameterMap(
    [
        'name' => 'string',
        'age'  => 'int',
        'friend',
    ],
    [
        'name' => 'Jamie',
        'age'  => 32,
    ],
);

$map->get('name');               // 'Jamie'
$map->getNamedParameters();      // ['name' => 'string', 'age' => 'int', 'friend' => 'mixed']

$map->put('friend', new Person('Jordan'));  // 'mixed' accepts anything
$map['age'] = 33;                // array-assignment also validated
```

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

### Ramsey\Collection\Collection

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Documentation for the Ramsey\Collection\Collection class methods including usage examples and error handling.

```APIDOC
## Collection Class Methods

### Description
Methods available on the `Ramsey\Collection\Collection` class for working with typed collections.

### Methods

#### getType()
- Returns the type of the collection.

#### first()
- Returns the first element. Throws `NoSuchElementException` when empty.

#### last()
- Returns the last element. Throws `NoSuchElementException` when empty.

#### column($propertyOrMethod)
- Returns an array of values from a property or method call on each element.

#### where($property, $value)
- Returns a new filtered collection. Original collection is untouched.

#### sort($property, $direction)
- Returns a new sorted collection. Original collection is untouched.

#### map($callback)
- Returns a new collection with the callback applied to each element.

#### reduce($callback, $initial)
- Reduces the collection to a single value.

#### diff($collection)
- Returns the symmetric difference between two collections.

#### intersect($collection)
- Returns the intersection of two collections.

#### merge($collection)
- Merges two collections.

#### add($value)
- Adds a value to the collection. Throws `InvalidArgumentException` if type mismatch.

### Usage Examples

```php
use Ramsey\Collection\Collection;

$persons = new Collection(Person::class, [
    new Person('Jane', 30),
    new Person('John', 25),
    new Person('Janice', 40),
]);

// getType
$persons->getType();   // Person::class

// first/last (throws NoSuchElementException when empty)
$persons->first();     // Person('Jane')
$persons->last();      // Person('Janice')

// column
$persons->column('name');          // ['Jane', 'John', 'Janice']
$persons->column('getAge()');      // method call
$persons->column('address.city');  // array key on array elements

// where returns a new filtered collection, original untouched
$janes = $persons->where('name', 'Jane');
$janes->count();       // 1
$persons->count();     // 3

// sort — new collection, original untouched
$sorted = $persons->sort('age', Sort::Descending);
$sorted->first()->name;            // 'Janice'

// filter/map/reduce chaining
$names = $persons->map(fn (Person $person): string => $person->name);
$names->getType();                 // 'mixed'

$totalAge = $persons->reduce(
    fn (int $carry, Person $person): int => $carry + $person->age,
    0,
);                                // 95

// set operations
$morePersons = new Collection(Person::class, [new Person('John'), new Person('Susan')]);
$diff = $persons->diff($morePersons);       // symmetric difference
$intersection = $persons->intersect($morePersons);
$merged = $persons->merge($morePersons);
```

### Error Handling

```php
use Ramsey\Collection\Collection;
use Ramsey\Collection\Exception\CollectionMismatchException;
use Ramsey\Collection\Exception\InvalidArgumentException;
use Ramsey\Collection\Exception\NoSuchElementException;

$ints = new Collection('int', [1, 2, 3]);

try {
    $ints->add('not-an-int');               // offsetSet() type check
} catch (InvalidArgumentException $e) {
    // 'Value must be of type int; value is not-an-int'
}

$other = new Collection('string', ['a']);   // different concrete type
try {
    $ints->diff($other);                    // different class AND different uniform type
} catch (CollectionMismatchException $e) {
    // 'Collection must be of type Ramsey\Collection\Collection'
}

$empty = new Collection(Person::class);
try {
    $empty->first();
} catch (NoSuchElementException $e) {
    // 'Can't determine first item. Collection is empty'
}
```
```

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

### Using AssociativeArrayMap with mixed values

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/map.md

Shows how to instantiate and use AssociativeArrayMap with mixed value types. Demonstrates iteration, keys, get, put, and remove. The put method returns the previous value, and remove returns the removed value.

```php
use Ramsey\Collection\Map\AssociativeArrayMap;

$map = new AssociativeArrayMap([
    'foo' => 1,
    'bar' => 'something',
    'baz' => false,
    'qux' => 23.3,
]);

foreach ($map as $key => $value) {
    // $key is string, $value is mixed
}

$map->keys();                    // list<string>
$map->get('foo');                // 1
$map->put('foo', 'hello');       // 1 (previous value)
$map->remove('baz');             // false
```

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

### Collection usage examples

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Shows common Collection operations: getType, first/last (throws NoSuchElementException when empty), column (supports property, method call, and array key), where, sort (Sort::Descending), map/reduce chaining, and set operations diff/intersect/merge. Methods like where and sort return new collections, leaving the original untouched.

```php
use Ramsey\Collection\Collection;

$persons = new Collection(Person::class, [
    new Person('Jane', 30),
    new Person('John', 25),
    new Person('Janice', 40),
]);

// getType
$persons->getType();   // Person::class

// first/last (throws NoSuchElementException when empty)
$persons->first();     // Person('Jane')
$persons->last();      // Person('Janice')

// column
$persons->column('name');          // ['Jane', 'John', 'Janice']
$persons->column('getAge()');      // method call
$persons->column('address.city');  // array key on array elements

// where returns a new filtered collection, original untouched
$janes = $persons->where('name', 'Jane');
$janes->count();       // 1
$persons->count();     // 3

// sort — new collection, original untouched
$sorted = $persons->sort('age', Sort::Descending);
$sorted->first()->name;            // 'Janice'

// filter/map/reduce chaining
$names = $persons->map(fn (Person $person): string => $person->name);
$names->getType();                 // 'mixed'

$totalAge = $persons->reduce(
    fn (int $carry, Person $person): int => $carry + $person->age,
    0,
);                                // 95

// set operations
$morePersons = new Collection(Person::class, [new Person('John'), new Person('Susan')]);
$diff = $persons->diff($morePersons);       // symmetric difference
$intersection = $persons->intersect($morePersons);
$merged = $persons->merge($morePersons);
```

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

### TypedMap error handling example

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/typed-map.md

Demonstrates that both key and value types are enforced. Assigning an integer key or a non-Foo value throws InvalidArgumentException with the specified messages.

```php
use Ramsey\Collection\Exception\InvalidArgumentException;
use Ramsey\Collection\Map\TypedMap;

$map = new TypedMap('string', Foo::class);

try {
    $map[10] = new Foo();        // key must be string → throws
} catch (InvalidArgumentException $e) {
    // 'Key must be of type string; key is 10'
}

try {
    $map['bar'] = 'bar';         // value must be Foo → throws
} catch (InvalidArgumentException $e) {
    // 'Value must be of type Foo\Foo; value is bar'
}
```

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

### Typed Collection usage

Source: https://github.com/ramsey/collection/wiki/Examples

Uses the custom FooCollection class similarly to the generic example, adding objects and iterating. This is the usage pattern for a typed collection.

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

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

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

### Using Collection with a class type

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Example of using the Collection class with a class type. It shows adding items, iterating, and catching an InvalidArgumentException when adding an invalid value.

```php
use Ramsey\Collection\Collection;

/** @var class-string<Foo> $type */
$collection = new Collection(Foo::class, [new Foo(), new Foo()]);
$collection->add(new Foo());

foreach ($collection as $foo) {
    // $foo is Foo
}

// TypeError-independent rejection:
try {
    $collection->add('bar');
} catch (\Ramsey\Collection\Exception\InvalidArgumentException $e) {
    // 'Value must be of type Foo\Foo; value is bar'
}
```

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

### Collection error handling examples

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Demonstrates error handling for Collection operations: InvalidArgumentException on type mismatch in add(), CollectionMismatchException when diffing collections of different types, and NoSuchElementException when calling first() on an empty collection. Each catch block shows the expected exception message.

```php
use Ramsey\Collection\Collection;
use Ramsey\Collection\Exception\CollectionMismatchException;
use Ramsey\Collection\Exception\InvalidArgumentException;
use Ramsey\Collection\Exception\NoSuchElementException;

$ints = new Collection('int', [1, 2, 3]);

try {
    $ints->add('not-an-int');               // offsetSet() type check
} catch (InvalidArgumentException $e) {
    // 'Value must be of type int; value is not-an-int'
}

$other = new Collection('string', ['a']);   // different concrete type
try {
    $ints->diff($other);                    // different class AND different uniform type
} catch (CollectionMismatchException $e) {
    // 'Collection must be of type Ramsey\Collection\Collection'
}

$empty = new Collection(Person::class);
try {
    $empty->first();
} catch (NoSuchElementException $e) {
    // 'Can't determine first item. Collection is empty'
}
```

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

### Catch specific collection exceptions with multiple catch blocks

Source: https://github.com/ramsey/collection/blob/main/_autodocs/errors.md

Use this pattern to handle different types of collection errors separately. The example catches CollectionMismatchException for type mismatches and InvalidArgumentException for wrong element, key, or value types. This is the recommended approach since there are no error codes.

```php
try {
    // ... collection operation ...
} catch (\Ramsey\Collection\Exception\CollectionMismatchException $e) {
    // type mismatch
} catch (\Ramsey\Collection\Exception\InvalidArgumentException $e) {
    // wrong element/key/value type
}
```

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

### Example: InvalidArgumentException message with toolValueToString

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/traits.md

Example usage of toolValueToString in an exception message. Adding a stdClass to an int collection throws InvalidArgumentException; the message shows the value as '(stdClass Object)'.

```php
use Ramsey\Collection\Collection;

$collection = new Collection('int');

try {
    $collection->add(new stdClass());       // wrong type
} catch (\Ramsey\Collection\Exception\InvalidArgumentException $e) {
    echo $e->getMessage();
    // 'Value must be of type int; value is (stdClass Object)'
}
```

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

### List available dev commands

Source: https://github.com/ramsey/collection/blob/main/CONTRIBUTING.md

Displays all commands available for contributing to the project.

```bash
composer list dev
```

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

### Using ValueExtractorTrait with column(), where(), and sort()

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/traits.md

Shows how to use the ValueExtractorTrait methods (column, where, sort) on collections. Demonstrates array-key extraction, method calls, magic properties, and passing null to sort. Requires a User class with a constructor accepting name and an array of attributes.

```php
use Ramsey\Collection\Collection;

$users = new Collection(User::class, [
    new User('alice', ['city' => 'Paris']),
    new User('bob',   ['city' => 'Rome']),
]);

// array-key extraction on array elements
$orders = new Collection('array', [
    ['id' => 1, 'total' => 9.99],
    ['id' => 2, 'total' => 19.99],
]);
$orders->column('total');      // [9.99, 19.99]

// method calls and magic properties
$users->column('name');                    // ['alice', 'bob']
$users->where('getCity', 'Paris');         // collection of User objects

// null propertyOrMethod passes elements through
$users->sort(null, Sort::Descending);
```

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

### Queue offer method

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/queue.md

Attempts to add an element, returning false on type mismatch instead of throwing. Returns true on success.

```php
public function offer(mixed $element): bool
```

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

### Basic GenericArray construction and array access

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/array.md

Demonstrates creating a GenericArray with an initial array, using array access to set and append values, counting, converting to array, iterating, and clearing. Shows that appending with a null offset uses the next integer key and that toArray() returns a zero-indexed array.

```php
use Ramsey\Collection\GenericArray;

$array = new GenericArray(['foo' => 'bar', 42 => 'answer']);
$array->isEmpty();      // false
$array['baz'] = 'qux';  // offsetSet()
$array[] = 'append';    // null offset appends at next integer key
$array->count();        // 4
$array->toArray();      // ['foo' => 'bar', 42 => 'answer', 'baz' => 'qux', 0 => 'append']

foreach ($array as $key => $value) {
    // iterates all items
}

$array->clear();
$array->isEmpty();      // true
```

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

### Queue bulk enqueue and FIFO guarantee

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/queue.md

Shows constructor enqueuing initial data in order and polling in FIFO order.

```php
use Ramsey\Collection\Queue;

$queue = new Queue('int', [10, 20, 30]);   // constructor enqueues in order

$order = [];
while (!$queue->isEmpty()) {
    $order[] = $queue->poll();             // [10, 20, 30] — FIFO
}
```

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

### peekFirst() method signature

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Method signature for peekFirst(). Delegates to peek() to return the head without removal, or null when empty.

```php
public function peekFirst(): mixed
```

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

### offerFirst()

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Inserts an element at the head of the deque. Returns `true` or `false` instead of throwing an exception on insertion failure.

```APIDOC
## offerFirst()

### Description
Inserts an element at the head of the deque. Returns `true` or `false` instead of throwing an exception on insertion failure.

### Method
offerFirst

### Signature
`public function offerFirst(mixed $element): bool`

### Parameters
- **$element** (mixed) - Required - The element to insert at the head.

### Return Value
- **bool** - Returns `true` if the element was inserted, `false` otherwise.
```

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

### offerFirst()

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Attempts to add an element to the front of the deque. Returns false on type mismatch instead of throwing.

```APIDOC
## offerFirst()

### Description
Attempts to add an element to the front of the deque. Returns `false` on type mismatch instead of throwing an exception.

### Method
offerFirst

### Signature
php
public function offerFirst(mixed $element): bool


### Parameters
- **$element** (mixed) - Required - The element to add to the front.

### Return Value
- **bool** - Returns `true` on success, `false` on type mismatch.

### Source
`src/DoubleEndedQueue.php:71`
```

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

### Queue constructor

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/queue.md

Constructor that takes a queue type string and optional initial data array.

```php
/**
 * @param string $queueType The type or class name associated with this queue.
 * @param array<array-key, T> $data The initial items to store in the queue.
 */
public function __construct(private readonly string $queueType, array $data = [])
{
    parent::__construct($data);
}
```

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

### Queue::offer

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/queue.md

Attempts to add an element to the queue, returning false instead of throwing on type mismatch. Returns true on success.

```APIDOC
## Queue::offer

### Description
Attempts to add an element to the queue, returning false instead of throwing on type mismatch. Returns true on success.

### Method
`offer`

### Signature
```php
public function offer(mixed $element): bool
```

### Parameters
- **$element** (mixed) - Required - The element to add.

### Returns
- **bool** - `true` on success, `false` on type mismatch.

### Usage Example
```php
$queue->offer('not-a-person'); // false
```
```

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

### firstElement() method signature

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Method signature for firstElement(). Delegates to element() to return the head without removal, throwing when empty.

```php
public function firstElement(): mixed
```

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

### Instantiating from an array of objects

Source: https://github.com/ramsey/collection/wiki/Examples

Creates a typed collection from an array of objects by passing the array to the constructor. This is an alternative to using add() repeatedly.

```php
$foos = [
  new \My\Foo(),
  new \My\Foo()
];

$fooCollection = new \My\Foo\FooCollection($foos);
```

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

### offerLast() method signature

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Method signature for offerLast(). Delegates to offer() and never throws for type mismatches.

```php
public function offerLast(mixed $element): bool
```

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

### Inheritance graph of collection classes

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/overview.md

Shows the class hierarchy from ArrayInterface down to concrete classes, including interfaces and abstract classes. Highlights key behaviors such as duplicate rejection in AbstractSet, FIFO semantics in Queue, and null offset rejection in AbstractMap.

```plaintext
ArrayInterface (extends ArrayAccess, Countable, IteratorAggregate)
 └── AbstractArray                       (implements ArrayInterface)
      ├── GenericArray
      ├── AbstractCollection             (implements CollectionInterface)
      │    ├── AbstractSet               (no duplicates; add() == false on duplicate)
      │    │    └── Set
      │    └── Collection
      ├── Queue                          (implements QueueInterface, FIFO semantics)
      │    └── DoubleEndedQueue          (implements DoubleEndedQueueInterface)
      └── AbstractMap                    (implements MapInterface)
           ├── AssociativeArrayMap
           ├── AbstractTypedMap          (implements TypedMapInterface)
           │    └── TypedMap
           └── NamedParameterMap
```

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

### Run static analysis with PHPStan

Source: https://github.com/ramsey/collection/blob/main/CONTRIBUTING.md

Runs static analysis across the whole codebase. CaptainHook will also run static analysis checks before pushing.

```bash
# Static analysis
composer dev:analyze
```

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

### Queue::__construct

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/queue.md

Initializes a new Queue instance with an optional initial set of items. The queue type is validated against the provided type or class name.

```APIDOC
## Queue::__construct

### Description
Initializes a new Queue instance with an optional initial set of items. The queue type is validated against the provided type or class name.

### Method
`__construct`

### Signature
```php
public function __construct(private readonly string $queueType, array $data = [])
```

### Parameters
- **$queueType** (string) - Required - Type or class name for the queue's elements (`TypeTrait::checkType()` vocabulary).
- **$data** (array<array-key, T>) - Optional - Initial items; validated through `offsetSet()` during construction. Default: `[]`.

### Usage Example
```php
$queue = new Queue('int', [10, 20, 30]);
```
```

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

### Queue peek method

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/queue.md

Returns the head element without removal, or null if the queue is empty.

```php
/**
 * @return T | null
 */
public function peek(): mixed
```

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

### first()

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Returns the first element of the collection. Throws an exception if the collection is empty.

```APIDOC
## first()

### Description
Returns the first element of the collection. Throws an exception if the collection is empty.

### Method
first

### Signature
```php
public function first(): mixed
```

### Return Value
- **mixed** - The first element.

### Exceptions
- **NoSuchElementException** - If the collection is empty.

```

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

### Constructor

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Initializes a new DoubleEndedQueue instance with a specified type and optional initial data.

```APIDOC
## Constructor

### Description
Initializes a new DoubleEndedQueue instance with a specified type and optional initial data.

### Method
__construct

### Signature
php
public function __construct(private readonly string $queueType, array $data = [])


### Parameters
- **$queueType** (string) - Required - Type or class name for the deque's elements.
- **$data** (array<array-key, T>) - Optional - Initial items; validated through `offsetSet()` during construction. Default: `[]`.

### Source
`src/DoubleEndedQueue.php:41`
```

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

### map() method signature

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Applies a callback to each item and returns a new collection. The result collection has runtime type 'mixed' regardless of the callback return type.

```php
/**
 * @param callable(T): TCallbackReturn $callback A callable to apply to each
 *     item of the collection.
 *
 * @return CollectionInterface<TCallbackReturn>
 *
 * @template TCallbackReturn
 */
public function map(callable $callback): CollectionInterface
```

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

### first() method signature

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Returns the first element of the collection. Throws NoSuchElementException if the collection is empty.

```php
/**
 * @return T
 *
 * @throws NoSuchElementException if this collection is empty.
 */
public function first(): mixed
```

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

### addFirst()

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Inserts an element at the head of the deque. Throws a RuntimeException (or a more specific subclass) if the insertion is refused.

```APIDOC
## addFirst()

### Description
Inserts an element at the head of the deque. Throws a RuntimeException (or a more specific subclass) if the insertion is refused.

### Method
addFirst

### Signature
`public function addFirst(mixed $element): bool`

### Parameters
- **$element** (mixed) - Required - The element to insert at the head.

### Return Value
- **bool** - Returns `true` on success; throws an exception on failure.

### Exceptions
- **\RuntimeException** - Thrown when the insertion is refused.
```

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

### Set class definition with constructor and getType()

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/set.md

Defines the Set class with a typed constructor and getType() method. The constructor accepts a type string and optional initial data, and getType() returns the set type.

```php
class Set extends AbstractSet
{
    /**
     * Constructs a set object of the specified type, optionally with the
     * specified data.
     *
     * @param string $setType The type or class name associated with this set.
     * @param array<array-key, T> $data The initial items to store in the set.
     */
    public function __construct(private readonly string $setType, array $data = [])
    {
        parent::__construct($data);
    }

    public function getType(): string
    {
        return $this->setType;
    }
}
```

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

### CollectionInterface

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Documentation for the CollectionInterface methods, including signatures, descriptions, and contract details.

```APIDOC
## CollectionInterface

### Description
Interface for a collection of values. It defines the contract for adding, removing, and querying elements, as well as operations that return new collections.

### Methods

#### add

```php
public function add(mixed $element): bool
```

Ensures the collection contains `$element`. Returns `true` if the collection changed. Throws `InvalidArgumentException` if the collection refuses an element for any reason other than duplicate-ness; duplicate rejection must return `false`.

#### contains

```php
public function contains(mixed $element, bool $strict = true): bool
```

Whether the element is present.

#### getType

```php
public function getType(): string
```

The type associated with this collection.

#### remove

```php
public function remove(mixed $element): bool
```

Removes a single instance. Returns `true` if an element was removed.

#### column

```php
public function column(string $propertyOrMethod): array
```

Returns values from the given property, method, or array key, as `list<mixed>`. Throws `InvalidPropertyOrMethod` or `UnsupportedOperationException`.

#### first

```php
public function first(): mixed
```

First item (`T`). Throws `NoSuchElementException` when empty.

#### last

```php
public function last(): mixed
```

Last item (`T`). Throws `NoSuchElementException` when empty.

#### sort

```php
public function sort(?string $propertyOrMethod = null, Sort $order = Sort::Ascending): self
```

Sorted copy of the collection. If `$propertyOrMethod` is `null`, elements are compared as themselves. Always leaves the original collection untouched. Throws `InvalidPropertyOrMethod` or `UnsupportedOperationException`.

#### filter

```php
public function filter(callable $callback): self
```

Copy filtered by `callable(T): bool`. Returns a new collection and never mutates the original.

#### where

```php
public function where(?string $propertyOrMethod, mixed $value): self
```

Copy of items whose extracted value equals `$value`. If `$propertyOrMethod` is `null`, the element itself is compared to `$value`. Returns a new collection and never mutates the original. Throws `InvalidPropertyOrMethod` or `UnsupportedOperationException`.

#### map

```php
public function map(callable $callback): self
```

Copy mapped via `callable(T): TCallbackReturn`. Returns a new collection and never mutates the original.

#### reduce

```php
public function reduce(callable $callback, mixed $initial): mixed
```

Reduces to a single `TCarry` value.

#### diff

```php
public function diff(CollectionInterface $other): self
```

New collection with divergent items (in either direction). Throws `CollectionMismatchException` on type-mismatched operands. Returns a new collection and never mutates the original.

#### intersect

```php
public function intersect(CollectionInterface $other): self
```

New collection with intersecting items. Throws `CollectionMismatchException` on type-mismatched operands. Returns a new collection and never mutates the original.

#### merge

```php
public function merge(CollectionInterface ...$collections): self
```

New collection merging the given collections. Returns a new collection and never mutates the original.
```

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

### offerLast()

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Inserts an element at the tail of the deque. Returns `true` or `false` instead of throwing an exception on insertion failure.

```APIDOC
## offerLast()

### Description
Inserts an element at the tail of the deque. Returns `true` or `false` instead of throwing an exception on insertion failure.

### Method
offerLast

### Signature
`public function offerLast(mixed $element): bool`

### Parameters
- **$element** (mixed) - Required - The element to insert at the tail.

### Return Value
- **bool** - Returns `true` if the element was inserted, `false` otherwise.
```

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

### offsetGet() method

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/array.md

Returns the value at the given offset, or null if it does not exist.

```php
/**
 * @param array-key $offset The offset for which a value should be returned.
 *
 * @return T the value stored at the offset, or null if the offset
 *     does not exist.
 */
public function offsetGet(mixed $offset): mixed
```

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

### Queue add method

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/queue.md

Enqueues an element at the tail. Returns true on success, throws InvalidArgumentException on type mismatch.

```php
/**
 * @throws InvalidArgumentException if $value is of the wrong type.
 */
public function add(mixed $element): bool
```

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

### offerFirst() method signature

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Method signature for offerFirst(). Returns false on type mismatch instead of throwing, by catching InvalidArgumentException from addFirst().

```php
public function offerFirst(mixed $element): bool
```

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

### reduce() method signature

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Reduces the collection to a single value using a callback and an initial value. Follows array_reduce() semantics.

```php
/**
 * @param callable(TCarry, T): TCarry $callback A callable to apply to each
 *     item of the collection to reduce it to a single value.
 * @param TCarry $initial This is the initial value provided to the callback.
 *
 * @return TCarry
 *
 * @template TCarry
 */
public function reduce(callable $callback, mixed $initial): mixed
```

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

### add()

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Adds an element to the collection. Validates the element type and returns true on success.

```APIDOC
## add()

### Description
Adds an element to the collection. The element is appended via offsetSet(), which performs type validation. Returns true on success.

### Method
add

### Signature
```php
public function add(mixed $element): bool
```

### Parameters
- **$element** (mixed) - Required - Element to add. Must be of type `getType()`.

### Return Value
- **bool** - Always `true` when accepted.

### Exceptions
- **InvalidArgumentException** - If `$element` is not of the type returned by `getType()`.

```

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

### Collection::__construct

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Constructor for the Collection class. Initializes a typed collection with an optional initial data array.

```APIDOC
## Collection::__construct

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

### Method
Constructor

### Signature
`public function __construct(private readonly string $collectionType, array $data = [])`

### Parameters
- `$collectionType` (string) - Required - The type or class name associated with this collection. Built-in names (`int`, `integer`, `bool`, `boolean`, `float`, `double`, `string`, `array`, `callable`, `null`, `numeric`, `object`, `resource`, `scalar`, `mixed`) or a class name (checked via `instanceof`).
- `$data` (array<array-key, T>) - Optional - Default: `[]` - The initial items to store in the collection. Validated through `offsetSet()` during construction.

### Example
```php
use Ramsey\Collection\Collection;

/** @var class-string<Foo> $type */
$collection = new Collection(Foo::class, [new Foo(), new Foo()]);
$collection->add(new Foo());

foreach ($collection as $foo) {
    // $foo is Foo
}
```
```

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

### offsetSet() method

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/array.md

Sets a value at the given offset, or appends if offset is null.

```php
/**
 * @param array-key | null $offset The offset to set. If `null`, the value
 *     may be set at a numerically-indexed offset.
 * @param T $value The value to set at the given offset.
 */
public function offsetSet(mixed $offset, mixed $value): void
```

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

### NamedParameterMap::__construct

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/named-parameter-map.md

Constructs a new NamedParameterMap with a set of named parameters and optional initial data. The named parameters define which keys are allowed and their types.

```APIDOC
## NamedParameterMap::__construct

### Description
Constructs a new NamedParameterMap with a set of named parameters and optional initial data. The named parameters define which keys are allowed and their types.

### Method
Constructor

### Signature
```php
public function __construct(array $namedParameters, array $data = [])
```

### Parameters
- **$namedParameters** (array<array-key, string>) - Required - Parameter names and their types. Entry shapes: `'key' => 'type'` maps `key` to `type`; a numeric index with a string value (e.g. `0 => 'name'`) declares `name` as type `'mixed'`.
- **$data** (array<string, mixed>) - Optional - Initial values; validated per-key through `offsetSet()` during construction. Default: `[]`.

### Behavior
Normalizes the named parameters and stores them in a private readonly array. Initial data is set via the parent constructor, which calls `offsetSet()` for each key, enforcing the configured types.
```

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

### Catch any ramsey/collection error using the CollectionException marker interface

Source: https://github.com/ramsey/collection/blob/main/_autodocs/errors.md

Use this catch-all pattern to handle any exception thrown by ramsey/collection. The CollectionException marker interface is implemented by all library exceptions, so catching it catches all of them. This is useful when you want a single handler for any collection-related error.

```php
try {
    // ...
} catch (\Ramsey\Collection\Exception\CollectionException $e) {
    // any ramsey/collection error
}
```

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

### DoubleEndedQueue as a stack (LIFO)

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Using DoubleEndedQueue as a LIFO stack. addFirst pushes, peekFirst inspects the top, and removeFirst pops elements.

```php
use Ramsey\Collection\DoubleEndedQueue;

$stack = new DoubleEndedQueue('string');
$stack->addFirst('a');    // push
$stack->addFirst('b');    // push
$stack->peekFirst();      // 'b'
$stack->removeFirst();    // pop → 'b'
$stack->removeFirst();    // pop → 'a'
```

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

### Catching extraction failures with UnsupportedOperationException and InvalidPropertyOrMethod

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/traits.md

Shows how to catch extraction failures when using column() on collections. Demonstrates UnsupportedOperationException for non-object/array elements and InvalidPropertyOrMethod for missing properties or methods. Includes the exact exception messages.

```php
use Ramsey\Collection\Collection;
use Ramsey\Collection\Exception\InvalidPropertyOrMethod;
use Ramsey\Collection\Exception\UnsupportedOperationException;

$scalars = new Collection('int', [1, 2, 3]);

try {
    $scalars->column('anything');          // ints are not objects/arrays
} catch (UnsupportedOperationException $e) {
    // 'The collection type "int" does not support the $propertyOrMethod parameter'
}

try {
    $users = new Collection(User::class, [new User('alice')]);
    $users->column('nonexistentField');    // no such property/method
} catch (InvalidPropertyOrMethod $e) {
    // 'Method or property "nonexistentField" not defined in ...User'
}
```

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

### sort() method signature

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/collection.md

Sorts the collection by a property or method, or directly. Returns a new sorted collection.

```php
/**
 * @return CollectionInterface<T>
 *
 * @throws InvalidPropertyOrMethod if the $propertyOrMethod does not exist
 *     on the elements in this collection.
 * @throws UnsupportedOperationException if unable to call sort() on this
 *     collection.
 */
public function sort(?string $propertyOrMethod = null, Sort $order = Sort::Ascending): CollectionInterface
```

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

### peekFirst()

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/deque.md

Returns (without removing) the element at the head of the deque, or returns `null` if the deque is empty.

```APIDOC
## peekFirst()

### Description
Returns (without removing) the element at the head of the deque, or returns `null` if the deque is empty.

### Method
peekFirst

### Signature
`public function peekFirst(): mixed`

### Return Value
- **mixed** - The element at the head, or `null` if the deque is empty.
```

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

### isEmpty() method

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/array.md

Checks if the array is empty.

```php
public function isEmpty(): bool
```

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

### __serialize() method

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/array.md

Returns the internal data array for PHP serialization.

```php
/**
 * @return array<array-key, T>
 */
public function __serialize(): array
```

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

### count() method

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/array.md

Returns the number of items in the array.

```php
public function count(): int
```

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

### toArray() method

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/array.md

Returns the internal data as an array.

```php
public function toArray(): array
```

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

### Queue element method

Source: https://github.com/ramsey/collection/blob/main/_autodocs/api-reference/queue.md

Returns the head element without removing it, throwing NoSuchElementException if the queue is empty.

```php
/**
 * @return T
 *
 * @throws NoSuchElementException if this queue is empty.
 */
public function element(): mixed
```
Tokens:
Raw