Create "Templated" rule

Because of how the validation engine works, there's no reason to keep adding templates to each rule. Instead, creating a single rule that handles templating rules will simplify the library greatly and shrink the `Rule` interface. Personally, I think this API is much more straightforward than the `setTemplate()` method, as it's way more explicit which rule is being templated.
Respect · Dec 26, 2024 · 1d1da7f · 1d1da7f
1 parent 634a155
commit 1d1da7f
Show file tree

Hide file tree

Showing 25 changed files with 234 additions and 166 deletions.
diff --git a/bin/create-mixin b/bin/create-mixin
@@ -171,17 +171,18 @@ function overwriteFile(string $content, string $basename): void
         'PropertyExists',
         'PropertyOptional',
         'Attributes',
+        'Templated',
     ];
 
     $mixins = [
         ['Key', 'key', [], $structureRelatedRules],
         ['Length', 'length', $numberRelatedRules, []],
         ['Max', 'max', $numberRelatedRules, []],
         ['Min', 'min', $numberRelatedRules, []],
-        ['Not', 'not', [], ['Not', 'NotEmpty', 'NotBlank', 'NotEmoji', 'NotUndef', 'NotOptional', 'NullOr', 'UndefOr', 'Optional', 'Attributes']],
-        ['NullOr', 'nullOr', [], ['Nullable', 'NullOr', 'Optional', 'NotOptional', 'NotUndef', 'UndefOr']],
+        ['Not', 'not', [], ['Not', 'NotEmpty', 'NotBlank', 'NotEmoji', 'NotUndef', 'NotOptional', 'NullOr', 'UndefOr', 'Optional', 'Attributes', 'Templated']],
+        ['NullOr', 'nullOr', [], ['Nullable', 'NullOr', 'Optional', 'NotOptional', 'NotUndef', 'UndefOr', 'Templated']],
         ['Property', 'property', [], $structureRelatedRules],
-        ['UndefOr', 'undefOr', [], ['Nullable', 'NullOr', 'NotOptional', 'NotUndef', 'Optional', 'UndefOr', 'Attributes']],
+        ['UndefOr', 'undefOr', [], ['Nullable', 'NullOr', 'NotOptional', 'NotUndef', 'Optional', 'UndefOr', 'Attributes', 'Templated']],
         ['', null, [], []],
     ];
 

diff --git a/docs/09-list-of-rules-by-category.md b/docs/09-list-of-rules-by-category.md
@@ -61,14 +61,21 @@
 
 - [AllOf](rules/AllOf.md)
 - [AnyOf](rules/AnyOf.md)
+- [Circuit](rules/Circuit.md)
 - [NoneOf](rules/NoneOf.md)
 - [OneOf](rules/OneOf.md)
 
 ## Conditions
 
+- [Circuit](rules/Circuit.md)
 - [Not](rules/Not.md)
 - [When](rules/When.md)
 
+## Core
+
+- [Not](rules/Not.md)
+- [Templated](rules/Templated.md)
+
 ## Date and Time
 
 - [Date](rules/Date.md)
@@ -155,12 +162,14 @@
 - [NotBlank](rules/NotBlank.md)
 - [NotEmpty](rules/NotEmpty.md)
 - [NotUndef](rules/NotUndef.md)
+- [Templated](rules/Templated.md)
 
 ## Nesting
 
 - [AllOf](rules/AllOf.md)
 - [AnyOf](rules/AnyOf.md)
 - [Call](rules/Call.md)
+- [Circuit](rules/Circuit.md)
 - [Each](rules/Each.md)
 - [Key](rules/Key.md)
 - [KeySet](rules/KeySet.md)
@@ -254,6 +263,7 @@
 - [Property](rules/Property.md)
 - [PropertyExists](rules/PropertyExists.md)
 - [PropertyOptional](rules/PropertyOptional.md)
+- [Templated](rules/Templated.md)
 
 ## Transformations
 
@@ -309,6 +319,7 @@
 - [CallableType](rules/CallableType.md)
 - [Callback](rules/Callback.md)
 - [Charset](rules/Charset.md)
+- [Circuit](rules/Circuit.md)
 - [Cnh](rules/Cnh.md)
 - [Cnpj](rules/Cnpj.md)
 - [Consonant](rules/Consonant.md)
@@ -431,6 +442,7 @@
 - [SubdivisionCode](rules/SubdivisionCode.md)
 - [Subset](rules/Subset.md)
 - [SymbolicLink](rules/SymbolicLink.md)
+- [Templated](rules/Templated.md)
 - [Time](rules/Time.md)
 - [Tld](rules/Tld.md)
 - [TrueVal](rules/TrueVal.md)

diff --git a/docs/rules/Attributes.md b/docs/rules/Attributes.md
@@ -83,3 +83,4 @@ See also:
 - [Property](Property.md)
 - [PropertyExists](PropertyExists.md)
 - [PropertyOptional](PropertyOptional.md)
+- [Templated](Templated.md)
diff --git a/docs/rules/Not.md b/docs/rules/Not.md
@@ -28,6 +28,7 @@ Each other validation has custom messages for negated rules.
 
 ## Categorization
 
+- Core
 - Conditions
 - Nesting
 
@@ -41,3 +42,4 @@ Each other validation has custom messages for negated rules.
 See also:
 
 - [NoneOf](NoneOf.md)
+- [Templated](Templated.md)
diff --git a/docs/rules/Templated.md b/docs/rules/Templated.md
@@ -0,0 +1,49 @@
+# Templated
+
+- `Templated(Rule $rule, string $template)`
+- `Templated(Rule $rule, string $template, array<string, mixed> $parameters)`
+
+Defines a rule with a custom message template.
+
+```php
+v::templated(v::email(), 'You must provide a valid email to signup')->assert('not an email');
+// Message: You must provide a valid email to signup
+
+v::templated(
+    v::notEmpty(),
+    'The author of the page {{title}} is empty, please fill it up.',
+    ['title' => 'Feature Guide']
+)->assert('');
+// Message: The author of the page "Feature Guide" is empty, please fill it up.
+```
+
+This rule can be also useful when you're using [Attributes](Attributes.md) and want a custom template for a specific property.
+
+## Templates
+
+This rule does not have any templates, as you must define the templates yourself.
+
+## Template placeholders
+
+| Placeholder | Description                                                      |
+|-------------|------------------------------------------------------------------|
+| `name`      | The validated input or the custom validator name (if specified). |
+
+
+## Categorization
+
+- Core
+- Structures
+- Miscellaneous
+
+## Changelog
+
+| Version | Description |
+|--------:|-------------|
+|   3.0.0 | Created     |
+
+***
+See also:
+
+- [Attributes](Attributes.md)
+- [Not](Not.md)
diff --git a/library/Mixins/Builder.php b/library/Mixins/Builder.php
@@ -355,6 +355,11 @@ public static function subset(array $superset): Chain;
 
     public static function symbolicLink(): Chain;
 
+    /**
+     * @param array<string, mixed> $parameters
+     */
+    public static function templated(Rule $rule, string $template, array $parameters = []): Chain;
+
     public static function time(string $format = 'H:i:s'): Chain;
 
     public static function tld(): Chain;

diff --git a/library/Mixins/Chain.php b/library/Mixins/Chain.php
@@ -360,6 +360,11 @@ public function subset(array $superset): Chain;
 
     public function symbolicLink(): Chain;
 
+    /**
+     * @param array<string, mixed> $parameters
+     */
+    public function templated(Rule $rule, string $template, array $parameters = []): Chain;
+
     public function time(string $format = 'H:i:s'): Chain;
 
     public function tld(): Chain;

diff --git a/library/Result.php b/library/Result.php
@@ -27,15 +27,13 @@ final class Result
 
     public readonly ?string $name;
 
-    public readonly string $template;
-
     /** @param array<string, mixed> $parameters */
     public function __construct(
         public readonly bool $isValid,
         public readonly mixed $input,
         public readonly Rule $rule,
         public readonly array $parameters = [],
-        string $template = Rule::TEMPLATE_STANDARD,
+        public readonly string $template = Rule::TEMPLATE_STANDARD,
         public readonly Mode $mode = Mode::DEFAULT,
         ?string $name = null,
         ?string $id = null,
@@ -44,7 +42,6 @@ public function __construct(
         Result ...$children,
     ) {
         $this->name = $rule->getName() ?? $name;
-        $this->template = $rule->getTemplate() ?? $template;
         $this->id = $id ?? lcfirst(substr((string) strrchr($rule::class, '\\'), 1));
         $this->children = $children;
     }
@@ -97,6 +94,12 @@ public function withTemplate(string $template): self
         return $this->clone(template: $template);
     }
 
+    /** @param array<string, mixed> $parameters */
+    public function withExtraParameters(array $parameters): self
+    {
+        return $this->clone(parameters: $parameters + $this->parameters);
+    }
+
     public function withId(string $id): self
     {
         if ($this->unchangeableId) {
@@ -190,11 +193,13 @@ public function allowsAdjacent(): bool
     }
 
     /**
+     * @param array<string, mixed> $parameters
      * @param array<Result>|null $children
      */
     private function clone(
         ?bool $isValid = null,
         mixed $input = null,
+        ?array $parameters = null,
         ?string $template = null,
         ?Mode $mode = null,
         ?string $name = null,
@@ -207,7 +212,7 @@ private function clone(
             $isValid ?? $this->isValid,
             $input ?? $this->input,
             $this->rule,
-            $this->parameters,
+            $parameters ?? $this->parameters,
             $template ?? $this->template,
             $mode ?? $this->mode,
             $name ?? $this->name,

diff --git a/library/Rule.php b/library/Rule.php
@@ -18,8 +18,4 @@ public function evaluate(mixed $input): Result;
     public function getName(): ?string;
 
     public function setName(string $name): static;
-
-    public function getTemplate(): ?string;
-
-    public function setTemplate(string $template): static;
 }
diff --git a/library/Rules/Core/Binder.php b/library/Rules/Core/Binder.php
@@ -26,10 +26,6 @@ public function evaluate(mixed $input): Result
             $this->bound->setName($this->source->getName());
         }
 
-        if ($this->source->getTemplate() !== null && $this->bound->getTemplate() === null) {
-            $this->bound->setTemplate($this->source->getTemplate());
-        }
-
         return $this->bound->evaluate($input);
     }
 }
diff --git a/library/Rules/Core/Composite.php b/library/Rules/Core/Composite.php
@@ -23,8 +23,6 @@ abstract class Composite implements Rule
 
     private ?string $name = null;
 
-    private ?string $template = null;
-
     public function __construct(Rule $rule1, Rule $rule2, Rule ...$rules)
     {
         $this->rules = array_merge([$rule1, $rule2], $rules);
@@ -55,16 +53,4 @@ public function getName(): ?string
     {
         return $this->name;
     }
-
-    public function setTemplate(string $template): static
-    {
-        $this->template = $template;
-
-        return $this;
-    }
-
-    public function getTemplate(): ?string
-    {
-        return $this->template;
-    }
 }
diff --git a/library/Rules/Core/Reducer.php b/library/Rules/Core/Reducer.php
@@ -11,11 +11,21 @@
 
 use Respect\Validation\Rule;
 use Respect\Validation\Rules\AllOf;
+use Respect\Validation\Rules\Templated;
 
 final class Reducer extends Wrapper
 {
     public function __construct(Rule $rule1, Rule ...$rules)
     {
         parent::__construct($rules === [] ? $rule1 : new AllOf($rule1, ...$rules));
     }
+
+    public function withTemplate(?string $template): self
+    {
+        if ($template === null) {
+            return $this;
+        }
+
+        return new self(new Templated($this->rule, $template));
+    }
 }
diff --git a/library/Rules/Core/Standard.php b/library/Rules/Core/Standard.php
@@ -18,8 +18,6 @@ abstract class Standard implements Rule
 
     private ?string $name = null;
 
-    private ?string $template = null;
-
     public function getName(): ?string
     {
         return $this->name;
@@ -31,16 +29,4 @@ public function setName(string $name): static
 
         return $this;
     }
-
-    public function getTemplate(): ?string
-    {
-        return $this->template;
-    }
-
-    public function setTemplate(string $template): static
-    {
-        $this->template = $template;
-
-        return $this;
-    }
 }
diff --git a/library/Rules/Core/Wrapper.php b/library/Rules/Core/Wrapper.php
@@ -39,18 +39,6 @@ public function setName(string $name): static
         return $this;
     }
 
-    public function getTemplate(): ?string
-    {
-        return $this->rule->getTemplate();
-    }
-
-    public function setTemplate(string $template): static
-    {
-        $this->rule->setTemplate($template);
-
-        return $this;
-    }
-
     public function getRule(): Rule
     {
         return $this->rule;

diff --git a/library/Rules/Templated.php b/library/Rules/Templated.php
@@ -0,0 +1,38 @@
+<?php
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <[email protected]>
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Validation\Rules;
+
+use Attribute;
+use Respect\Validation\Result;
+use Respect\Validation\Rule;
+use Respect\Validation\Rules\Core\Wrapper;
+
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
+final class Templated extends Wrapper
+{
+    /** @param array<string, mixed> $parameters */
+    public function __construct(
+        Rule $rule,
+        private readonly string $template,
+        private readonly array $parameters = []
+    ) {
+        parent::__construct($rule);
+    }
+
+    public function evaluate(mixed $input): Result
+    {
+        $result = $this->rule->evaluate($input);
+        if ($result->hasCustomTemplate()) {
+            return $result;
+        }
+
+        return $result->withTemplate($this->template)->withExtraParameters($this->parameters);
+    }
+}
diff --git a/library/Rules/When.php b/library/Rules/When.php
@@ -26,8 +26,7 @@ public function __construct(
         ?Rule $else = null
     ) {
         if ($else === null) {
-            $else = new AlwaysInvalid();
-            $else->setTemplate(AlwaysInvalid::TEMPLATE_SIMPLE);
+            $else = new Templated(new AlwaysInvalid(), AlwaysInvalid::TEMPLATE_SIMPLE);
         }
 
         $this->else = $else;