jjware/php-optional

This package is abandoned and no longer maintained. The author suggests using the jjware/option package instead.

Library for working with optional values in PHP

v1.0.1 2017-10-25 16:28 UTC

Requires

• php: >=7.0.0

Requires (Dev)

• phpunit/phpunit: ^5.0

MIT

• Joshua Jones

• library
• optional

README

An optional structure for PHP based on the Java interface

Getting Started

composer require jjware/php-optional

Creation

The Optional class resides in namespace JJWare\Util

You can create an Optional simply by calling the static of method:

$opt = Optional::of('example value');

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

$opt = Optional::ofNullable($value);

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

$opt = Optional::empty();

Usage

Once you have an Optional, 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) : Optional
{
    // Try to find the setting if it exists...
    return Optional::ofNullable($result);
}

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

$port = getSetting('port')->orElse(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')->orElseGet(function () use ($db) {
    return $db->getDefaultPortFromDatabase();
});

// or using an instance method reference

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

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

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

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

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

// or using a function reference

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

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

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

// or as a function reference

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

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

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

// or using a static method reference

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

You may want to do something if the value is present:

getSetting('port')->ifPresent(function ($x) use ($configBuilder) {
    $configBuilder->setPort($x);
});

// or as an instance method reference

getSetting('port')->ifPresent([$configBuilder, 'setPort']);

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

$port = getSetting('port');

if ($port->isPresent()) {
    $value = $port->get();
}