yceruto/option-type

An Option type that represents an optional value

v1.0.6 2024-08-05 01:20 UTC

Requires

• php: >=8.2

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.54
• phpstan/phpstan: ^1.11
• phpunit/phpunit: ^11.1

MIT

• Yonel Ceruto

README

The Option type represents a value that might or might not be there. It's all about null safety in PHP!

Note

Inspired by Rust's Option type and other languages like Scala, Swift, F#, etc.

Installation

composer require yceruto/option-type

Handling the presence or absence of a value with null

In PHP, denoting the absence of a value is done with null, e.g. when a divide function returns null if the divisor is 0.

function divide(int $dividend, int $divisor): ?int
{
    if (0 === $divisor) {
        return null;
    }

    return intdiv($dividend, $divisor);
}

function success(int $result): string {
    return sprintf('Result: %d', $result);
}

$result = divide(10, 2);

echo success($result);

Can you spot the issue in this code? Apparently, everything is fine until you try to divide by zero. The function will return null, and the success() function will throw a TypeError because it expects an int value, not null.

The issue with this approach is that it's too easy to overlook checking if the value is null, leading to runtime errors, and this is where the Option type comes in handy: it always forces you to deal with the null case.

Handling the presence or absence of a value with Option

Options often work with pattern matching to check if there’s a value and act accordingly, always making sure to handle the null case.

use Std\Type\Option;
use function Std\Type\Option\none;
use function Std\Type\Option\some;

/**
 * @return Option<int>
 */
function divide(int $dividend, int $divisor): Option
{
    if (0 === $divisor) {
        return none();
    }

    return some(intdiv($dividend, $divisor));
}

function success(int $result): string {
    return sprintf('Result: %d', $result);
}

// The return value of the function is an Option
$result = divide(10, 2);

// Pattern match to retrieve the value
echo $result->match(
    // The division was valid
    some: fn (int $v) => success($v),
    // The division was invalid
    none: fn () => 'Division by zero!',
);

Tip

You can use the functions some() and none() as quick ways to create an Option instance. some() is just like new Some(), meaning it includes a value, while none() is the same as new None(), indicating it is missing a value.

Documentation

• API Reference
• Examples

License

This software is published under the MIT License