README

Option sum type for PHP

Getting Started

composer require jjware/option

Creation

The Option class resides in namespace JJWare\Utils\Option

You can create an Option simply by calling the static some method:

$opt = Option::some('example value');

If you have a variable that may contain a null value, you may use the nullable static method:

$opt = Option::nullable($value);

If you have a case where you need to return an empty value, you may use the none static method:

$opt = Option::none();

Usage

Once you have an Option, there are many operations you can perform against it.

Let's say we have a function that may or may not return a value:

function getSetting(string $setting) : Option
{
    // Try to find the setting if it exists...
    return Option::nullable($result);
}

You may provide a default value in the case that your Option is empty:

$port = getSetting('port')->getOrElse(8080);

If your default value requires expensive calculation or calls to external resources, you may only want to get the default value when necessary:

$port = getSetting('port')->getOrElseGet(function () use ($db) {
    return $db->getDefaultPortFromDatabase();
});

// or using an instance method reference

$port = getSetting('port')->getOrElseGet([$db, 'getDefaultPortFromDatabase']);

The absence of a value may be an exceptional case for you:

$port = getSetting('port')->getOrThrow(function () {
   return new UnderflowException("setting does not exist");
});

You may need to change the value within the Option in some way if it exists:

$port = getSetting('port')->map(function ($x) {
   return intval($x);
})->getOrElse(8080);

// or using a function reference

$port = getSetting('port')->map('intval')->getOrElse(8080);

You may have a need to map to an entirely different Option:

$scheme = getSetting('port')->flatMap(function ($x) {
   return getSchemeForPort($x);
})->getOrElse('http');

// or as a function reference

$scheme = getSetting('port')->flatMap('getSchemeForPort')->getOrElse('http');

You may not want the value unless it meets specific criteria:

$port = getSetting('port')->filter(function ($x) {
    return $x >= 1024 && $x <= 49151;
})->getOrElse(8080);

// or using a static method reference

$port = getSetting('port')->filter('Filters::registeredPort')->getOrElse(8080);

Let's say you have a need to test for the presence of a value:

$port = getSetting('port');

if (!$port->isSome()) {
    $log->debug("port setting empty");
    throw new InvalidArgumentException("port not provided");
}