jimmyoak/optional

Optional

A port of Java 9's java.util.Optional improved for PHP., _(*1)

Some examples

Basic usage

Example request class:, _(*2)

class Request
{
    private $date;
    // ... constructor and getter ...
}

Example code of optional:, _(*3)

$date = Optional::ofNullable($request->getDate())
    ->map(function ($dateString) {
        return DateTime::createFromFormat('Y-m-d', $dateString);
    })
    ->orElseGet(function () {
        return new \DateTime();
    });

echo $date->format('Y-m-d');

Given this request:, _(*4)

$request = new Request('1992-10-07');

Program will output 1992-10-07., _(*5)

If a null is specified in request:, _(*6)

$request = new Request(null);

Then program will output the default value, which in this case would be something like 2016-08-19, _(*7)

Instead of returning a default value we could just throw an exception in case no value:, _(*8)

$date = Optional::ofNullable($request->getDate())
    ->map(function ($dateString) {
        return DateTime::createFromFormat('Y-m-d', $dateString);
    })
    ->orElseThrow(new \Exception());

In case of:, _(*9)

$request = new Request(null);

Program will throw the specified exception, otherwise, will return specified parsed date., _(*10)

or

We can chain Optionality:, _(*11)

$findInMemory = function () {
    ...
    return Optional::ofNullable(...);
};

$findInDisc = function () {
    ...
    return Optional::ofNullable(...);
};

$findRemotely = function () {
    ...
    return Optional::ofNullable(...);
};

$optional = $findInMemory()
    ->or($findInDisc)
    ->or($findRemotely);

Callbacks will only execute if the last optional is empty. Example:, _(*12)

$findInMemory = function () {
    echo "Searching in memory...\n";
    return Optional::empty();
};

$findInDisc = function () {
    echo "Searching in disc...\n";
    return Optional::of("Awesome");
};

$findRemotely = function () {
    echo "Searching remotely...";
    return Optional::of("Not so awesome");
};

$findInMemory()
    ->or($findInDisc)
    ->or($findRemotely)
    ->ifPresent(function ($value) {
        echo $value;
    });

Will output:, _(*13)

Searching in memory...
Searching in disc...
Awesome

filter

$request = new Request('1992-10-07');

$makeDateTime = function ($value) {
    return \DateTime::createFromFormat('Y-m-d', $value);
};

$beforeNow = function (\DateTime $date) {
    return $date->getTimestamp() > (new \DateTime())->getTimestamp();
};

$date = Optional::ofNullable($request->getDate())
    ->map($makeDateTime)
    ->filter($beforeNow)
    ->orElse(new \DateTime());

echo $date->format('Y-m-d');

Outputs (similar): 2016-08-19, _(*14)

With: $request = new Request('2030-01-01'); would output: 2030-01-01, _(*15)

With: $request = new Request(null); would output: 2016-08-19, _(*16)

ifPresent

Optional::ofNullable($request->getDate())
    ->ifPresent(function ($value) {
        echo "It's present: " . $value;
    });

If value, it would output: It's present: 1992-10-07 Otherwise would do nothing., _(*17)

ifPresentOrElse

Similar to ifPresent but with an else callback if optional is empty, _(*18)

Optional::ofNullable($request->getDate())
    ->ifPresentOrElse(function ($value) {
        echo "It's present: " . $value;
    }, function() {
        echo 'No value is present';
    });

If value, it would output: It's present: 1992-10-07 Otherwise, it would output: No value is present, _(*19)

Comparable

Returns true:, _(*20)

Optional::of('something')->equals(Optional::of('something'));

Returns false:, _(*21)

Optional::of(5)->equals(Optional::of('something'));

Returns true:, _(*22)

Optional::empty()->equals(Optional::empty());

Returns false:, _(*23)

Optional::empty()->equals(Optional::of(5));

__toString

echo (string) Optional::of('something');

Outputs: Optional[something], _(*24)

echo (string) Optional::empty();

Outputs: Optional.empty, _(*25)