Merge pull request #5 from Innmind/shape-improvements

Add `Shape::rename()` and `Shape::default()`

Author: Baptouuuu

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- `Shape::rename()` to rename a key in the output array
+- `Shape::default()` to specify a default value when an optional key is not set
+
 ## 1.5.0 - 2024-11-10
 
 ### Added

docs/constraints/array-shapes.md

@@ -38,3 +38,32 @@ The optional key will only be present in the output value if it was set in the i
 
 ??? tip
     If you want to build a shape with a single optional key you can do `#!php Is::shape('key', Is::string())->optional('key')`.
+
+If you don't want to handle the possible absence of the key in the output array you can specify a default value:
+
+```php hl_lines="6"
+use Innmind\Validation\Is;
+
+$validate = Is::shape('username', Is::string())
+    ->with('password', Is::string())
+    ->optional('keep-logged-in', Is::string())
+    ->default('keep-logged-in', 'false');
+```
+
+## Rename a key
+
+This is useful when the output value no longer matches the input key name.
+
+For example you have a shape containing a list of integers but you want the highest one:
+
+```php
+use Innmind\Validation\Is;
+
+$validate = Is::shape(
+    'versions',
+    Is::list(Is::int())
+        ->map(\max(...)),
+)->rename('versions', 'highest');
+```
+
+Now the output type is `array{highest: int}`.

proofs/shape.php

@@ -134,6 +134,28 @@ static function($assert) {
         },
     );
 
+    yield proof(
+        'Shape with optional key default',
+        given(Set\Type::any()),
+        static function($assert, $default) {
+            $assert->same(
+                [
+                    'foo' => 42,
+                    'bar' => $default,
+                ],
+                Shape::of('foo', Is::int())
+                    ->optional('bar', Is::bool())
+                    ->default('bar', $default)([
+                        'foo' => 42,
+                    ])
+                    ->match(
+                        static fn($value) => $value,
+                        static fn() => null,
+                    ),
+            );
+        },
+    );
+
     yield test(
         'Shape with optional key with constraint directly specified',
         static function($assert) {
@@ -207,4 +229,24 @@ static function($assert, $value) {
             );
         },
     );
+
+    yield test(
+        'Shape rename key',
+        static function($assert) {
+            $assert->same(
+                [
+                    'bar' => 42,
+                ],
+                Shape::of('foo', Is::int())
+                    ->rename('foo', 'bar')([
+                        'foo' => 42,
+                        'bar' => true,
+                    ])
+                    ->match(
+                        static fn($value) => $value,
+                        static fn() => null,
+                    ),
+            );
+        },
+    );
 };

src/Shape.php

@@ -18,21 +18,31 @@ final class Shape implements Constraint
     private array $constraints;
     /** @var list<non-empty-string> */
     private array $optional;
+    /** @var array<non-empty-string, mixed> */
+    private array $defaults;
+    /** @var array<non-empty-string, non-empty-string> */
+    private array $rename;
     /** @var ?callable(non-empty-string): non-empty-string */
     private $message;
 
     /**
      * @param non-empty-array<non-empty-string, Constraint<mixed, mixed>> $constraints
      * @param list<non-empty-string> $optional
+     * @param array<non-empty-string, mixed> $defaults
+     * @param array<non-empty-string, non-empty-string> $rename
      * @param ?callable(non-empty-string): non-empty-string $message
      */
     private function __construct(
         array $constraints,
         array $optional,
-        ?callable $message = null,
+        array $defaults,
+        array $rename,
+        ?callable $message,
     ) {
         $this->constraints = $constraints;
         $this->optional = $optional;
+        $this->defaults = $defaults;
+        $this->rename = $rename;
         $this->message = $message;
     }
 
@@ -48,7 +58,13 @@ public function __invoke(mixed $value): Validation
      */
     public static function of(string $key, Constraint $constraint): self
     {
-        return new self([$key => $constraint], []);
+        return new self(
+            [$key => $constraint],
+            [],
+            [],
+            [],
+            null,
+        );
     }
 
     /**
@@ -59,7 +75,13 @@ public function with(string $key, Constraint $constraint): self
         $constraints = $this->constraints;
         $constraints[$key] = $constraint;
 
-        return new self($constraints, $this->optional, $this->message);
+        return new self(
+            $constraints,
+            $this->optional,
+            $this->defaults,
+            $this->rename,
+            $this->message,
+        );
     }
 
     /**
@@ -75,15 +97,67 @@ public function optional(string $key, Constraint $constraint = null): self
             $constraints[$key] = $constraint;
         }
 
-        return new self($constraints, $optional, $this->message);
+        return new self(
+            $constraints,
+            $optional,
+            $this->defaults,
+            $this->rename,
+            $this->message,
+        );
+    }
+
+    /**
+     * @param non-empty-string $key
+     */
+    public function default(string $key, mixed $value): self
+    {
+        if (!\in_array($key, $this->optional, true)) {
+            throw new \LogicException("No optional key $key defined");
+        }
+
+        $defaults = $this->defaults;
+        /** @psalm-suppress MixedAssignment */
+        $defaults[$key] = $value;
+
+        return new self(
+            $this->constraints,
+            $this->optional,
+            $defaults,
+            $this->rename,
+            $this->message,
+        );
+    }
+
+    /**
+     * @param non-empty-string $from
+     * @param non-empty-string $to
+     */
+    public function rename(string $from, string $to): self
+    {
+        $rename = $this->rename;
+        $rename[$from] = $to;
+
+        return new self(
+            $this->constraints,
+            $this->optional,
+            $this->defaults,
+            $rename,
+            $this->message,
+        );
     }
 
     /**
      * @param callable(non-empty-string): non-empty-string $message
      */
     public function withKeyFailure(callable $message): self
     {
-        return new self($this->constraints, $this->optional, $message);
+        return new self(
+            $this->constraints,
+            $this->optional,
+            $this->defaults,
+            $this->rename,
+            $message,
+        );
     }
 
     public function and(Constraint $constraint): Constraint
@@ -140,10 +214,15 @@ private function validate(array $value): Validation
 
             $validation = $validation->and(
                 $keyValidation->and($ofType)($value),
-                static function($array, $value) use ($key, $optional) {
+                function($array, $value) use ($key, $optional) {
+                    $concreteKey = $this->rename[$key] ?? $key;
+
                     if ($value !== $optional) {
                         /** @psalm-suppress MixedAssignment */
-                        $array[$key] = $value;
+                        $array[$concreteKey] = $value;
+                    } else if (\array_key_exists($key, $this->defaults)) {
+                        /** @psalm-suppress MixedAssignment */
+                        $array[$concreteKey] = $this->defaults[$key];
                     }
 
                     return $array;