Add when and unless for single-branch conditional transforms

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: phanan

composer.json

@@ -122,7 +122,9 @@
             "src/Functional/True.php",
             "src/Functional/Truthy.php",
             "src/Functional/Unique.php",
+            "src/Functional/Unless.php",
             "src/Functional/ValueToKey.php",
+            "src/Functional/When.php",
             "src/Functional/With.php",
             "src/Functional/Zip.php",
             "src/Functional/ZipAll.php"

docs/functional-php.md

@@ -935,6 +935,40 @@ Applies a callback to each element in the collection and collects the return val
 
 # Conditional functions
 
+## when()
+
+``mixed when(mixed $value, callable|mixed $if, callable $then)``
+Apply `$then` to the value if the condition is truthy, otherwise return the value unchanged. `$if` can be a callable (evaluated with the value) or a value (used directly as the condition).
+
+```php
+use function Functional\when;
+
+// With a callable condition
+when('foo', 'is_string', fn ($v) => strtoupper($v)); // 'FOO'
+when([1, 2], 'is_string', fn ($v) => strtoupper($v)); // [1, 2]
+
+// With a value condition
+when($input, $isProduction, fn ($v) => htmlspecialchars($v));
+```
+
+## unless()
+
+``mixed unless(mixed $value, callable|mixed $if, callable $then)``
+Apply `$then` to the value if the condition is falsy, otherwise return the value unchanged. The inverse of `when()`. `$if` can be a callable or a value.
+
+```php
+use function Functional\unless;
+
+// With a callable condition
+unless(null, fn ($v) => $v !== null, fn () => 'default'); // 'default'
+unless('hello', fn ($v) => $v !== null, fn () => 'default'); // 'hello'
+
+// With a value condition
+unless($input, $isProduction, fn ($v) => $v . ' [debug]');
+```
+
+_See also `if_else()`, which requires both branches._
+
 ## if_else()
 
 ``callable if_else(callable $if, callable $then, callable $else)``

src/Functional/Functional.php

@@ -493,11 +493,21 @@ final class Functional
      */
     const unique = '\Functional\unique';
 
+    /**
+     * @see \Functional\unless
+     */
+    const unless = '\Functional\unless';
+
     /**
      * @see \Functional\value_to_key
      */
     const value_to_key = '\Functional\value_to_key';
 
+    /**
+     * @see \Functional\when
+     */
+    const when = '\Functional\when';
+
     /**
      * @see \Functional\with
      */

src/Functional/Unless.php

@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * @package   Functional-php
+ * @author    Lars Strojny <lstrojny@php.net>
+ * @copyright 2011-2021 Lars Strojny
+ * @license   https://opensource.org/licenses/MIT MIT
+ * @link      https://github.com/lstrojny/functional-php
+ */
+
+namespace Functional;
+
+/**
+ * Apply $then to the value if the condition is falsy, otherwise return the value unchanged.
+ *
+ * $if can be a callable (evaluated with the value) or a value (used directly).
+ *
+ * @param mixed $value
+ * @param callable|mixed $if   the condition function or value
+ * @param callable $then function to call if condition is false
+ *
+ * @return mixed
+ * @no-named-arguments
+ */
+function unless($value, $if, callable $then)
+{
+    $condition = \is_callable($if) ? $if($value) : $if;
+
+    return $condition ? $value : $then($value);
+}

src/Functional/When.php

@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * @package   Functional-php
+ * @author    Lars Strojny <lstrojny@php.net>
+ * @copyright 2011-2021 Lars Strojny
+ * @license   https://opensource.org/licenses/MIT MIT
+ * @link      https://github.com/lstrojny/functional-php
+ */
+
+namespace Functional;
+
+/**
+ * Apply $then to the value if the condition is truthy, otherwise return the value unchanged.
+ *
+ * $if can be a callable (evaluated with the value) or a value (used directly).
+ *
+ * @param mixed $value
+ * @param callable|mixed $if   the condition function or value
+ * @param callable $then function to call if condition is true
+ *
+ * @return mixed
+ * @no-named-arguments
+ */
+function when($value, $if, callable $then)
+{
+    $condition = \is_callable($if) ? $if($value) : $if;
+
+    return $condition ? $then($value) : $value;
+}

tests/Functional/UnlessTest.php

@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * @package   Functional-php
+ * @author    Lars Strojny <lstrojny@php.net>
+ * @copyright 2011-2021 Lars Strojny
+ * @license   https://opensource.org/licenses/MIT MIT
+ * @link      https://github.com/lstrojny/functional-php
+ */
+
+namespace Functional\Tests;
+
+use function Functional\unless;
+use function Functional\equal;
+use function Functional\const_function;
+
+class UnlessTest extends AbstractTestCase
+{
+    public function testUnlessCallableConditionIsTrue(): void
+    {
+        self::assertEquals('foo', unless('foo', equal('foo'), const_function('bar')));
+    }
+
+    public function testUnlessCallableConditionIsFalse(): void
+    {
+        self::assertEquals('bar', unless('qux', equal('foo'), const_function('bar')));
+    }
+
+    public function testUnlessValueConditionIsTruthy(): void
+    {
+        self::assertEquals('anything', unless('anything', true, const_function('bar')));
+    }
+
+    public function testUnlessValueConditionIsFalsy(): void
+    {
+        self::assertEquals('bar', unless('anything', false, const_function('bar')));
+    }
+}

tests/Functional/WhenTest.php

@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * @package   Functional-php
+ * @author    Lars Strojny <lstrojny@php.net>
+ * @copyright 2011-2021 Lars Strojny
+ * @license   https://opensource.org/licenses/MIT MIT
+ * @link      https://github.com/lstrojny/functional-php
+ */
+
+namespace Functional\Tests;
+
+use function Functional\when;
+use function Functional\equal;
+use function Functional\const_function;
+
+class WhenTest extends AbstractTestCase
+{
+    public function testWhenCallableConditionIsTrue(): void
+    {
+        self::assertEquals('bar', when('foo', equal('foo'), const_function('bar')));
+    }
+
+    public function testWhenCallableConditionIsFalse(): void
+    {
+        self::assertEquals('qux', when('qux', equal('foo'), const_function('bar')));
+    }
+
+    public function testWhenValueConditionIsTruthy(): void
+    {
+        self::assertEquals('bar', when('anything', true, const_function('bar')));
+    }
+
+    public function testWhenValueConditionIsFalsy(): void
+    {
+        self::assertEquals('anything', when('anything', false, const_function('bar')));
+    }
+}