Optional
A port of Java 9's java.util.Optional improved for PHP.
Some examples
Basic usage
Example request class:
class Request
{
private $date;
// ... constructor and getter ...
}
Example code of optional:
$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:
$request = new Request('1992-10-07');
Program will output 1992-10-07
.
If a null is specified in request:
$request = new Request(null);
Then program will output the default value, which in this case would be something like 2016-08-19
Instead of returning a default value we could just throw an exception in case no value:
$date = Optional::ofNullable($request->getDate())
->map(function ($dateString) {
return DateTime::createFromFormat('Y-m-d', $dateString);
})
->orElseThrow(new \Exception());
In case of:
$request = new Request(null);
Program will throw the specified exception, otherwise, will return specified parsed date.
or
We can chain Optionality:
$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:
$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:
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
With: $request = new Request('2030-01-01');
would output: 2030-01-01
With: $request = new Request(null);
would output: 2016-08-19
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.
ifPresentOrElse
Similar to ifPresent but with an else callback if optional is empty
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
Comparable
Returns true:
Optional::of('something')->equals(Optional::of('something'));
Returns false:
Optional::of(5)->equals(Optional::of('something'));
Returns true:
Optional::empty()->equals(Optional::empty());
Returns false:
Optional::empty()->equals(Optional::of(5));
__toString
echo (string) Optional::of('something');
Outputs: Optional[something]
echo (string) Optional::empty();
Outputs: Optional.empty