Option

https://github.com/prewk/option
Admin
A PHP implementation of Rust's Option type, providing a way to handle potentially null values with a...
Tokens:37,542
Snippets:367
Trust Score:8.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/prewk/option/blob/master/readme.md

Install the prewk/option package via Composer.

```bash
composer require prewk/option
```

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

### and usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Example call to and, producing Some('bar').

```php
$result = (new Some('foo'))->and(new Some('bar')); // Some('bar')
```

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

### and usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows how to use and to chain options, returning the second option if the first is Some.

```php
$opt = $a->and($b); // $b if $a is Some, None otherwise
```

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

### Option::fromKey usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Example usage of fromKey: returns Some('foo') when key exists, None when key does not exist.

```php
$opt = Option::fromKey(['bar' => 'foo'], 'bar'); // Some('foo')
$opt = Option::fromKey(['bar' => 'foo'], 'baz'); // None
```

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

### Option::fromFirst usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Example usage of fromFirst: returns Some('foo') for non-empty array, None for empty array.

```php
$opt = Option::fromFirst(['foo', 'bar']); // Some('foo')
$opt = Option::fromFirst([]);             // None
```

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

### Option::fromEmptyable usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Example usage of fromEmptyable: returns None for empty string, Some for non-empty string.

```php
$opt = Option::fromEmptyable('');   // None
$opt = Option::fromEmptyable('foo'); // Some('foo')
```

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

### or usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows how to use or to provide a fallback option and then unwrap the result.

```php
$value = findSomething()->or(findSomethingElse())->unwrap();
```

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

### okOrElse usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Example call to okOrElse, producing Ok('foo').

```php
$result = $some->okOrElse(static fn () => 'bar'); // Ok('foo')
```

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

### mapOrElse usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Example call to mapOrElse, producing 'foobar'.

```php
$value = $some->mapOrElse(static fn () => 'baz', static fn ($v) => $v . 'bar'); // 'foobar'
```

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

### or usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Example call to or, returning the same $some instance.

```php
$result = $some->or(new Some('bar')); // the same $some instance
```

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

### mapOr usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Example call to mapOr, producing 'foobaz'.

```php
$value = $some->mapOr('bar', static fn ($v) => $v . 'baz'); // 'foobaz'
```

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

### iter usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows how to iterate over the Option's value, with zero or one iteration depending on Some or None.

```php
foreach ($option->iter() as $value) { /* zero or one iteration */ }
```

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

### okOr usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Example call to okOr, producing Ok('foo').

```php
$result = (new Some('foo'))->okOr('bar'); // Ok('foo')
```

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

### filter usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows how to use filter to conditionally keep a Some based on a predicate.

```php
$opt = $option->filter(static fn ($v) => $v->isActive());
```

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

### orElse usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows how to use orElse to lazily compute a fallback option.

```php
$opt = $option->orElse(static fn () => loadFallback());
```

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

### okOrElse usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows how to call okOrElse with a zero-arg callable that returns the error value for a None.

```php
$result = $option->okOrElse(static fn () => new Failed('missing'));
```

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

### andThen usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows how to use andThen to chain a function that returns an Option, commonly called flatmap.

```php
$opt = $option->andThen(static fn ($v) => findRelated($v)); // Option<Related>
```

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

### Usage example for prewk/option

Source: https://github.com/prewk/option/blob/master/_autodocs/readme.md

Shows static construction with Some::fromNullable, fallback with unwrapOr, chaining with or, custom exception with expect, and guard with isNone.

```php
use Prewk\Option\{Some, None};

// Static construction
$option = Some::fromNullable($maybeNull);

// Fallback to value
$value = findSomething()->unwrapOr(null);

// Chain a fallback option, throw only if both fail
$value = findSomething()->or(findSomethingElse())->unwrap();

// Custom exception on missing value (None)
$value = findSomething()->expect(new Exception("Oh noes!"));

// Guard with the asserting predicates
if ($option->isNone()) {
    // ...
}
```

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

### Usage example with Some, None, and Option methods

Source: https://github.com/prewk/option/blob/master/readme.md

Shows how to use the Option type with Some and None, and methods like unwrapOr, or, and expect.

```php
use Prewk\Option;
use Prewk\Option\{Some, None};

function findSomething(): Option {
    // ...
    if ($foundSomething) {
        return new Some($thing);
    } else {
        return new None;
    }
}

function findSomethingElse(): Result {
    // ...
    if ($foundSomething) {
        return new Some($thing);
    } else {
        return new None;
    }
}

// Fallback to value
$value = findSomething()->unwrapOr(null);

// Fallback to option and throw an exception if both fail
$value = findSomething()->or(findSomethingElse())->unwrap();

// Throw custom exception on missing thing (None)
$value = findSomething()->expect(new Exception("Oh noes!"));
```

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

### andThen usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Example call to andThen, producing Some('foobar').

```php
$result = (new Some('foo'))->andThen(static fn ($v) => new Some($v . 'bar')); // Some('foobar')
```

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

### or usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Calls or on a None instance, returning the same $optb instance.

```php
$optb = new Some('foo');
$result = (new None())->or($optb); // the same $optb instance
```

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

### orElse usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Example call to orElse, returning the same $some instance.

```php
$result = $some->orElse(static fn () => new Some('bar')); // the same $some instance
```

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

### okOr usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows how to call okOr with an error value, returning a Result usable with the prewk/result API.

```php
$result = $option->okOr('missing'); // Result usable with the prewk/result API
```

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

### Option::fromNullable usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Example usage of fromNullable: returns Some<T> for non-null values, None otherwise.

```php
$opt = Option::fromNullable($maybeNull); // Some<T> for non-null, None otherwise
```

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

### filter usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Shows both a kept and a dropped case.

```php
$kept = (new Some('foo'))->filter(static fn ($v) => $v === 'foo'); // Some('foo')
$dropped = (new Some('foo'))->filter(static fn () => false);       // None
```

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

### iter usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Iterates exactly once over the contained value.

```php
foreach ($some->iter() as $value) { /* exactly one iteration */ }
```

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

### expect() usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Catches the exact exception instance passed to expect(). The caught exception is the same object with the same message.

```php
try {
    (new None())->expect(new Exception('foo'));
} catch (Exception $e) {
    // $e === the instance passed to expect(), message 'foo'
}
```

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

### Use some() to wrap a value

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/helpers.md

Example of calling some() with a variable to create a Some instance. Equivalent to new Some($value) and accepts null without checking.

```php
$option = some($foundSomething); // Some<T>
```

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

### and usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Calls and on a None instance, returning a new None.

```php
$result = (new None())->and(new Some('foo')); // new None()
```

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

### Use none() to represent absence

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/helpers.md

Example of calling none() to create a None instance. Equivalent to new None().

```php
$option = none(); // None
```

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

### iter usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Iterates over the result of iter(), which yields zero iterations.

```php
foreach ($none->iter() as $value) { /* zero iterations */ }
```

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

### inspect() usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

The side-effect callable is never run, and the same None instance is returned.

```php
$none->inspect($sideEffect); // $sideEffect never runs, returns $none
```

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

### orElse usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Calls orElse on a None instance, returning the same $optb instance.

```php
$optb = new Some('foo');
$result = (new None())->orElse(static fn () => $optb); // the same $optb instance
```

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

### unwrap() usage

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows calling unwrap() on an option to get the contained value.

```php
$value = $option->unwrap();
```

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

### filter usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Calls filter on a None instance, returning the same instance.

```php
$result = (new None())->filter(static fn () => true); // the same $none instance
```

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

### andThen usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Calls andThen on a None instance, returning a new None.

```php
$result = (new None())->andThen(static fn () => new Some('foo')); // new None()
```

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

### okOrElse usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Calls okOrElse on a None instance, returning an Err('foo').

```php
$result = (new None())->okOrElse(static fn () => 'foo'); // Err('foo')
```

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

### unwrap() usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Catches the OptionException thrown by unwrap() and verifies the message is 'Unwrapped a None'.

```php
try {
    (new None())->unwrap();
} catch (Prewk\Option\OptionException $e) {
    // $e->getMessage() === 'Unwrapped a None'
}
```

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

### unwrapOr() usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns the fallback value 'foo' as an identical reference when called on a None instance.

```php
$optb = 'foo';
$value = (new None())->unwrapOr($optb); // 'foo', identical reference
```

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

### okOr usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Calls okOr on a None instance, returning an Err('foo').

```php
$result = (new None())->okOr('foo'); // Err('foo')
```

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

### unwrapOrElse() usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Calls the fallback function to compute the value when the option is None.

```php
$value = (new None())->unwrapOrElse(static fn () => computeFallback());
```

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

### map() usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Mapping a None returns a new None instance, distinct from the original.

```php
$mapped = (new None())->map(static fn () => 'foo'); // new None(), distinct instance
```

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

### mapOrElse usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Calls mapOrElse on a None instance, returning 'foo' from the default callable.

```php
$value = (new None())->mapOrElse(static fn () => 'foo', static fn () => 'bar'); // 'foo'
```

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

### Instantiate Some with a value

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Creates a new Some instance wrapping the string 'foo'.

```php
$option = new Some('foo');
```

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

### expect() usage with exception

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows calling expect() with a new Exception instance to throw if the value is None.

```php
$value = findSomething()->expect(new Exception("Oh noes!"));
```

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

### and(self $optb): self

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Returns the second Option if the receiver is a Some, otherwise returns a new None.

```APIDOC
## and(self $optb): self

### Description
Returns the second Option if the receiver is a Some, otherwise returns a new None.

### Method
and

### Parameters
- `$optb` (Option<U>) - Required - Any Option instance (the `self` type means "same class", accepted parameter is typed `Option`)

### Returns
`Option<U>`: `$optb` if the receiver is a `Some`; a new `None` if the receiver is a `None`.

### Example
```php
$opt = $a->and($b); // $b if $a is Some, None otherwise
```
```

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

### Some constructor with promoted property

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Constructor that accepts any value, including null, and promotes it to the private property $value. No null check is performed.

```php
public function __construct(
    private $value,
) {
}
```

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

### and method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns the provided Option unchanged.

```php
public function and(Option $optb): Option
{
    return $optb;
}
```

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

### unwrap(): never

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Unwraps the Option, but for None it always throws an OptionException.

```APIDOC
## unwrap(): never

### Description
Unwraps the Option, but for None it always throws an OptionException.

### Method
unwrap

### Signature
```php
public function unwrap(): never
```

### Parameters
None

### Return Value
- **never** - Always throws, never returns.

### Throws
- **Prewk\Option\OptionException** - With message 'Unwrapped a None'.

### Example
```php
try {
    (new None())->unwrap();
} catch (Prewk\Option\OptionException $e) {
    // $e->getMessage() === 'Unwrapped a None'
}
```
```

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

### Option::fromKey implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Static constructor that returns Some if the key exists in the collection (using array_key_exists), None otherwise.

```php
public static function fromKey(array $coll, $key): self
{
    return array_key_exists($key, $coll) ? new Some($coll[$key]) : new None();
}
```

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

### Option::fromFirst implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Static constructor that returns Some wrapping the first item yielded by the iterable, or None if the iterable is empty.

```php
public static function fromFirst(iterable $iterable): self
{
    foreach ($iterable as $item) {
        return new Some($item);
    }

    return new None();
}
```

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

### none() global function

Source: https://github.com/prewk/option/blob/master/_autodocs/readme.md

Global helper function that creates a None option. It is autoloaded from helpers.php and available in the global scope.

```APIDOC
## [PHP] none()

### Description
Global helper function that creates a None option. It is autoloaded from helpers.php and available in the global scope.

### Method
Global function

### Endpoint
`none()`

### Parameters
None

### Return Value
- `None` - A None option.

### Example
```php
$option = none();
```
```

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

### new Some($value)

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Creates a new Some instance wrapping the given value. The constructor accepts any value, including null, and stores it in the private promoted property $value.

```APIDOC
## Constructor

### Description
Creates a new Some instance wrapping the given value. The constructor accepts any value, including null, and stores it in the private promoted property $value.

### Method
Constructor

### Signature
```php
public function __construct(
    private $value,
) {}
```

### Parameters
- `$value` (mixed) - Required - The wrapped value; promoted to the private property `Some::$value`.

### Example
```php
$option = new Some('foo');
```
```

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

### and method signature

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Declares the abstract and method that returns the second option if the receiver is Some, otherwise a new None.

```php
abstract public function and(self $optb): self;
```

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

### andThen method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Applies the flatmap-style function to the contained value and returns its result directly.

```php
public function andThen(callable $op): Option
{
    return $op($this->value);
}
```

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

### iter method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns an empty array, so iteration yields nothing.

```php
public function iter(): iterable
{
    return [];
}
```

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

### mapOr() usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns the default value 'foo' unchanged when called on a None instance.

```php
$default = 'foo';
$value = (new None())->mapOr($default, static fn () => 'bar'); // 'foo'
```

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

### or method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns the provided fallback option as-is.

```php
public function or(Option $optb): Option
{
    return $optb;
}
```

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

### Option::fromEmptyable implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Static constructor that returns Some if the argument is non-empty per PHP's empty(), None otherwise.

```php
public static function fromEmptyable($thing): self
{
    return ! empty($thing) ? new Some($thing) : new None();
}
```

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

### map() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns a new Some instance wrapping the result of applying the mapper to the contained value.

```php
public function map(callable $mapper): Option
{
    return new self($mapper($this->value));
}
```

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

### or(self $optb): self

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Returns the receiver if it is a Some, otherwise returns the fallback option verbatim.

```APIDOC
## or(self $optb): self

### Description
Returns the receiver if it is a Some, otherwise returns the fallback option verbatim.

### Method
or

### Parameters
- `$optb` (Option<T>) - Required - Fallback option returned when the receiver is a `None`

### Returns
`Option<T>`: `$this` if it is a `Some`, or `$optb` verbatim if it is a `None`.

### Example
```php
$value = findSomething()->or(findSomethingElse())->unwrap();
```
```

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

### Usage of expect()

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns the contained value 'foo' from a Some instance, ignoring the exception.

```php
$value = (new Some('foo'))->expect(new Exception('bar')); // 'foo'
```

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

### map() usage with string concatenation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows mapping a Some('foo') to Some('foobar') using an arrow function.

```php
$opt = (new Some('foo'))->map(static fn ($v) => $v . 'bar'); // Some('foobar')
```

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

### expect() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Throws the passed exception instance unchanged. Declared to return never, so static analysis treats it as unreachable.

```php
public function expect(Exception $msg): never
{
    throw $msg;
}
```

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

### expect() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns the contained value and ignores the passed exception. Never throws.

```php
public function expect(Exception $msg)
{
    return $this->value;
}
```

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

### isSome() usage example

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Shows that calling isSome() on a None instance always returns false, so the block is never executed.

```php
if ((new None())->isSome()) { /* never reached */ }
```

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

### Usage pattern with some() and none()

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/helpers.md

Shows a typical function returning some($thing) when a value is found and none() otherwise.

```php
function findSomething(): Option
{
    // ...
    if ($foundSomething) {
        return some($thing);
    } else {
        return none();
    }
}
```

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

### Option::fromNullable implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Static constructor that returns Some if the argument passes isset(), otherwise None. Returns None for null and undefined variables.

```php
public static function fromNullable($thing): self
{
    return isset($thing) ? new Some($thing) : new None();
}
```

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

### unwrap()

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns the contained value. Throws nothing.

```APIDOC
## unwrap()

### Description
Returns the contained value. Throws nothing.

### Method
unwrap

### Signature
```php
public function unwrap()
```

### Parameters
None

### Return Value
- `T` - The contained value.

### Example
```php
$value = (new Some('foo'))->unwrap(); // 'foo'
```
```

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

### Option::fromKey(array $coll, $key): self

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Static constructor that returns a Some<V> if the given key exists in the collection, otherwise a None. Uses array_key_exists to determine membership.

```APIDOC
## Option::fromKey(array $coll, $key): self

### Description
Static constructor that returns a Some<V> if the given key exists in the collection, otherwise a None. Uses array_key_exists to determine membership.

### Method
Static method

### Signature
```php
public static function fromKey(array $coll, $key): self
```

### Parameters
- `$coll` (array<K, V>) - Required - The collection to look the key up in
- `$key` (K) - Required - The key to look up

### Returns
`Option<V>`: `Some<V>` if the key exists in the collection, `None` otherwise.

### Example
```php
$opt = Option::fromKey(['bar' => 'foo'], 'bar'); // Some('foo')
$opt = Option::fromKey(['bar' => 'foo'], 'baz'); // None
```
```

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

### unwrap() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Throws a new OptionException with the message 'Unwrapped a None'. This is the only place OptionException is constructed.

```php
public function unwrap(): never
{
    throw new OptionException('Unwrapped a None');
}
```

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

### Usage of map()

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Maps the contained value 'foo' to 'foobar' and returns a new Some instance.

```php
$mapped = (new Some('foo'))->map(static fn ($value) => $value . 'bar');
// Some('foobar'), distinct instance
```

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

### none(): \Prewk\Option\None

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/helpers.md

Procedural helper that creates a None instance representing a lack of value. Equivalent to `new \Prewk\Option\None()`.

```APIDOC
## none(): \Prewk\Option\None

### Description
Procedural helper that creates a None instance representing a lack of value. Equivalent to `new \Prewk\Option\None()`.

### Parameters
None

### Returns
- `\Prewk\Option\None` - The None instance

### Example
```php
$option = none(); // None
```
```

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

### isNone() usage with Psalm narrowing

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows how isNone() narrows the option type to None<T> for Psalm inside an if condition.

```php
if ($option->isNone()) { /* option narrows to None<T> for Psalm */ }
```

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

### unwrapOr($optb)

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns the provided default value. For None, it returns the default unchanged.

```APIDOC
## unwrapOr($optb)

### Description
Returns the provided default value. For None, it returns the default unchanged.

### Method
unwrapOr

### Signature
```php
public function unwrapOr($optb)
```

### Parameters
- **$optb** (U) - Required - The value to return.

### Return Value
- **U** - The `$optb` value unchanged.

### Example
```php
$optb = 'foo';
$value = (new None())->unwrapOr($optb); // 'foo', identical reference
```
```

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

### inspect() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Invokes the callable exactly once with the contained value and returns the same instance.

```php
public function inspect(callable $f): Option
{
    $f($this->value);

    return $this;
}
```

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

### isNone(): bool

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Returns true if the option is a None value, false otherwise. Annotated with Psalm assertions for type narrowing.

```APIDOC
## isNone(): bool

### Description
Returns `true` if the option is a `None` value, `false` otherwise. Annotated `@psalm-assert-if-true None<T> $this` / `@psalm-assert-if-false Some<T> $this`.

### Method
`isNone`

### Signature
```php
abstract public function isNone(): bool;
```

### Parameters
None.

### Returns
- `bool` - `true` if the option is a `None` value, `false` otherwise.

### Example
```php
if ($option->isNone()) { /* option narrows to None<T> for Psalm */ }
```
```

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

### andThen method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns a new None instance, never invoking the provided callable.

```php
public function andThen(callable $op): Option
{
    return new self();
}
```

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

### None::unwrap()

Source: https://github.com/prewk/option/blob/master/_autodocs/errors.md

Throws an OptionException when called on a None instance. This method is declared to return never, indicating it always throws.

```APIDOC
## None::unwrap()

### Description
Throws an OptionException when called on a None instance. This method is declared to return never, indicating it always throws.

### Method
unwrap

### Endpoint
None::unwrap()

### Parameters
None

### Throws
- **Prewk\Option\OptionException** - Always thrown with message 'Unwrapped a None'

### Example
```php
use Prewk\Option\None;
use Prewk\Option\OptionException;

try {
    (new None())->unwrap();
} catch (OptionException $e) {
    // $e->getMessage() === 'Unwrapped a None'
}
```
```

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

### and method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns a new None instance, discarding the provided option.

```php
public function and(Option $optb): Option
{
    return new self();
}
```

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

### expect(Exception $msg): never

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Throws the provided exception instance. For None, it always throws the passed exception.

```APIDOC
## expect(Exception $msg): never

### Description
Throws the provided exception instance. For None, it always throws the passed exception.

### Method
expect

### Signature
```php
public function expect(Exception $msg): never
```

### Parameters
- **$msg** (Exception) - Required - The exact exception instance that is thrown.

### Return Value
- **never** - Always throws, never returns.

### Throws
- **Exception** - The passed `$msg` instance.

### Example
```php
try {
    (new None())->expect(new Exception('foo'));
} catch (Exception $e) {
    // $e === the instance passed to expect(), message 'foo'
}
```
```

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

### Usage of unwrap()

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns the contained value 'foo' from a Some instance.

```php
$value = (new Some('foo'))->unwrap(); // 'foo'
```

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

### some() global function

Source: https://github.com/prewk/option/blob/master/_autodocs/readme.md

Global helper function that creates a Some option from a value. It is autoloaded from helpers.php and available in the global scope.

```APIDOC
## [PHP] some()

### Description
Global helper function that creates a Some option from a value. It is autoloaded from helpers.php and available in the global scope.

### Method
Global function

### Endpoint
`some(mixed $value)`

### Parameters
- **$value** (mixed) - Required - The value to wrap in a Some option.

### Return Value
- `Some` - A Some option containing the given value.

### Example
```php
$option = some($value);
```
```

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

### isNone() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Always returns false for a Some instance.

```php
public function isNone(): bool
{
    return false;
}
```

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

### unwrapOr() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns the provided fallback value unchanged, as the same reference.

```php
public function unwrapOr($optb)
{
    return $optb;
}
```

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

### okOrElse method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns a new Err wrapping the result of the error callable.

```php
public function okOrElse(callable $err): Result
{
    return new Err($err());
}
```

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

### and(Option $optb): Option

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns the provided Option instance unchanged. Since a Some is always present, the other option is returned directly.

```APIDOC
## and(Option $optb): Option

### Description
Returns the provided Option instance unchanged. Since a Some is always present, the other option is returned directly.

### Method
and

### Parameters
- `$optb` (Option) - Required - Any Option instance

### Returns
Option<U> — `$optb` itself, passed through unchanged.

### Example
```php
$result = (new Some('foo'))->and(new Some('bar')); // Some('bar')
```
```

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

### Instantiate None with new None()

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Creates a new None instance using the implicit constructor. This is the direct way to represent an absent value.

```php
$option = new None();
```

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

### unwrapOr($optb)

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns the contained value. The provided fallback is ignored and never returned by a Some instance.

```APIDOC
## unwrapOr($optb)

### Description
Returns the contained value. The provided fallback is ignored and never returned by a Some instance.

### Method
unwrapOr

### Signature
```php
public function unwrapOr($optb)
```

### Parameters
- `$optb` (mixed) - Required - Ignored; never returned by a Some.

### Return Value
- `T` - The contained value.

### Example
```php
$some = new Some('foo');
$value = $some->unwrapOr('bar'); // 'foo'
```
```

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

### unwrapOrElse() usage with arrow function

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows calling unwrapOrElse() with a static arrow function that computes the fallback.

```php
$value = $option->unwrapOrElse(static fn () => $default);
```

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

### and(Option $optb): Option

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns a new None instance, discarding the provided option. This method is used to chain options where the result is None if the first is None.

```APIDOC
## and(Option $optb): Option

### Description
Returns a new None instance, discarding the provided option. This method is used to chain options where the result is None if the first is None.

### Method
and

### Signature
```php
public function and(Option $optb): Option
```

### Parameters
- `$optb` (Option) - Required - Never returned

### Returns
`Option<U>` - a *new* `None` instance; `$optb` is discarded.

### Example
```php
$result = (new None())->and(new Some('foo')); // new None()
```
```

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

### expect(Exception $msg)

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Returns the contained value or throws the provided exception if the option is None. The exception instance passed is thrown exactly as given.

```APIDOC
## expect(Exception $msg)

### Description
Returns `T` (the contained value). Throws `$msg` (the exact exception instance passed in) if the value is a `None`. Documented `@throws Exception`.

### Method
`expect`

### Signature
```php
abstract public function expect(Exception $msg);
```

### Parameters
- `$msg` (Exception) - Required - The exception to throw if the value is a `None`.

### Returns
- `T` - The contained value if the option is a `Some`.

### Throws
- `Exception` - The exact exception instance passed in if the option is a `None`.

### Example
```php
$value = findSomething()->expect(new Exception("Oh noes!"));
```
```

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

### Some::fromNullable

Source: https://github.com/prewk/option/blob/master/_autodocs/readme.md

Static constructor that creates a Some option from a nullable value. If the value is null, it returns None; otherwise, it wraps the value in Some.

```APIDOC
## [PHP] Some::fromNullable

### Description
Static constructor that creates a Some option from a nullable value. If the value is null, it returns None; otherwise, it wraps the value in Some.

### Method
Static method

### Endpoint
`Some::fromNullable(mixed $value)`

### Parameters
- **$value** (mixed) - Required - The value to wrap, may be null.

### Return Value
- `Option<T>` - Returns `Some<T>` if value is not null, `None<T>` if value is null.

### Example
```php
$option = Some::fromNullable($maybeNull);
```
```

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

### Option::fromFirst(iterable $iterable): self

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Static constructor that returns a Some<V> wrapping the first item yielded by the iterable, or None if the iterable is empty.

```APIDOC
## Option::fromFirst(iterable $iterable): self

### Description
Static constructor that returns a Some<V> wrapping the first item yielded by the iterable, or None if the iterable is empty.

### Method
Static method

### Signature
```php
public static function fromFirst(iterable $iterable): self
```

### Parameters
- `$iterable` (iterable<V>) - Required - Any iterable value

### Returns
`Option<V>`: `Some<V>` wrapping the first item yielded by the iterable, or `None` if the iterable is empty.

### Example
```php
$opt = Option::fromFirst(['foo', 'bar']); // Some('foo')
$opt = Option::fromFirst([]);             // None
```
```

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

### some($value): \Prewk\Option\Some

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/helpers.md

Procedural helper that wraps a value in a Some instance. Equivalent to `new \Prewk\Option\Some($value)`, including accepting null.

```APIDOC
## some($value): \Prewk\Option\Some

### Description
Procedural helper that wraps a value in a Some instance. Equivalent to `new \Prewk\Option\Some($value)`, including accepting null.

### Parameters
- `$value` (mixed, T) - Required - The value to wrap

### Returns
- `\Prewk\Option\Some<T>` - The Some instance wrapping the value

### Example
```php
$option = some($foundSomething); // Some<T>
```
```

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

### unwrap() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns the contained value without throwing.

```php
public function unwrap()
{
    return $this->value;
}
```

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

### iter method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns a one-element array containing the wrapped value.

```php
public function iter(): iterable
{
    return [$this->value];
}
```

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

### isSome(): bool

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Returns true if the option is a Some value, false otherwise. Annotated with Psalm assertions for type narrowing.

```APIDOC
## isSome(): bool

### Description
Returns `true` if the option is a `Some` value, `false` otherwise. Annotated `@psalm-assert-if-true Some<T> $this` / `@psalm-assert-if-false None<T> $this`.

### Method
`isSome`

### Signature
```php
abstract public function isSome(): bool;
```

### Parameters
None.

### Returns
- `bool` - `true` if the option is a `Some` value, `false` otherwise.

### Example
```php
if ($option->isSome()) { /* option narrows to Some<T> for Psalm */ }
```
```

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

### or method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns $this unchanged, ignoring the provided Option.

```php
public function or(Option $optb): Option
{
    return $this;
}
```

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

### Option::fromEmptyable($thing): self

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Static constructor that returns a Some<V> if the given value is non-empty per PHP's empty(), otherwise a None. Useful for converting empty values into an Option.

```APIDOC
## Option::fromEmptyable($thing): self

### Description
Static constructor that returns a Some<V> if the given value is non-empty per PHP's empty(), otherwise a None. Useful for converting empty values into an Option.

### Method
Static method

### Signature
```php
public static function fromEmptyable($thing): self
```

### Parameters
- `$thing` (mixed) - Required - The value; PHP's `empty()` decides the outcome

### Returns
`Option<V>`: `Some<V>` if the argument is non-empty per PHP's `empty()`, `None` if it is empty.

### Example
```php
$opt = Option::fromEmptyable('');   // None
$opt = Option::fromEmptyable('foo'); // Some('foo')
```
```

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

### expect(Exception $msg)

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Returns the contained value. The passed exception is ignored and never thrown by a Some instance.

```APIDOC
## expect(Exception $msg)

### Description
Returns the contained value. The passed exception is ignored and never thrown by a Some instance.

### Method
expect

### Signature
```php
public function expect(Exception $msg)
```

### Parameters
- `$msg` (Exception) - Required - Ignored; never thrown by a Some.

### Return Value
- `T` - The contained value.

### Example
```php
$value = (new Some('foo'))->expect(new Exception('bar')); // 'foo'
```
```

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

### Define some() and none() procedural helpers

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/helpers.md

Full source of helpers.php defining global-scope functions some() and none() as alternatives to new Some() and new None(). Both are guarded by function_exists() and marked @codeCoverageIgnore.

```php
<?php
/**
 * Procedural style construction of Option instances
 *
 * @author Oskar Thornblad
 */

if (! function_exists('some')) {
    /**
     * Represent the existance of a value
     *
     * @codeCoverageIgnore
     *
     * @template T
     *
     * @param T $value
     * @return \Prewk\Option\Some<T>
     */
    function some($value): \Prewk\Option\Some
    {
        return new \Prewk\Option\Some($value);
    }
}

if (! function_exists('none')) {
    /**
     * Represent a lack of value
     *
     * @codeCoverageIgnore
     */
    function none(): \Prewk\Option\None
    {
        return new \Prewk\Option\None();
    }
}
```

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

### isSome() usage with Psalm narrowing

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows how isSome() narrows the option type to Some<T> for Psalm inside an if condition.

```php
if ($option->isSome()) { /* option narrows to Some<T> for Psalm */ }
```

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

### unwrap()

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Returns the contained value or throws an OptionException if the option is None. This is the only place OptionException is raised.

```APIDOC
## unwrap()

### Description
Returns `T` (the contained value). Throws `OptionException` if the value is a `None`; this is the only place `OptionException` is raised.

### Method
`unwrap`

### Signature
```php
abstract public function unwrap();
```

### Parameters
None.

### Returns
- `T` - The contained value if the option is a `Some`.

### Throws
- `OptionException` - If the option is a `None`.

### Example
```php
$value = $option->unwrap();
```
```

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

### okOrElse method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Converts the Some to an Ok result, ignoring the error callable.

```php
public function okOrElse(callable $err): Result
{
    return new Ok($this->value);
}
```

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

### isNone(): bool

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Checks if the Option is None. For None, always returns true.

```APIDOC
## isNone(): bool

### Description
Checks if the Option is None. For None, always returns true.

### Method
isNone

### Signature
```php
public function isNone(): bool
```

### Parameters
None

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

### Example
```php
if ((new None())->isNone()) { /* always reached */ }
```
```

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

### map() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns a new None instance, never invoking the mapper callable. The new instance is distinct from $this.

```php
public function map(callable $mapper): Option
{
    return new self();
}
```

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

### unwrapOr() usage with null fallback

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Shows calling unwrapOr() with null as the fallback value.

```php
$value = findSomething()->unwrapOr(null);
```

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

### or(Option $optb): Option

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns the provided fallback option as-is. This method is used to provide an alternative option when the current one is None.

```APIDOC
## or(Option $optb): Option

### Description
Returns the provided fallback option as-is. This method is used to provide an alternative option when the current one is None.

### Method
or

### Signature
```php
public function or(Option $optb): Option
```

### Parameters
- `$optb` (Option) - Required - The fallback option; returned as-is

### Returns
`Option<T>` - `$optb`, same reference.

### Example
```php
$optb = new Some('foo');
$result = (new None())->or($optb); // the same $optb instance
```
```

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

### Option::or

Source: https://github.com/prewk/option/blob/master/_autodocs/readme.md

Instance method that returns the option itself if it is Some, otherwise returns the provided fallback option. Useful for chaining fallback options.

```APIDOC
## [PHP] Option::or

### Description
Instance method that returns the option itself if it is Some, otherwise returns the provided fallback option. Useful for chaining fallback options.

### Method
Instance method

### Endpoint
`Option::or(Option $other)`

### Parameters
- **$other** (Option) - Required - The fallback option to return if this option is None.

### Return Value
- `Option` - Returns `$this` if Some, otherwise `$other`.

### Example
```php
$value = findSomething()->or(findSomethingElse())->unwrap();
```
```

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

### Option::isNone

Source: https://github.com/prewk/option/blob/master/_autodocs/readme.md

Instance method that returns true if the option is None, false otherwise. This method has Psalm assertion annotations for static type narrowing.

```APIDOC
## [PHP] Option::isNone

### Description
Instance method that returns true if the option is None, false otherwise. This method has Psalm assertion annotations for static type narrowing.

### Method
Instance method

### Endpoint
`Option::isNone()`

### Parameters
None

### Return Value
- `bool` - True if the option is None, false otherwise.

### Example
```php
if ($option->isNone()) {
    // ...
}
```
```

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

### isSome() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Always returns true for a Some instance.

```php
public function isSome(): bool
{
    return true;
}
```

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

### isNone() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Overrides the abstract isNone() method to always return true, confirming the absence of a value.

```php
public function isNone(): bool
{
    return true;
}
```

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

### okOr method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns a new Err wrapping the provided error value.

```php
public function okOr($err): Result
{
    return new Err($err);
}
```

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

### or method signature

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Declares the abstract or method that returns the receiver if Some, otherwise the fallback option.

```php
abstract public function or(self $optb): self;
```

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

### isNone(): bool - abstract method declaration

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Declares the abstract method isNone() that returns true if the option is a None value. Annotated with @psalm-assert-if-true None<T> $this and @psalm-assert-if-false Some<T> $this.

```php
abstract public function isNone(): bool;
```

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

### inspect() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Returns $this unchanged and never invokes the provided callable, since there is no value to inspect.

```php
public function inspect(callable $f): Option
{
    return $this;
}
```

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

### andThen method signature

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/option.md

Declares the abstract andThen method that applies a flatmap-style function to the wrapped value of a Some.

```php
abstract public function andThen(callable $op): self;
```

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

### unwrapOrElse() method implementation

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/none.md

Invokes the provided callable exactly once and returns its result as the fallback value.

```php
public function unwrapOrElse(callable $op)
{
    return $op();
}
```

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

### isNone(): bool

Source: https://github.com/prewk/option/blob/master/_autodocs/api-reference/some.md

Checks if the option is a None variant. Always returns false for a Some instance.

```APIDOC
## isNone(): bool

### Description
Checks if the option is a None variant. Always returns false for a Some instance.

### Method
isNone

### Signature
```php
public function isNone(): bool
```

### Parameters
None

### Return Value
- `bool` - Always `false`.

### Example
```php
if ((new Some('foo'))->isNone()) { /* no */ }
```
```
Tokens:
Raw