feat(option): new Option::apply() method (#426)

* feat(option): new `Option::apply()` method

* Add unit tests

* Requested changes

* Verify in unit test that a `None` option remains the same after calling `apply`

* Rewrote test with `$actual`

* Check that returned Option from `apply` is actually the same instance and value

* Fix coding standards

src/Psl/Option/Option.php

@@ -227,6 +227,22 @@ public function proceed(Closure $some, Closure $none): mixed
         return $none();
     }
 
+    /**
+     * Applies a function to a contained value and returns the original `Option<T>`.
+     *
+     * @param (Closure(T): void) $closure
+     *
+     * @return Option<T>
+     */
+    public function apply(Closure $closure): Option
+    {
+        if ($this->option !== null) {
+            $closure($this->option[0]);
+        }
+
+        return $this;
+    }
+
     /**
      * Maps an `Option<T>` to `Option<Tu>` by applying a function to a contained value.
      *

tests/unit/Option/NoneTest.php

@@ -10,6 +10,7 @@
 use Psl\Comparison\Order;
 use Psl\Option;
 use Psl\Option\Exception\NoneException;
+use Psl\Ref;
 use Psl\Str;
 
 final class NoneTest extends TestCase
@@ -95,6 +96,19 @@ public function testProceed(): void
         static::assertSame('There is no value', $result);
     }
 
+    public function testApply(): void
+    {
+        $spy = new Ref(1);
+
+        $option = Option\none();
+        $actual = $option->apply(static function (int $value) use ($spy) {
+            $spy->value += $value;
+        });
+
+        static::assertSame(1, $spy->value);
+        static::assertSame($option, $actual);
+    }
+
     public function testMap(): void
     {
         $option = Option\none();

tests/unit/Option/SomeTest.php

@@ -9,6 +9,7 @@
 use Psl\Comparison\Equable;
 use Psl\Comparison\Order;
 use Psl\Option;
+use Psl\Ref;
 use Psl\Str;
 use Psl\Tests\Fixture;
 use Psl\Type;
@@ -94,6 +95,19 @@ public function testProceed(): void
         static::assertSame('Value is 1', $result);
     }
 
+    public function testApply(): void
+    {
+        $spy = new Ref(1);
+
+        $option = Option\some(2);
+        $actual = $option->apply(static function (int $value) use ($spy) {
+            $spy->value += $value;
+        });
+
+        static::assertSame(3, $spy->value);
+        static::assertSame($actual, $option);
+    }
+
     public function testMap(): void
     {
         $option = Option\some(2);