Functional PHP

https://github.com/lstrojny/functional-php
Admin
Functional PHP provides a set of functional programming primitives for PHP, inspired by Scala, Dojo,...
Tokens:43,303
Snippets:330
Trust Score:9.8
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install functional-php using Composer

Source: https://github.com/lstrojny/functional-php/blob/main/README.md

To install the library, run the composer require command in your project root. This command fetches and installs the latest version of functional-php.

```bash
composer require lstrojny/functional-php
```

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

### Installation

Source: https://context7.com/lstrojny/functional-php/llms.txt

Instructions on how to install the Functional PHP library using Composer.

```bash
composer require lstrojny/functional-php
```

```php
// Preferred import style (PHP 5.6+)
use function Functional\map;
use function Functional\filter;

// Or import the whole namespace as an alias
use Functional as F;
$result = F\map($collection, $callback);
```

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

### Selecting and Rejecting elements with select() and reject()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Use `select()` to get elements that satisfy a condition and `reject()` to get elements that do not. Array keys are preserved. If no callback is provided, `id()` is used.

```php
use function Functional\select;
use function Functional\reject;

$fn = fn ($user, $key, $collection) => $user->isActive();
$activeUsers = select($users, $fn);
$inactiveUsers = reject($users, $fn);
```

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

### product()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Calculates the product of all numeric elements, starting with `$initial`.

```APIDOC
## product()

### Description
Calculates the product of all numeric elements in a collection.

### Parameters
#### Path Parameters
- **collection** (array|Traversable) - Required - The input array or traversable collection.
- **initial** (integer|float) - Optional - The initial value to start the product calculation. Defaults to 1.

### Response
#### Success Response (integer|float)
- The calculated product of the elements.
```

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

### ratio()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Calculates the ratio of all numeric elements, starting with `$initial`.

```APIDOC
## ratio()

### Description
Calculates the ratio of all numeric elements in a collection.

### Parameters
#### Path Parameters
- **collection** (array|Traversable) - Required - The input array or traversable collection.
- **initial** (integer|float) - Optional - The initial value to start the ratio calculation. Defaults to 1.

### Response
#### Success Response (integer|float)
- The calculated ratio of the elements.
```

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

### Run tests using Composer

Source: https://github.com/lstrojny/functional-php/blob/main/README.md

After installing dependencies, you can run the project's tests using the composer run tests command. This is part of the contribution workflow.

```bash
composer run tests
```

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

### difference()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Calculates the difference of all elements, starting with `$initial`.

```APIDOC
## difference()

### Description
Calculates the difference of all elements in a collection.

### Parameters
#### Path Parameters
- **collection** (array|Traversable) - Required - The input array or traversable collection.
- **initial** (integer|float) - Optional - The initial value to start the difference calculation. Defaults to 0.

### Response
#### Success Response (integer|float)
- The calculated difference of the elements.
```

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

### sum()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Calculates the sum of all numeric elements, starting with `$initial`.

```APIDOC
## sum()

### Description
Calculates the sum of all numeric elements in a collection.

### Parameters
#### Path Parameters
- **collection** (array|Traversable) - Required - The input array or traversable collection.
- **initial** (integer|float) - Optional - The initial value to start the sum calculation. Defaults to 0.

### Response
#### Success Response (integer|float)
- The calculated sum of the elements.
```

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

### Partition collection by predicates using `partition()`

Source: https://context7.com/lstrojny/functional-php/llms.txt

Distributes each element into the bucket of the first matching predicate; elements matching none go into a final catch-all bucket. Ensure the `Functionalunctions` namespace is imported.

```php
use function Functional\partition;

$numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

[$divisibleBy3, $divisibleBy2, $rest] = partition(
    $numbers,
    fn ($n) => $n % 3 === 0,
    fn ($n) => $n % 2 === 0
);
// $divisibleBy3 => [3, 6, 9]
// $divisibleBy2 => [2, 4, 8, 10]  (already matched 6 went to first bucket)
// $rest         => [1, 5, 7]
```

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

### Reduce collection from left or right

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Applies a callback to each element to reduce the collection to a single scalar value. `reduce_left` starts from the first element, while `reduce_right` starts from the last.

```php
use function Functional\reduce_left;
use function Functional\reduce_right;

$str = reduce_left([2, 3], fn ($value, $index, $collection, $reduction) => $reduction . $value, 2); // '223'
$str = reduce_right([2, 3], fn ($value, $index, $collection, $reduction) => $reduction . $value, 2); // '232'
```

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

### Partial application with placeholders using partial_any()

Source: https://context7.com/lstrojny/functional-php/llms.txt

Use `partial_any()` with the `…` constant to create functions where specific argument positions are left open. This allows for more flexible partial application.

```php
use function Functional\partial_any;
use function Functional\select;
use const Functional\…;

$elements = ['john', 'joe', 'joanna', 'patrick'];

// Fill second argument of substr_count, leave first as placeholder
$containsJo = partial_any('substr_count', …, 'jo');
$matches = select($elements, $containsJo);
// => ['john', 'joe', 'joanna']

// Multiple placeholders
$format = fn ($prefix, $value, $suffix) => $prefix . $value . $suffix;
$brackets = partial_any($format, '[', …, ']');
$brackets('hello'); // => '[hello]'
```

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

### partition()

Source: https://context7.com/lstrojny/functional-php/llms.txt

Distributes each element into the bucket of the first matching predicate; elements matching none go into a final catch-all bucket.

```APIDOC
## partition()

### Description
Distributes each element into the bucket of the first matching predicate; elements matching none go into a final catch-all bucket.

### Method
`partition(iterable $collection, callable ...$predicates): array`

### Parameters
#### Path Parameters
- **collection** (iterable) - The collection to partition.
- **predicates** (callable) - One or more callback functions to test elements.

### Request Example
```php
use function Functional\partition;

$numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

[$divisibleBy3, $divisibleBy2, $rest] = partition(
    $numbers,
    fn ($n) => $n % 3 === 0,
    fn ($n) => $n % 2 === 0
);
// $divisibleBy3 => [3, 6, 9]
// $divisibleBy2 => [2, 4, 8, 10]  (already matched 6 went to first bucket)
// $rest         => [1, 5, 7]
```
```

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

### Partial Any Application with partial_any()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Illustrates using `Functional\partial_any` with a placeholder to create a partially applied function for `select`.

```php
use function Functional\select;
use function Functional\partial_any;
use const Functional\…;

$elements = [
    'john',
    'joe',
    'joanna',
    'patrick',
];

// Original callback for select
// $selected = select($elements, fn ($name) => substr_count($name, 'jo'));

// Using partial_any for a more concise callback
$selected = select($elements, partial_any('substr_count', …, 'jo'));
```

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

### partition()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Splits a collection into two or more by callback(s).

```APIDOC
## partition()

### Description
Splits a collection into two or more partitions based on the results of provided callbacks. Elements are placed in the first partition for which the callback returns a truthy value. If no callback returns a truthy value, the element is placed in the final partition.

### Parameters
#### Path Parameters
- **collection** (array|Traversable) - Required - The collection to partition.
- **callback** (callable) - Required - One or more callable functions to determine the partition for each element.

### Response
#### Success Response (array)
- An array where each element is a partition (an array) of the original collection.

### Request Example
```php
use function Functional\partition;

list($admins, $guests, $users) = partition(
    $collection,
    fn ($user) => $user->isAdmin(),
    fn ($user) => $user->isGuest()
);
```
```

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

### Poll for Truthy Value with Linear Back-off

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Polls a callback function until it returns a truthy value or a specified timeout is reached. Uses a linear back-off sequence for delays, starting at a given interval. Suitable for checking conditions that resolve over time.

```php
use function Functional\poll;
use function Functional\sequence_linear;

// Poll if a file exists for 10,000 microseconds with a linearly growing back-off starting at 100 milliseconds
poll(
    fn () => file_exists('/tmp/lockfile'),
    10000,
    sequence_linear(100, 1)
);
```

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

### matching()

Source: https://context7.com/lstrojny/functional-php/llms.txt

Returns a function that tests each `[$predicate, $handler]` pair in order and calls the handler of the first matching predicate.

```APIDOC
## matching()

### Description
Returns a function that tests each `[$predicate, $handler]` pair in order and calls the handler of the first matching predicate.

### Parameters
- **pairs** (array) - An array of `[$predicate, $handler]` pairs.
  - **predicate** (callable) - A function that returns a boolean.
  - **handler** (callable) - A function to call if the predicate returns true.

### Request Example
```php
use function Functional\matching;
use function Functional\greater_than_or_equal;

$classify = matching([
    [greater_than_or_equal(90), fn ($s) => 'A'],
    [greater_than_or_equal(80), fn ($s) => 'B'],
    [greater_than_or_equal(70), fn ($s) => 'C'],
    [greater_than_or_equal(60), fn ($s) => 'D'],
    [fn () => true,             fn ($s) => 'F'],
]);

$classify(95); // => 'A'
$classify(73); // => 'C'
$classify(55); // => 'F'
```

### Response
#### Success Response (callable)
- Returns a new function that takes an argument and applies the first matching predicate's handler.

#### Response Example
```php
// The returned function can be called with different arguments
$grade1 = $classify(85);
// => 'B'

$grade2 = $classify(60);
// => 'D'
```
```

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

### Importing Functional PHP Functions

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Demonstrates how to import functions from the Functional PHP library for use in your code. Use `use function Functional\function_name` for specific functions.

```php
use function Functional\map;

$emails = map($users, fn ($user) => $users->getEmail());
```

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

### Importing functions and namespaces in functional-php

Source: https://context7.com/lstrojny/functional-php/llms.txt

Demonstrates preferred import styles for functions and namespaces. Supports PHP 5.6+.

```php
// Preferred import style (PHP 5.6+)
use function Functional\map;
use function Functional\filter;

// Or import the whole namespace as an alias
use Functional as F;
$result = F\map($collection, $callback);
```

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

### Pattern-match style dispatch with `matching()`

Source: https://context7.com/lstrojny/functional-php/llms.txt

Returns a function that tests each `[$predicate, $handler]` pair in order and calls the handler of the first matching predicate. A final `[fn() => true, ...]` pair acts as a default case.

```php
use function Functional\matching;
use function Functional\greater_than_or_equal;

$classify = matching([
    [greater_than_or_equal(90), fn ($s) => 'A'],
    [greater_than_or_equal(80), fn ($s) => 'B'],
    [greater_than_or_equal(70), fn ($s) => 'C'],
    [greater_than_or_equal(60), fn ($s) => 'D'],
    [fn () => true,             fn ($s) => 'F'],
]);

$classify(95); // => 'A'
$classify(73); // => 'C'
$classify(55); // => 'F'
```

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

### Partition collection by callbacks

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Splits a collection into multiple groups based on the return value of provided callbacks. Elements are assigned to the first partition for which the callback returns a truthy value. If no callback succeeds, the element goes into the final partition.

```php
use function Functional\partition;

list($admins, $guests, $users) = partition(
    $collection,
    fn ($user) => $user->isAdmin(),
    fn ($user) => $user->isGuest()
);
```

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

### Pre-fill arguments with partial_left() and partial_right()

Source: https://context7.com/lstrojny/functional-php/llms.txt

Use `partial_left()` to pre-fill arguments from the left and `partial_right()` to pre-fill from the right. This is useful for creating specialized versions of existing functions.

```php
use function Functional\partial_left;
use function Functional\partial_right;
use function Functional\select;

$subtract = fn ($a, $b) => $a - $b;

// partial_left: fixes first argument
$subtractFrom20 = partial_left($subtract, 20);
$subtractFrom20(5);  // => 15

// partial_right: fixes last argument
$subtract5 = partial_right($subtract, 5);
$subtract5(20); // => 15

// Practical: pre-fill a filter
$names = ['alice', 'bob', 'alfred', 'carol'];
$startsWith = fn ($needle, $str) => str_starts_with($str, $needle);
$startsWithA = partial_left($startsWith, 'a');
$aNames = select($names, $startsWithA); // => ['alice', 'alfred']
```

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

### juxt()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Takes a list of functions and returns a new function that applies each function to the given arguments and returns an array of the results. Inspired by Clojure's `juxt`.

```APIDOC
## juxt()

### Description
Takes a list of functions and returns a new function that applies each function to the given arguments and returns an array of the results.

### Signature
``callable Functional\juxt(callable ...$functions)``

### Example
```php
use function Functional\juxt;

$getStats = juxt('min', 'max');
$getStats(3, 1, 5, 2); // [1, 5]

$transform = juxt('strtoupper', 'strtolower', 'strrev');
$transform('Hello'); // ['HELLO', 'hello', 'olleH']
```

_See also `converge()`, which additionally passes the results through a converging function._
```

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

### Partial Application

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Utilities for creating partially applied functions.

```APIDOC
## partial_left()

### Description
Creates a partially applied function by applying arguments from the left.

### Usage
```php
use function Functional\partial_left;

$subtractor = fn ($a, $b) => $a - $b;
$partiallyAppliedSubtractor = partial_left($subtractor, 20);
$partiallyAppliedSubtractor(10); // 10
```
```

```APIDOC
## partial_right()

### Description
Creates a partially applied function by applying arguments from the right.

### Usage
```php
use function Functional\partial_right;

$subtractor = fn ($a, $b) => $a - $b;
$partiallyAppliedSubtractor = partial_right($subtractor, 20);
$partiallyAppliedSubtractor(10); // 10
```
```

```APIDOC
## ary()

### Description
Takes a callable and a count, and calls the callable with that many arguments. Uses `take_left` if positive, or `take_right` if negative. Throws if passed 0.

### Usage
```php
use function Functional\ary;
use function Functional\map;

$array = ['a', 'b', 'c'];
// This fails because map calls its callable with the element, index and the whole collection
// map($array, 'ucfirst');

// Using `ary` to pass only the first argument to `ucfirst`
map($array, ary('ucfirst', 1));
```
```

```APIDOC
## partial_any()

### Description
Creates a partially applied function that resolves placeholders indicated by `Functional\placeholder()` or `Functional\…`.

### Usage
```php
use function Functional\select;
use function Functional\partial_any;
use const Functional\…;

$elements = [
    'john',
    'joe',
    'joanna',
    'patrick',
];

$selected = select($elements, partial_any('substr_count', …, 'jo'));
```
```

```APIDOC
## partial_method()

### Description
Returns a function with a bound method call, expecting the object that receives the method call as the first parameter.

### Usage
```php
use function Functional\select;
use function Functional\partial_method;

// Assuming $users is a collection of objects with an isRegistered() method
$registeredUsers = select($users, partial_method('isRegistered'));
```
```

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

### Pick Element by Property Name/Index - pick()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Pick() retrieves an element from a collection based on its property name or index. If the key does not exist, it returns null or a specified default value.

```php
use function Functional\pick;

$array = ['one' => 1, 'two' => 2, 'three' => 3];
pick($array, 'one'); // 1
pick($array, 'ten'); // null
pick($array, 'ten', 10); // 10
```

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

### Partial Method Application with partial_method()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Shows how `Functional\partial_method` can be used to create a partially applied method call, useful for filtering objects.

```php
use function Functional\select;
use function Functional\partial_method;

// Assume $users is an array of objects with an isRegistered() method
// $registeredUsers = select($users, fn ($user) => $user->isRegistered());

// Using partial_method for a cleaner select call
$registeredUsers = select($users, partial_method('isRegistered'));
```

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

### Match Operator Simulation with match()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

The `match` function returns a new function that simulates a match operator. It iterates through conditions, executing the first matching `$then` callable. Returns `null` if no conditions match.

```php
use function Functional\greater_than_or_equal;
use function Functional\match;

$preschool = fn ($age) => "At {$age} you go to preschool";
$primary = fn ($age) => "At {$age} you go to primary school";
$secondary = fn ($age) => "At {$age} you go to secondary school";

$stage = match([
  [greater_than_or_equal(12), $secondary],
  [greater_than_or_equal(5), $primary],
  [greater_than_or_equal(4), $preschool],
]);

echo $stage(4); // At 4 you go to preschool
echo $stage(5); // At 5 you go to primary school
echo $stage(13); // At 13 you go to secondary school
```

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

### converge()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Accepts a converging function and a list of branching functions, returning a new function that applies branching functions to arguments and then passes their results to the converging function.

```APIDOC
## converge()

### Description
Accepts a converging function and a list of branching functions and returns a new function. The returned function takes a variable number of arguments. The converging function should take the same number of arguments as there are branching functions. Each branching function should take the same number of arguments as the number of arguments passed in to the returned function.

### Signature
``callable Functional\converge(callable $convergingFunction, callable[] $branchingFunctions)``

### Example
```php
use function Functional\converge;

function div($dividend, $divisor) {
    return $dividend / $divisor;
}

$average = converge('div', ['array_sum', 'count']);
$average([1, 2, 3, 4]); // 2.5
```

The returned function passes each of its arguments to each branching function. It then takes the return values of all the branching functions and passes each one as an argument to the converging function. The return value of the converging function is the return value of the returned function.
```

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

### invoke(), invoke_first(), invoke_last()

Source: https://context7.com/lstrojny/functional-php/llms.txt

Call a method on collection items. `invoke()` calls a method on every object; `invoke_first()` / `invoke_last()` call it on the first/last object that has the method.

```APIDOC
## invoke(), invoke_first(), invoke_last()

### Description
Call a method on collection items. `invoke()` calls a method on every object; `invoke_first()` / `invoke_last()` call it on the first/last object that has the method.

### Parameters
- **collection** (iterable) - The collection of objects.
- **method** (string) - The name of the method to call.
- **args** (array, optional) - Arguments to pass to the method.

### Request Example
```php
use function Functional\invoke;
use function Functional\invoke_first;
use function Functional\invoke_last;

// Call a method on all objects
$emails = invoke($users, 'getEmail');

// Call with arguments
invoke($meetings, 'setStatus', ['confirmed']);

// invoke_first: finds first object with the method
$events = [new MandatoryEvent(), new OptionalEvent(), new OptionalEvent()];
invoke_first($events, 'reschedule', ['+1 day']); // calls on first OptionalEvent
invoke_last($events, 'cancel');                  // calls on last OptionalEvent
```

### Response
#### Success Response (mixed)
- **invoke()**: Returns an array of the results from calling the method on each object.
- **invoke_first() / invoke_last()**: Returns the result from calling the method on the first/last matching object, or null if no object has the method.

#### Response Example
```php
// Example for invoke()
$emails = ['alice@example.com', 'bob@example.com'];

// Example for invoke_first() / invoke_last()
// Assuming OptionalEvent has reschedule and cancel methods
// The method is called and returns void or a specific result depending on the method implementation.
```
```

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

### No-Operation Function with noop()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

The `noop` function is a placeholder that performs no operation and returns nothing.

```php
void Functional\noop()
```

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

### compose()

Source: https://context7.com/lstrojny/functional-php/llms.txt

Chains multiple functions together into a single pipeline, passing the output of one function as the input to the next.

```APIDOC
## compose()

### Description
Returns a new function that passes its argument through each function from left to right.

### Parameters
- **...$functions** (callable) - The functions to compose in order.

### Request Example
```php
use function Functional\compose;

$plus2  = fn ($x) => $x + 2;
$times3 = fn ($x) => $x * 3;
$square = fn ($x) => $x ** 2;

$transform = compose($plus2, $times3, $square);
$transform(4); // ((4 + 2) * 3) ^ 2 = 324

// Practical: sanitize and normalize user input
$sanitize = compose('trim', 'strtolower', fn ($s) => preg_replace('/S+/', '-', $s));
$sanitize('  Hello World  '); // => 'hello-world'
```
```

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

### Dropping first or last elements with drop_first() and drop_last()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Use `drop_first()` to remove elements from the beginning of a collection based on a condition, and `drop_last()` to remove elements from the end.

```php
use function Functional\drop_first;
use function Functional\drop_last;

$fn = fn ($user, $index, $collection) => $index < 3;
// All users except the first three
drop_first($users, $fn);
// First three users
drop_last($users, $fn);
```

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

### Curry a function with curry()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Use curry to create a curried version of a function, where each argument is applied one at a time. This allows for partial application of functions step-by-step.

```php
use function Functional\curry;

$curriedSubtractor = curry($subtractor);
$subtractFrom10 = $curriedSubtractor(20);
$subtractFrom10(10); // 10
```

```php
use function Functional\curry;

$curriedAdd = curry(fn ($a, $b, $c, $d) => $a + $b + $c + $d);

$add10 = $curriedAdd(10);
$add15 = $add10(5);
$add42 = $add15(27);
$add42(10); // 52
```

```php
use function Functional\curry;

$add = fn ($a, $b, $c = 10) => $a + $b + $c;

// Curry only required parameters. The default $c will always be 10.
$curriedAdd = curry($add, true);

// This time, 3 parameters will be curried.
$curriedAddWithOptional = curry($add, false);
```

```php
use function Functional\curry;

$curriedAdd = curry(fn ($a, $b, $c, $d) => $a + $b + $c + $d);
$curriedAdd(10)(5)(27)(10); // 52
```

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

### partial_method()

Source: https://context7.com/lstrojny/functional-php/llms.txt

Creates a callback that calls a specified method on an object, useful for partial application in functional contexts.

```APIDOC
## partial_method()

### Description
Returns a callback that calls the named method on whatever object is passed to it.

### Parameters
- **$methodName** (string) - The name of the method to call.
- **...$args** - Arguments to pre-fill for the method call.

### Request Example
```php
use function Functional\partial_method;
use function Functional\select;
use function Functional\map;

// Filter by object method
$activeUsers = select($users, partial_method('isActive'));

// Map method with arguments
$setAdmin = partial_method('setRole', ['admin']);
map($users, $setAdmin); // calls $user->setRole('admin') on each user
```
```

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

### partial_any()

Source: https://context7.com/lstrojny/functional-php/llms.txt

Enables partial application of a function with support for placeholders, allowing any argument position to be left open.

```APIDOC
## partial_any()

### Description
Uses the `…` constant (or `placeholder()` / `Functional\…()`) to mark which positions are left open.

### Parameters
- **$function** (callable) - The function to partially apply.
- **...$args** - Arguments to pre-fill, using `Functional\…` as placeholders.

### Request Example
```php
use function Functional\partial_any;
use function Functional\select;
use const Functional\…;

$elements = ['john', 'joe', 'joanna', 'patrick'];

// Fill second argument of substr_count, leave first as placeholder
$containsJo = partial_any('substr_count', …, 'jo');
$matches = select($elements, $containsJo);
// => ['john', 'joe', 'joanna']

// Multiple placeholders
$format = fn ($prefix, $value, $suffix) => $prefix . $value . $suffix;
$brackets = partial_any($format, '[', …, ']');
$brackets('hello'); // => '[hello]'
```
```

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

### Partial Right Application with partial_right()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Uses `Functional\partial_right` to create a partially applied subtractor function, demonstrating argument order.

```php
use function Functional\partial_right;

$subtractor = fn ($a, $b) => $a - $b;
$partiallyAppliedSubtractor = partial_right($subtractor, 20);
$partiallyAppliedSubtractor(10); // 10
```

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

### Slice from beginning or end with `take_left()` and `take_right()`

Source: https://context7.com/lstrojny/functional-php/llms.txt

These functions slice a collection from the beginning (`take_left`) or end (`take_right`). The `take_right` function has an optional boolean parameter to preserve original keys. Ensure the `Functionalunctions` namespace is imported.

```php
use function Functional\take_left;
use function Functional\take_right;

take_left([1, 2, 3, 4, 5], 3);  // => [1, 2, 3]
take_right([1, 2, 3, 4, 5], 3); // => [3, 4, 5]

// Preserve original keys when taking from right
take_right(['a', 'b', 'c', 'd'], 2, true); // => [2 => 'c', 3 => 'd']
```

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

### Find first or last matching element with `first()` / `head()` and `last()`

Source: https://context7.com/lstrojny/functional-php/llms.txt

Use `first()` (or `head()`) and `last()` to retrieve the first or last element of a collection, respectively. If a callback is provided, they return the first/last element that satisfies the callback's condition. Import the `Functional
ame` functions.

```php
use function Functional\first;
use function Functional\last;

$numbers = [3, 7, 2, 8, 1, 5];

$firstOver5 = first($numbers, fn ($n) => $n > 5); // => 7
$lastOver5  = last($numbers, fn ($n) => $n > 5);  // => 8

// No callback: just first/last element
first($numbers); // => 3
last($numbers);  // => 5
```

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

### match()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Returns a new function that mimics a match operator. It evaluates a series of conditions and executes the corresponding action for the first condition that evaluates to truthy. Returns null if no conditions match.

```APIDOC
## match()

### Description
Returns a new function that behaves like a match operator. `$conditions` should be a bi-dimensional array with items following the given signature: `[callable $if, callable $then]`. `$if` is the predicate, that when returns a truthy value `$then` is called. It stops on the first match and if none of the conditions matches, `null` is returned.

### Signature
``callable match(array $conditions)``

### Example
```php
use function Functional\greater_than_or_equal;
use function Functional\match;

$preschool = fn ($age) => "At {$age} you go to preschool";
$primary = fn ($age) => "At {$age} you go to primary school";
$secondary = fn ($age) => "At {$age} you go to secondary school";

$stage = match([
  [greater_than_or_equal(12), $secondary],
  [greater_than_or_equal(5), $primary],
  [greater_than_or_equal(4), $preschool],
]);

echo $stage(4); // At 4 you go to preschool
echo $stage(5); // At 5 you go to primary school
echo $stage(13); // At 13 you go to secondary school
```
```

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

### Apply multiple functions to same arguments

Source: https://context7.com/lstrojny/functional-php/llms.txt

Use `juxt` to apply a list of functions to the same arguments and collect their results into an array. Useful for gathering multiple statistics or transformations simultaneously.

```php
use function Functional\juxt;

$stats = juxt('min', 'max', 'array_sum');
$stats(3, 1, 4, 1, 5, 9); // => [1, 9, 23]

$transformString = juxt('strtoupper', 'strtolower', 'strrev', 'strlen');
$transformString('Hello'); // => ['HELLO', 'hello', 'olleH', 5]
```

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

### Combine functions with converge()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Use converge to apply a list of branching functions to arguments, then pass their results to a converging function. The converging function should accept as many arguments as there are branching functions.

```php
use function Functional\converge;

function div($dividend, $divisor) {
    return $dividend / $divisor;
}

$average = converge('div', ['array_sum', 'count']);
$average([1, 2, 3, 4]); // 2.5
```

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

### with()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Invokes a callback on a given value if the value is not null, returning the callback's result or a default value.

```APIDOC
## with()

### Description
Invokes a callback on a value if the value is not null. It returns whatever the callback returns. If the initial value is null, it returns a specified default value.

### Signature
``Function\with(mixed $value, callable $callback, bool $invokeValue = true, mixed $default = null): mixed``

### Example
```php
use function Functional\with;

// Assuming create_user and send_welcome_email are defined functions.
// $retval = with(create_user('John Doe'), function ($user) {
//     send_welcome_email($user);
//     return 'my_result';
// });
// $retval would be 'my_result'
```

If the value of `$value` is `null`, `with()` will return `$default` which defaults to be `null`.
```

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

### Take Elements from Left - take_left()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Take_left() creates a new array by taking a specified number of elements from the beginning of a collection. If the collection has fewer elements than requested, the entire collection is returned.

```php
use function Functional\take_left;

take_left([1, 2, 3], 2); // [1, 2]
```

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

### partial_left() and partial_right()

Source: https://context7.com/lstrojny/functional-php/llms.txt

These functions allow for partial application of a function by pre-filling arguments from either the left or the right.

```APIDOC
## partial_left() and partial_right()

### Description
`partial_left()` pre-fills arguments from the left; `partial_right()` pre-fills from the right.

### Parameters
- **$function** (callable) - The function to partially apply.
- **...$args** - Arguments to pre-fill.

### Request Example
```php
use function Functional\partial_left;
use function Functional\partial_right;
use function Functional\select;

$subtract = fn ($a, $b) => $a - $b;

// partial_left: fixes first argument
$subtractFrom20 = partial_left($subtract, 20);
$subtractFrom20(5);  // => 15

// partial_right: fixes last argument
$subtract5 = partial_right($subtract, 5);
$subtract5(20); // => 15

// Practical: pre-fill a filter
$names = ['alice', 'bob', 'alfred', 'carol'];
$startsWith = fn ($needle, $str) => str_starts_with($str, $needle);
$startsWithA = partial_left($startsWith, 'a');
$aNames = select($names, $startsWithA); // => ['alice', 'alfred']
```
```

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

### Convert map to entries and vice versa

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Converts a key-value map into an array of key-value pairs using `entries()`, and reconstructs a map from an array of pairs using `from_entries()`.

```php
use function Functional\entries;
use function Functional\from_entries;

$map   = ['one' => 1, 'two' => 2, 'three' => 3];
$pairs = entries($map); // [['one', 1], ['two', 2], ['three', 3]]
$map2  = from_entries($pairs); // $map === $map2
```

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

### flatten(), intersperse(), entries(), from_entries()

Source: https://context7.com/lstrojny/functional-php/llms.txt

Functions for structural transformations of collections.

```APIDOC
## flatten() + intersperse() + entries() / from_entries()

### Description
Structural transforms for collections.

### Methods
`intersperse(iterable $collection, $separator): array`
`entries(iterable $collection): array`
`from_entries(iterable $collection): array`

### Parameters
#### intersperse
- **collection** (iterable) - The collection to insert separators into.
- **separator** - The value to insert between elements.

#### entries
- **collection** (iterable) - The associative array to convert to pairs.

#### from_entries
- **collection** (iterable) - An array of key-value pairs to convert back to an associative array.

### Request Example
```php
use function Functional\intersperse;
use function Functional\entries;
use function Functional\from_entries;

// Insert separator between elements
intersperse(['a', 'b', 'c'], '-'); // => ['a', '-', 'b', '-', 'c']

// Convert associative array to pairs and back
$map   = ['one' => 1, 'two' => 2, 'three' => 3];
$pairs = entries($map);    // => [['one', 1], ['two', 2], ['three', 3]]
$back  = from_entries($pairs); // => ['one' => 1, 'two' => 2, 'three' => 3]
```
```

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

### zip() and zip_all()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Recombines arrays by index and applies a callback optionally.

```APIDOC
## zip() & zip_all()

### Description
Combines multiple arrays (or traversable collections) by index. `zip()` uses the keys of the first input array, while `zip_all()` considers all keys present in any of the input arrays. An optional callback can be provided to process the combined elements.

### Parameters
#### Path Parameters
- **collection1** (array|Traversable) - Required - The first collection to combine.
- **...** (array|Traversable) - Optional - Additional collections to combine.
- **callback** (callable) - Optional - A callable function that takes elements from the same index across all collections and returns a combined value.

### Response
#### Success Response (array)
- An array containing the combined elements. If a callback is provided, it contains the results of the callback; otherwise, it contains arrays of elements from the same index.

### Request Example
```php
use function Functional\zip;

zip(['one', 'two', 'three'], [1, 2, 3]); // [['one', 1], ['two', 2], ['three', 3]]

zip(
    ['one', 'two', 'three'],
    [1, 2, 3],
    fn ($one, $two) => $one . '|' . $two
); // ['one|1', 'two|2', 'three|3']
```
```

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

### entries() and from_entries()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Convert a key-value map into an array of key-value pairs, and vice versa.

```APIDOC
## entries() & from_entries()

### Description
`entries()` converts an associative array (key-value map) into an array of key-value pairs. `from_entries()` performs the reverse operation, converting an array of key-value pairs back into an associative array.

### Parameters
#### Path Parameters
- **collection** (array|Traversable) - Required - For `entries()`, the associative array to convert. For `from_entries()`, the array of key-value pairs.

### Response
#### Success Response (array)
- For `entries()`, an array of `[key, value]` pairs. For `from_entries()`, an associative array.

### Request Example
```php
use function Functional\entries;
use function Functional\from_entries;

$map   = ['one' => 1, 'two' => 2, 'three' => 3];
$pairs = entries($map); // [['one', 1], ['two', 2], ['three', 3]]
$map2  = from_entries($pairs); // $map === $map2
```
```

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

### Rekey collection with `reindex()`

Source: https://context7.com/lstrojny/functional-php/llms.txt

Returns the collection with keys replaced by the values returned from the callback. Ensure the `Functionalunctions` namespace is imported.

```php
use function Functional\reindex;

$users = [
    ['id' => 'u1', 'name' => 'Alice'],
    ['id' => 'u2', 'name' => 'Bob'],
];

$byId = reindex($users, fn ($user) => $user['id']);
// => ['u1' => ['id'=>'u1','name'=>'Alice'], 'u2' => ['id'=>'u2','name'=>'Bob']]
```

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

### reject() & select()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Selects or rejects elements from a collection based on a condition. Array keys are preserved. If no callback is provided, `select` returns truthy values and `reject` returns falsey values.

```APIDOC
## select() & reject()

### Description
Selects or rejects elements from a collection based on a condition.

### Signature
``array Functional\select(array|Traversable $collection, callable $callback = null)``
``array Functional\reject(array|Traversable $collection, callable $callback = null)``

### Example
```php
use function Functional\select;
use function Functional\reject;

$fn = fn ($user, $key, $collection) => $user->isActive();
$activeUsers = select($users, $fn);
$inactiveUsers = reject($users, $fn);
```

For both functions array keys are preserved.

For both functions if a value for $callback is not provided then the `id()` function is used. For `select`, this means that only the truthy values in the collection will be returned. For `reject`, this means that only the falsey values in the collection will be returned.

Alias for `Functional\select()` is `Functional\filter()`

**Note:** This may unexpectedly turn your indexed array into an associative array, [see here](https://github.com/lstrojny/functional-php/issues/39#issuecomment-48034617) if you always want to keep an indexed array.
```

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

### Building Comparators with compare_on()

Source: https://context7.com/lstrojny/functional-php/llms.txt

Create custom comparison functions for sorting or de-duplication based on object properties or hash values. Requires the `Functional` namespace.

```php
use function Functional\compare_on;
use function Functional\compare_object_hash_on;

$users = [/* User objects with getName() */];

// Sort by name using strcmp
usort($users, compare_on('strcmp', fn ($u) => $u->getName()));

// Sort by object hash (de-duplicate, detect identity)
$diff = array_udiff($setA, $setB, compare_object_hash_on());
```

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

### take_left()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Creates a new array containing a specified number of elements taken from the beginning of a collection. If the collection has fewer elements than requested, the entire collection is returned.

```APIDOC
## take_left()

### Description
Creates a slice of `$collection` with `$count` elements taken from the beginning. If the collection has less than `$count` elements, the whole collection will be returned as an array.

### Signature
`array Functional\take_left(Traversable|array $collection, int $count)`

### Example
```php
use function Functional\take_left;

take_left([1, 2, 3], 2); // [1, 2]
```
```

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

### Group collection by key using `group()`

Source: https://context7.com/lstrojny/functional-php/llms.txt

Splits a collection into sub-arrays grouped by the key returned from the callback. Ensure the `Functionalunctions` namespace is imported.

```php
use function Functional\group;

$people = [
    ['name' => 'Alice', 'dept' => 'Engineering'],
    ['name' => 'Bob',   'dept' => 'Marketing'],
    ['name' => 'Carol', 'dept' => 'Engineering'],
    ['name' => 'Dave',  'dept' => 'Marketing'],
];

$byDept = group($people, fn ($p) => $p['dept']);
// => [
//     'Engineering' => [['name'=>'Alice',...], ['name'=>'Carol',...]],
//     'Marketing'   => [['name'=>'Bob',...],   ['name'=>'Dave',...]]
// ]
```

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

### Apply multiple functions to arguments with juxt()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Use juxt to create a function that applies a list of functions to the same arguments and collects the results in an array. Useful for gathering multiple statistics or transformations from a single input.

```php
use function Functional\juxt;

$getStats = juxt('min', 'max');
$getStats(3, 1, 5, 2); // [1, 5]

$transform = juxt('strtoupper', 'strtolower', 'strrev');
$transform('Hello'); // ['HELLO', 'hello', 'olleH']
```

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

### Pick a single element from a collection by key with `pick()`

Source: https://context7.com/lstrojny/functional-php/llms.txt

The `pick()` function retrieves the value associated with a given key from a collection. If the key does not exist, it returns `null` or a specified default value. Import the `Functional
ame` function.

```php
use function Functional\pick;

$config = ['host' => 'localhost', 'port' => 5432, 'name' => 'mydb'];

pick($config, 'host');        // => 'localhost'
pick($config, 'password');    // => null
pick($config, 'password', 'secret'); // => 'secret'
```

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

### Partial Left Application with partial_left()

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Uses `Functional\partial_left` to create a partially applied subtractor function.

```php
use function Functional\partial_left;

$subtractor = fn ($a, $b) => $a - $b;
$partiallyAppliedSubtractor = partial_left($subtractor, 20);
$partiallyAppliedSubtractor(10); // 10
```

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

### not

Source: https://github.com/lstrojny/functional-php/blob/main/docs/functional-php.md

Returns a new function which takes the same arguments as the original function, but returns the logical negation of its result.

```APIDOC
## not

### Description
Return a new function which takes the same arguments as the original function, but returns the logical negation of its result.

### Signature
``callable Functional\not(callable $callback)``

### Parameters
#### Path Parameters
- **callback** (callable) - The callback function whose result will be negated.

### Request Example
```php
use function Functional\not;

$isEven = fn ($number) => $number % 2 === 0;
$isOdd = not($isEven);
$isOdd(1); // true
$isOdd(2); // false
```
```
Tokens:
Raw