feat(validation)!: add ability to specify translation keys for specific properties (#1618)

Author: innocenzi

docs/2-features/03-validation.md

@@ -125,7 +125,7 @@ use Tempest\Support\Arr;
 $failures = $this->validator->validateValue('[email protected]', new Email());
 
 // Map failures to their message
-$errors = Arr\map($failures, fn (Rule $failure) => $this->validator->getErrorMessage($failure));
+$errors = Arr\map($failures, fn (FailingRule $failure) => $this->validator->getErrorMessage($failure));
 ```
 
 You may also specify the field name of the validation failure to get a localized message for that field.
@@ -145,3 +145,17 @@ validation_error:
     .input {$field :string}
     {$field} must be a valid email address.
 ```
+
+Sometimes though, you may want to have a specific error message for a rule, without overriding the default translation message for that rule.
+
+This can be done by using the {b`#[Tempest\Validation\TranslationKey]`} attribute on the property being validated. For instance, you may have the following object:
+
+```php
+final class Book {
+    #[Rules\HasLength(min: 5, max: 50)]
+    #[TranslationKey('book_management.book_title')]
+    public string $title;
+}
+```
+
+When this rule fails, the `getErrorMessage()` method from the validator will use `validation_error.has_length.book_management.book_title` as the translation key, instead of `validation_error.has_length`.

packages/http/src/Responses/Invalid.php

@@ -12,6 +12,7 @@
 use Tempest\Http\Status;
 use Tempest\Reflection\ClassReflector;
 use Tempest\Support\Json;
+use Tempest\Validation\FailingRule;
 use Tempest\Validation\Rule;
 use Tempest\Validation\Validator;
 
@@ -31,7 +32,7 @@ final class Invalid implements Response
      */
     public function __construct(
         Request $request,
-        /** @var \Tempest\Validation\Rule[][] $failingRules */
+        /** @var \Tempest\Validation\FailingRule[][] $failingRules */
         array $failingRules = [],
         ?string $targetClass = null,
     ) {
@@ -49,7 +50,7 @@ public function __construct(
             Json\encode(
                 arr($failingRules)->map(
                     fn (array $failingRulesForField) => arr($failingRulesForField)->map(
-                        fn (Rule $rule) => $this->validator->getErrorMessage($rule),
+                        fn (FailingRule $rule) => $this->validator->getErrorMessage($rule),
                     )->toArray(),
                 )->toArray(),
             ),

packages/validation/src/Exceptions/PropertyValidationFailed.php

@@ -5,22 +5,22 @@
 namespace Tempest\Validation\Exceptions;
 
 use Exception;
-use Tempest\Validation\Rule;
+use Tempest\Validation\FailingRule;
 
 final class ValidationFailed extends Exception
 {
     /**
      * @template TKey of array-key
      *
-     * @param array<TKey,Rule[]> $failingRules
+     * @param array<TKey,FailingRule[]> $failingRules
      * @param array<TKey,string> $errorMessages
      * @param class-string|null $targetClass
      */
     public function __construct(
-        public readonly array $failingRules,
-        public readonly null|object|string $subject = null,
-        public readonly array $errorMessages = [],
-        public readonly ?string $targetClass = null,
+        private(set) array $failingRules,
+        private(set) null|object|string $subject = null,
+        private(set) array $errorMessages = [],
+        private(set) ?string $targetClass = null,
     ) {
         parent::__construct(match (true) {
             is_null($subject) => 'Validation failed.',

packages/validation/src/Exceptions/ValidationFailed.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace Tempest\Validation;
+
+/**
+ * Represents a rule that failed during validation, including context about the failure.
+ */
+final readonly class FailingRule
+{
+    /**
+     * @param Rule $rule The rule that failed validation.
+     * @param null|string $field The field name associated with the value that was validated and caused the failure.
+     * @param mixed|null $value The value that was validated and caused the failure.
+     * @param null|string $key An optional key associated with the value, used for localization.
+     */
+    public function __construct(
+        private(set) Rule $rule,
+        private(set) ?string $field = null,
+        private(set) mixed $value = null,
+        private(set) ?string $key = null,
+    ) {}
+
+    /**
+     * @param null|string $field The field name associated with the value that was validated and caused the failure.
+     */
+    public function withField(?string $field): self
+    {
+        return new self(
+            rule: $this->rule,
+            field: $field,
+            value: $this->value,
+            key: $this->key,
+        );
+    }
+
+    /**
+     * @param null|string $key An optional key associated with the value, used for localization.
+     */
+    public function withKey(?string $key): self
+    {
+        return new self(
+            rule: $this->rule,
+            field: $this->field,
+            value: $this->value,
+            key: $key,
+        );
+    }
+
+    /**
+     * @param null|mixed $value The value that was validated and caused the failure.
+     */
+    public function withValue(mixed $value): self
+    {
+        return new self(
+            rule: $this->rule,
+            field: $this->field,
+            value: $value,
+            key: $this->key,
+        );
+    }
+}

packages/validation/src/Exceptions/ValueWasInvalid.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Tempest\Validation;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class TranslationKey
+{
+    public function __construct(
+        private(set) string $key,
+    ) {}
+}

packages/validation/src/FailingRule.php

@@ -55,26 +55,26 @@ public function validateObject(object $object): void
     /**
      * Creates a {@see ValidationFailed} exception from the given rule failures, populated with error messages.
      *
-     * @param array<string,Rule[]> $failingRules
+     * @param array<string,FailingRule[]> $failingRules
      * @param class-string|null $targetClass
      */
     public function createValidationFailureException(array $failingRules, null|object|string $subject = null, ?string $targetClass = null): ValidationFailed
     {
         return new ValidationFailed(
-            $failingRules,
-            $subject,
-            Arr\map_iterable($failingRules, function (array $rules, string $field) {
-                return Arr\map_iterable($rules, fn (Rule $rule) => $this->getErrorMessage($rule, $field));
+            failingRules: $failingRules,
+            subject: $subject,
+            errorMessages: Arr\map_iterable($failingRules, function (array $rules, string $field) {
+                return Arr\map_iterable($rules, fn (FailingRule $rule) => $this->getErrorMessage($rule, $field));
             }),
-            $targetClass,
+            targetClass: $targetClass,
         );
     }
 
     /**
      * Validates the specified `$values` for the corresponding public properties on the specified `$class`, using built-in PHP types and attribute rules.
      *
      * @param ClassReflector|class-string $class
-     * @return Rule[]
+     * @return array<string,FailingRule[]>
      */
     public function validateValuesForClass(ClassReflector|string $class, ?array $values, string $prefix = ''): array
     {
@@ -125,7 +125,7 @@ class: $property->getType()->asClass(),
     /**
      * Validates `$value` against the specified `$property`, using built-in PHP types and attribute rules.
      *
-     * @return Rule[]
+     * @return FailingRule[]
      */
     public function validateValueForProperty(PropertyReflector $property, mixed $value): array
     {
@@ -148,14 +148,19 @@ public function validateValueForProperty(PropertyReflector $property, mixed $val
             $rules[] = new IsEnum(enum: $property->getType()->getName(), orNull: $property->isNullable());
         }
 
-        return $this->validateValue($value, $rules);
+        $key = $property->getAttribute(TranslationKey::class)?->key;
+
+        return Arr\map_iterable(
+            array: $this->validateValue($value, $rules),
+            map: fn (FailingRule $rule) => $rule->withKey($key),
+        );
     }
 
     /**
      * Validates the specified `$value` against the specified set of `$rules`. If a rule is a closure, it may return a string as a validation error.
      *
      * @param Rule|array<Rule|(Closure(mixed $value):string|false)>|(Closure(mixed $value):string|false) $rules
-     * @return Rule[]
+     * @return FailingRule[]
      */
     public function validateValue(mixed $value, Closure|Rule|array $rules): array
     {
@@ -169,7 +174,7 @@ public function validateValue(mixed $value, Closure|Rule|array $rules): array
             $rule = $this->convertToRule($rule, $value);
 
             if (! $rule->isValid($value)) {
-                $failingRules[] = $rule;
+                $failingRules[] = new FailingRule($rule, value: $value);
             }
         }
 
@@ -206,21 +211,18 @@ public function validateValues(iterable $values, array $rules): array
     /**
      * Gets a localized validation error message for the specified rule.
      */
-    public function getErrorMessage(Rule $rule, ?string $field = null): string
+    public function getErrorMessage(Rule|FailingRule $rule, ?string $field = null): string
     {
         if ($rule instanceof HasErrorMessage) {
             return $rule->getErrorMessage();
         }
 
-        $ruleTranslationKey = str($rule::class)
-            ->classBasename()
-            ->snake()
-            ->replaceEvery([ // those are snake case issues that we manually fix for consistency
-                'i_pv6' => 'ipv6',
-                'i_pv4' => 'ipv4',
-                'reg_ex' => 'regex',
-            ])
-            ->toString();
+        $ruleTranslationKey = $this->getTranslationKey($rule);
+
+        if ($rule instanceof FailingRule) {
+            $field ??= $rule->field;
+            $rule = $rule->rule;
+        }
 
         $variables = [
             'field' => $this->getFieldName($ruleTranslationKey, $field),
@@ -233,6 +235,30 @@ public function getErrorMessage(Rule $rule, ?string $field = null): string
         return $this->translator->translate("validation_error.{$ruleTranslationKey}", ...$variables);
     }
 
+    private function getTranslationKey(Rule|FailingRule $rule): string
+    {
+        $key = '';
+
+        if ($rule instanceof FailingRule && $rule->key) {
+            $key .= $rule->key;
+        }
+
+        if ($rule instanceof FailingRule) {
+            $rule = $rule->rule;
+        }
+
+        return str($rule::class)
+            ->classBasename()
+            ->snake()
+            ->replaceEvery([ // those are snake case issues that we manually fix for consistency
+                'i_pv6' => 'ipv6',
+                'i_pv4' => 'ipv4',
+                'reg_ex' => 'regex',
+            ])
+            ->when($key !== '', fn ($s) => $s->append('.', $key))
+            ->toString();
+    }
+
     private function getFieldName(string $key, ?string $field = null): string
     {
         $translatedField = $this->translator->translate("validation_field.{$key}");