jjware/option

PHP Option sum type

Option

, _(*1)

Option sum type for PHP, _(*2)

Getting Started

composer require jjware/option

Creation

The Option class resides in namespace JJWare\Utils\Option, _(*3)

You can create an Option simply by calling the static some method:, _(*4)

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

If you have a variable that may contain a null value, you may use the nullable static method:, _(*5)

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

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

$opt = Option::none();

Usage

Once you have an Option, there are many operations you can perform against it., _(*7)

Let's say we have a function that may or may not return a value:, _(*8)

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:, _(*9)

$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:, _(*10)

$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:, _(*11)

$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:, _(*12)

$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:, _(*13)

$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:, _(*14)

$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:, _(*15)

$port = getSetting('port');

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