Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 14 additions & 7 deletions .github/workflows/java-test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,21 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
directory:
- tests/JavaSe8
- tests/JavaSe9
include:
- se: 8
lts: 8
- se: 9
lts: 11
- se: 10
lts: 11
- se: 16
lts: 17
name: Java SE ${{ matrix.se }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
- uses: actions/setup-java@v5
with:
java-version: 21
java-version: ${{ matrix.lts }}
distribution: corretto
- run: javac ${{ matrix.directory }}/OptionalTest.java
- run: java -cp ${{ matrix.directory }} OptionalTest
- run: javac tests/JavaSe${{ matrix.se }}/OptionalTest.java
- run: java -ea -cp tests/JavaSe${{ matrix.se }} OptionalTest
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Optional (like in Java Platform SE 8/9 but in PHP)
# Optional (like in Java Platform SE but in PHP)

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

Expand All @@ -15,6 +15,8 @@ This library delivers complete and reliable behavior of the `Optional`.
The **entire feature set is explicitly described and checked** by:
- [`JavaSe8/OptionalTest.java`](./tests/JavaSe8/OptionalTest.java)
- [`JavaSe9/OptionalTest.java`](./tests/JavaSe9/OptionalTest.java)
- [`JavaSe10/OptionalTest.java`](./tests/JavaSe10/OptionalTest.java)
- [`JavaSe16/OptionalTest.java`](./tests/JavaSe16/OptionalTest.java)

This ensures absolute reliability and alignment with the Java specification.

Expand Down
32 changes: 32 additions & 0 deletions src/JavaSe10/Optional.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<?php

declare(strict_types=1);

namespace PetrKnap\Optional\JavaSe10;

use PetrKnap\Optional\JavaSe8;
use PetrKnap\Optional\JavaSe9;
use Throwable;

/**
* A container object which may or may not contain a non-null value.
*
* @template-covariant T of mixed type of non-null value
*
* @see https://docs.oracle.com/javase/10/docs/api/java/util/Optional.html
*
* @extends JavaSe9\Optional<T>
*/
interface Optional extends JavaSe9\Optional
{
/**
* @template E of Throwable
*
* @param null|callable(): E $exceptionSupplier
*
* @return T
*
* @throws ($exceptionSupplier is null ? JavaSe8\NoSuchElementException : E)
*/
public function orElseThrow(?callable $exceptionSupplier = null): mixed;
}
4 changes: 2 additions & 2 deletions src/Optional.php
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@
/**
* @template-covariant T of mixed type of non-null value
*
* @implements JavaSe9\Optional<T>
* @implements JavaSe10\Optional<T>
*/
abstract class Optional implements JavaSe9\Optional
abstract class Optional implements JavaSe10\Optional
{
/**
* @param T|null $value
Expand Down
19 changes: 19 additions & 0 deletions tests/JavaSe10/OptionalTest.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
import java.util.NoSuchElementException;
import java.util.Optional;

/**
* @note `assert`s are written as `assert (...)` to simplify translate to PHP
* @note variable names are prefixed by `$` to simplify translate to PHP
*/
public class OptionalTest {
public static void main(String[] args) {
testOrElseThrow();
}

private static void testOrElseThrow() {
// present option returns value
assert (Optional.of(1).orElseThrow() == 1);
// empty option throws default exception
try { Optional.empty().orElseThrow(); } catch (NoSuchElementException $e) { assert (true); }
}
}
19 changes: 19 additions & 0 deletions tests/JavaSe10/OptionalTestCase.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<?php

declare(strict_types=1);

namespace PetrKnap\Optional\JavaSe10;

use PetrKnap\Optional\JavaSe9;

abstract class OptionalTestCase extends JavaSe9\OptionalTestCase
{
#[\Override]
protected static function getJavaLines(): array
{
return array_merge(
parent::getJavaLines(),
self::loadJavaLines(__DIR__ . '/OptionalTest.java'),
);
}
}
24 changes: 24 additions & 0 deletions tests/JavaSe16/OptionalTest.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
import java.util.Optional;

/**
* @note `assert`s are written as `assert (...)` to simplify translate to PHP
* @note variable names are prefixed by `$` to simplify translate to PHP
*/
public class OptionalTest {
public static void main(String[] args) {
testEquals();
}

private static void testEquals() {
Record $record;
// same record instance
$record = new Record(1); assert (Optional.of($record).equals(Optional.of($record)) == true);
// two equal record instances
assert (Optional.of(new Record(1)).equals(Optional.of(new Record(1))) == true);
// two different record instances
assert (Optional.of(new Record(1)).equals(Optional.of(new Record(2))) == false);
}

private static record Record(int value) {
}
}
31 changes: 31 additions & 0 deletions tests/JavaSe16/OptionalTestCase.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<?php

declare(strict_types=1);

namespace PetrKnap\Optional\JavaSe16;

use PetrKnap\Optional\JavaSe10;
use stdClass;

abstract class OptionalTestCase extends JavaSe10\OptionalTestCase
{
#[\Override]
protected static function getJavaLines(): array
{
return array_merge(
parent::getJavaLines(),
self::loadJavaLines(__DIR__ . '/OptionalTest.java'),
);
}

#[\Override]
protected static function getJava2PhpTranslations(): array
{
return array_merge(
parent::getJava2PhpTranslations(),
[
'Record' => '\\' . Record::class,
],
);
}
}
13 changes: 13 additions & 0 deletions tests/JavaSe16/Record.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<?php

declare(strict_types=1);

namespace PetrKnap\Optional\JavaSe16;

final class Record
{
public function __construct(
public int $value,
) {
}
}
8 changes: 1 addition & 7 deletions tests/JavaSe8/OptionalTest.java
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,6 @@ private static void testEquals() {
assert (Optional.of(1).equals(1) == false);
assert (Optional.of(1).equals(Optional.of(2)) == false);
assert (Optional.of(1).equals(Optional.empty()) == false);
// two records
assert (Optional.of(new Record()).equals(Optional.of(new Record())) == true);
// two empties
assert (Optional.<Integer>empty().equals(Optional.<Alternative>empty()) == true);
// wrong type
Expand Down Expand Up @@ -57,13 +55,12 @@ private static void testGetters() {
assert (Optional.of(1).get() == 1);
assert (Optional.of(1).orElse(2) == 1);
assert (Optional.of(1).orElseGet(() -> 2) == 1);
assert (Optional.of(1).orElseThrow() == 1);
assert (Optional.of(1).orElseThrow(() -> new AlternativeException()) == 1);
// empty option returns fallback
assert (Optional.<Integer>empty().orElse(1) == 1);
assert (Optional.<Integer>empty().orElseGet(() -> 1) == 1);
// empty option throws
try { Optional.empty().get(); } catch (NoSuchElementException $e) { assert (true); }
try { Optional.empty().orElseThrow(); } catch (NoSuchElementException $e) { assert (true); }
try { Optional.empty().orElseThrow(() -> new AlternativeException()); } catch (AlternativeException $e) { assert (true); }
// fallback can be null
assert (Optional.empty().orElse(null) == null);
Expand Down Expand Up @@ -94,9 +91,6 @@ private static void testMap() {
Optional.empty().map($v -> { assert (false); return null; });
}

private static record Record() {
}

private static class Alternative {
}

Expand Down
37 changes: 19 additions & 18 deletions tests/JavaSe8/OptionalTestCase.php
Original file line number Diff line number Diff line change
Expand Up @@ -6,46 +6,30 @@

use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;
use stdClass;

abstract class OptionalTestCase extends TestCase
{
#[DataProvider('dataMatchesJavaBehavior')]
final public function testMatchesJavaBehavior(string $assert): void
{
if (str_contains($assert, 'assertTrue(false)')) {
if (str_contains($assert, '::assertTrue(false)')) {
self::expectNotToPerformAssertions();
}

eval($assert);

Check notice on line 19 in tests/JavaSe8/OptionalTestCase.php

View workflow job for this annotation

GitHub Actions / run

* [Eval] Use of eval() is discouraged
}

final public static function dataMatchesJavaBehavior(): iterable

Check notice on line 22 in tests/JavaSe8/OptionalTestCase.php

View workflow job for this annotation

GitHub Actions / run

* [Return type hint] Method \PetrKnap\Optional\JavaSe8\OptionalTestCase::dataMatchesJavaBehavior() does not have @return annotation for its traversable return value.
{
$headers = 'namespace ' . __NAMESPACE__ . ';';
foreach (static::getJavaLines() as $javaLine) {
if (!str_starts_with($javaLine, '*') && str_contains($javaLine, 'assert (')) {

Check notice on line 26 in tests/JavaSe8/OptionalTestCase.php

View workflow job for this annotation

GitHub Actions / run

* [Line length] Line exceeds 80 characters; contains 90 characters * [Space after not] Expected 1 space after NOT operator; 0 found
yield $javaLine => [$headers . strtr($javaLine, [
'assert (' => '\\' . self::class . '::assertTrue(',
'Optional.<Alternative>' => 'AlternativeOption::',
'Optional.' => '\\' . static::getClassName() . '::',
'Record' => '\\' . stdClass::class,
'<Integer>' => '',
'.' => '->',
' == ' => ' === ',
' != ' => ' !== ',
'$v -> { }' => 'fn ($v) => null',
'$v -> {' => 'function ($v) { return ',
'$v -> ' => 'fn ($v) => ',
'() -> { }' => 'fn () => null',
'() -> {' => 'function () { return ',
'() -> ' => 'fn () => ',
])];
yield $javaLine => [$headers . strtr($javaLine, static::getJava2PhpTranslations())];

Check notice on line 27 in tests/JavaSe8/OptionalTestCase.php

View workflow job for this annotation

GitHub Actions / run

* [Line length] Line exceeds 80 characters; contains 100 characters
}
}
}

final protected static function loadJavaLines(string $path): array

Check notice on line 32 in tests/JavaSe8/OptionalTestCase.php

View workflow job for this annotation

GitHub Actions / run

* [Return type hint] Method \PetrKnap\Optional\JavaSe8\OptionalTestCase::loadJavaLines() does not have @return annotation for its traversable return value.
{
return array_map(
trim(...),
Expand All @@ -53,11 +37,28 @@
);
}

protected static function getJavaLines(): array

Check notice on line 40 in tests/JavaSe8/OptionalTestCase.php

View workflow job for this annotation

GitHub Actions / run

* [Return type hint] Method \PetrKnap\Optional\JavaSe8\OptionalTestCase::getJavaLines() does not have @return annotation for its traversable return value.
{
return self::loadJavaLines(__DIR__ . '/OptionalTest.java');
}

protected static function getJava2PhpTranslations(): array

Check notice on line 45 in tests/JavaSe8/OptionalTestCase.php

View workflow job for this annotation

GitHub Actions / run

* [Return type hint] Method \PetrKnap\Optional\JavaSe8\OptionalTestCase::getJava2PhpTranslations() does not have @return annotation for its traversable return value.
{
return [
'assert (' => '\\' . self::class . '::assertTrue(',
'Optional.<Alternative>' => '\\' . AlternativeOption::class . '::',
'Optional.' => '\\' . static::getClassName() . '::',
'<Integer>' => '',
'.' => '->',
' == ' => ' === ',
' != ' => ' !== ',
'$v -> {' => 'function ($v) { return ',
'$v -> ' => 'fn ($v) => ',
'() -> {' => 'function () { return ',
'() -> ' => 'fn () => ',
];
}

/**
* @return class-string<Optional>
*/
Expand Down
1 change: 0 additions & 1 deletion tests/JavaSe9/OptionalTest.java
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import java.util.NoSuchElementException;
import java.util.Optional;

/**
Expand Down
12 changes: 12 additions & 0 deletions tests/JavaSe9/OptionalTestCase.php
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,16 @@ protected static function getJavaLines(): array
self::loadJavaLines(__DIR__ . '/OptionalTest.java'),
);
}

#[\Override]
protected static function getJava2PhpTranslations(): array
{
return array_merge(
parent::getJava2PhpTranslations(),
[
'$v -> { }' => 'fn ($v) => null',
'() -> { }' => 'fn () => null',
],
);
}
}
2 changes: 1 addition & 1 deletion tests/OptionalTestCase.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
use InvalidArgumentException;
use PHPUnit\Framework\Attributes\DataProvider;

abstract class OptionalTestCase extends JavaSe9\OptionalTestCase
abstract class OptionalTestCase extends JavaSe16\OptionalTestCase
{
final public static function dataOptions(): array
{
Expand Down
Loading