petrknap / optional

v4.0.0-rc1 2026-10-24 08:46 UTC

Requires

• php: >=8.1

Requires (Dev)

• nunomaduro/phpinsights: ^2.11
• petrknap/shorts: ^3.3
• phpstan/phpstan: ^1.12
• phpunit/phpunit: ^10.5
• squizlabs/php_codesniffer: ^3.7

LGPL-3.0-or-later

• type
• datatype
• optional

Published on Packagist.org on 2026-10-24 08:52 UTC

README

It is an easy way to make sure that everyone has to check if they have (not) received a value.

A container object which may or may not contain a non-null value. If a value is present, isPresent() will return true and get() will return the value.

Additional methods that depend on the presence or absence of a contained value are provided, such as orElse() (return a default value if value not present) and ifPresent() (execute a block of code if the value is present).

This is a value-based class; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of Optional may have unpredictable results and should be avoided.

-- Optional (Java Platform SE 8)

This library delivers complete and reliable behavior of the Optional. The entire feature set is explicitly described and checked by:

• JavaSe8/OptionalTest.java
• JavaSe9/OptionalTest.java

This ensures absolute reliability and alignment with the Java specification.

Basic usage

use PetrKnap\Optional\Optional;

$stringOption = Optional::of('data');
if ($stringOption->isPresent()) {
    echo $stringOption->get();
}

Optional::ofFalsable(tmpfile())->ifPresent(function ($tmpFile): void {
    fwrite($tmpFile, 'data');
    fclose($tmpFile);
}, else: fn () => print('tmpfile() failed'));

Creating your own optional

This library provides OptionalOverrides trait to help you implement your own wrapper with full static analysis support (see Some\Optional class):

use PetrKnap\Optional\Optional;
use PetrKnap\Optional\OptionalOverrides;

/**
 * @template-covariant T of mixed type of non-null value
 *
 * @extends Optional<T>
 */
final class MyOptional extends Optional
{
   /** @use OptionalOverrides<T> */
   use OptionalOverrides;
}

⚠ SILENT BREAKING CHANGE ⚠

Optional::equals() Behavior Alignment

The equals() method has been refactored to align strictly with Optional specification.

1. Comparing two empty Optionals now evaluates to true. Comparing any two empty Optional instances evaluates to true, regardless of their underlying type.

   Optional<String> emptyOptStr = Optional.empty();
   Optional<Array> emptyOptArr = Optional.empty();
   emptyOptStr.equals(emptyOptArr); // true

2. Comparing an Optional against a raw value now evaluates to false. Passing non-optional values directly into equals() will immediately evaluate to false.

   Optional.of("").equals(""); // false

Run composer require petrknap/optional to install it. You can support this project via donation. The project is licensed under the terms of the LGPL-3.0-or-later.