Add postal_code validator extension

axlon · axlon · commit 03ddfdc3a14f · 2025-12-29T20:10:21.000+01:00
diff --git a/README.md b/README.md
@@ -22,6 +22,7 @@ Worldwide postal code validation for Laravel, based on Google's Address Data Ser
 - [Usage](#usage)
     - [Available rules](#available-rules)
     - [Adding an error message](#adding-an-error-message)
+    - [String rules](#string-rules)
 - [Changelog](#changelog)
 - [License](#license)
 
@@ -93,10 +94,10 @@ $request->validate([
 
 ### Adding an error message
 
-To add a meaningful error message, add the following line to `resources/lang/{your language}/validation.php`:
+To add a meaningful error message, add the following line to `lang/{your language}/validation.php`:
 
 ```php
-'postal_code' => 'Your message here',
+'postal_code' => 'Your message here.',
 ```
 
 The following placeholders will be automatically filled for you:
@@ -109,6 +110,19 @@ The following placeholders will be automatically filled for you:
 
 *The `:countries` and `:examples` placeholders may be empty if no valid countries are passed.
 
+### String rules
+
+All rules provided by this package can also be used as strings. This is especially useful when validating arrays, for
+example:
+
+```php
+$request->validate([
+    'addresses.*' => 'array:country,postal_code',
+    'addresses.*.country' => '...',
+    'addresses.*.postal_code' => 'postal_code:addresses.*.country',
+]);
+```
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
diff --git a/composer.json b/composer.json
@@ -19,6 +19,7 @@
     "require": {
         "php": ">=8.1",
         "illuminate/support": "^10.0 || ^11.0 || ^12.0",
+        "illuminate/translation": "^10.0 || ^11.0 || ^12.0",
         "illuminate/validation": "^10.0 || ^11.0 || ^12.0"
     },
     "require-dev": {
@@ -50,5 +51,12 @@
             "phpstan/extension-installer": true
         },
         "sort-packages": true
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "\\Axlon\\PostalCodeValidation\\Support\\PostalCodeServiceProvider"
+            ]
+        }
     }
 }
diff --git a/src/Rules/PostalCode.php b/src/Rules/PostalCode.php
@@ -22,6 +22,13 @@ final class PostalCode implements ValidationRule, DataAwareRule
      */
     private array $data = [];
 
+    /**
+     * The resolved parameters.
+     *
+     * @var list<non-empty-string|false>|null
+     */
+    private ?array $resolvedParameters = null;
+
     /**
      * Create a new validation rule.
      *
@@ -63,24 +70,54 @@ public static function of(array|string $countries): self
     }
 
     /**
-     * Resolve the rule parameters.
+     * Get the replacements for the validation message.
+     *
+     * @return array<string, string>
+     */
+    public function replacements(): array
+    {
+        $countries = $examples = [];
+
+        foreach ($this->resolvedParameters() as $parameter) {
+            if ($parameter === false) {
+                continue;
+            }
+
+            $countries[] = $parameter;
+            $regex = $this->regexes->get($parameter);
+
+            if ($regex !== null) {
+                $examples[] = $regex->example();
+            }
+        }
+
+        return [
+            'countries' => implode(', ', $countries),
+            'examples' => implode(', ', $examples),
+        ];
+    }
+
+    /**
+     * Get the resolved parameters.
      *
      * @return list<non-empty-string|false>
      */
-    private function resolveParameters(): array
+    private function resolvedParameters(): array
     {
-        $parameters = [];
-
-        foreach ($this->parameters as $parameter) {
-            if (self::isCountryCode($parameter)) {
-                $parameters[] = $parameter;
-            } elseif (Arr::has($this->data, $parameter)) {
-                $other = Arr::get($this->data, $parameter);
-                $parameters[] = self::isCountryCode($other) ? $other : false;
+        if ($this->resolvedParameters === null) {
+            $this->resolvedParameters = [];
+
+            foreach ($this->parameters as $parameter) {
+                if (self::isCountryCode($parameter)) {
+                    $this->resolvedParameters[] = $parameter;
+                } elseif (Arr::has($this->data, $parameter)) {
+                    $other = Arr::get($this->data, $parameter);
+                    $this->resolvedParameters[] = self::isCountryCode($other) ? $other : false;
+                }
             }
         }
 
-        return $parameters;
+        return $this->resolvedParameters;
     }
 
     /**
@@ -92,6 +129,7 @@ private function resolveParameters(): array
     public function setData(array $data): self
     {
         $this->data = $data;
+        $this->resolvedParameters = null;
 
         return $this;
     }
@@ -110,35 +148,22 @@ public function validate(string $attribute, mixed $value, Closure $fail): void
             return;
         }
 
-        $examples = $countryCodes = [];
-        $parameters = $this->resolveParameters();
-
-        if ($parameters === [] && is_string($value)) {
-            return;
-        }
-
         if (is_string($value)) {
+            if (($parameters = $this->resolvedParameters()) === []) {
+                return;
+            }
+
             foreach ($parameters as $parameter) {
                 if ($parameter === false) {
                     continue;
                 }
 
-                $regex = $this->regexes->get($parameter);
-
-                if ($regex?->test($value) === true) {
+                if ($this->regexes->get($parameter)?->test($value) === true) {
                     return;
                 }
-
-                if ($regex !== null) {
-                    $countryCodes[] = $parameter;
-                    $examples[] = $regex->example();
-                }
             }
         }
 
-        $fail('validation.postal_code')->translate([
-            'countries' => implode(', ', $countryCodes),
-            'examples' => implode(', ', $examples),
-        ]);
+        $fail('validation.postal_code')->translate($this->replacements());
     }
 }
diff --git a/src/Support/PostalCodeServiceProvider.php b/src/Support/PostalCodeServiceProvider.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Axlon\PostalCodeValidation\Support;
+
+use Axlon\PostalCodeValidation\Rules\PostalCode;
+use Illuminate\Support\ServiceProvider;
+use Illuminate\Translation\PotentiallyTranslatedString;
+use Illuminate\Validation\Factory;
+use Illuminate\Validation\InvokableValidationRule;
+use Illuminate\Validation\Validator;
+
+final class PostalCodeServiceProvider extends ServiceProvider
+{
+    /**
+     * Register validation services.
+     *
+     * @return void
+     */
+    public function register(): void
+    {
+        $this->callAfterResolving('validator', static function (Factory $validator) {
+            $validator->extendDependent('postal_code', self::validatePostalCode(...));
+            $validator->replacer('postal_code', self::replacePostalCode(...));
+        });
+    }
+
+    /**
+     * Replace all place-holders for the postal_code rule.
+     *
+     * @param string $message
+     * @param string $attribute
+     * @param string $rule
+     * @param array<string> $parameters
+     * @param \Illuminate\Validation\Validator $validator
+     * @return string
+     */
+    private static function replacePostalCode(
+        string $message,
+        string $attribute,
+        string $rule,
+        array $parameters,
+        Validator $validator,
+    ): string {
+        $data = $validator->getData();
+        $replacements = PostalCode::of($parameters)->setData($data)->replacements();
+        $translator = $validator->getTranslator();
+
+        return (new PotentiallyTranslatedString($message, $translator))
+            ->translate($replacements)
+            ->toString();
+    }
+
+    /**
+     * Validate that the given value is a valid postal code.
+     *
+     * @param string $attribute
+     * @param mixed $value
+     * @param array<string> $parameters
+     * @param \Illuminate\Validation\Validator $validator
+     * @return bool
+     */
+    private static function validatePostalCode(
+        string $attribute,
+        mixed $value,
+        array $parameters,
+        Validator $validator,
+    ): bool {
+        $rule = InvokableValidationRule::make(PostalCode::of($parameters));
+        $rule->setValidator($validator);
+
+        return $rule->passes($attribute, $value);
+    }
+}
diff --git a/tests/Rules/PostalCodeTest.php b/tests/Rules/PostalCodeTest.php
@@ -92,7 +92,7 @@ public function testItFailsWhenCountryCodeFieldIsNotValid(): void
             ['value' => $this->makeRule('other')],
         );
 
-        $this->regexes->expects($this->once())->method('get')->with('AA')->willReturn(null);
+        $this->regexes->expects($this->exactly(2))->method('get')->with('AA')->willReturn(null);
 
         self::assertFalse($validator->passes());
     }
@@ -104,7 +104,7 @@ public function testItFailsWhenCountryCodeIsNotValid(): void
             ['value' => $this->makeRule('AA')],
         );
 
-        $this->regexes->expects($this->once())->method('get')->with('AA')->willReturn(null);
+        $this->regexes->expects($this->exactly(2))->method('get')->with('AA')->willReturn(null);
 
         self::assertFalse($validator->passes());
     }
@@ -116,7 +116,7 @@ public function testItFailsWhenValueDoesNotMatchCountryCode(): void
             ['value' => $this->makeRule('AA')],
         );
 
-        $this->regexes->expects($this->once())->method('get')->with('AA')->willReturn(new MatchNothing());
+        $this->regexes->expects($this->exactly(2))->method('get')->with('AA')->willReturn(new MatchNothing());
 
         self::assertFalse($validator->passes());
     }
@@ -128,7 +128,7 @@ public function testItFailsWhenValueDoesNotMatchCountryCodeField(): void
             ['value' => $this->makeRule('other')],
         );
 
-        $this->regexes->expects($this->once())->method('get')->with('AA')->willReturn(new MatchNothing());
+        $this->regexes->expects($this->exactly(2))->method('get')->with('AA')->willReturn(new MatchNothing());
 
         self::assertFalse($validator->passes());
     }
@@ -140,7 +140,7 @@ public function testItFailsWhenValueIsNotAString(): void
             ['value' => $this->makeRule('AA')],
         );
 
-        $this->regexes->expects($this->never())->method('get');
+        $this->regexes->expects($this->once())->method('get')->with('AA')->willReturn(new MatchNothing());
 
         self::assertFalse($validator->passes());
     }
@@ -242,7 +242,7 @@ public function testItReplacesCountriesInErrorMessage(): void
             ['value' => $this->makeRule('AA')],
         );
 
-        $this->regexes->expects($this->once())->method('get')->with('AA')->willReturn(new MatchNothing());
+        $this->regexes->expects($this->exactly(2))->method('get')->with('AA')->willReturn(new MatchNothing());
 
         self::assertTrue($validator->fails());
         self::assertSame(['Value should be a valid AA postal code.'], $validator->errors()->get('value'));
@@ -263,7 +263,7 @@ public function testItReplacesExamplesInErrorMessage(): void
         $regex->expects($this->once())->method('test')->willReturn(false);
         $regex->expects($this->once())->method('example')->willReturn('00000');
 
-        $this->regexes->expects($this->once())->method('get')->with('AA')->willReturn($regex);
+        $this->regexes->expects($this->exactly(2))->method('get')->with('AA')->willReturn($regex);
 
         self::assertTrue($validator->fails());
         self::assertSame(['Value should be a valid postal code such as 00000.'], $validator->errors()->get('value'));
diff --git a/tests/Support/PostalCodeServiceProviderTest.php b/tests/Support/PostalCodeServiceProviderTest.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Support;
+
+use Axlon\PostalCodeValidation\Regex\MatchCountry;
+use Axlon\PostalCodeValidation\Regex\RegexCollection;
+use Axlon\PostalCodeValidation\Rules\PostalCode;
+use Axlon\PostalCodeValidation\Support\PostalCodeServiceProvider;
+use Illuminate\Support\Facades\Lang;
+use Illuminate\Support\Facades\Validator;
+use Orchestra\Testbench\TestCase;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\UsesClass;
+
+#[CoversClass(PostalCodeServiceProvider::class)]
+#[UsesClass(MatchCountry::class)]
+#[UsesClass(PostalCode::class)]
+#[UsesClass(RegexCollection::class)]
+final class PostalCodeServiceProviderTest extends TestCase
+{
+    protected function getPackageProviders($app): array
+    {
+        return [
+            PostalCodeServiceProvider::class,
+        ];
+    }
+
+    public function testItValidatesPostalCodeForCountryCode(): void
+    {
+        Lang::addLines([
+            'validation.postal_code' => ':Attribute should be a valid postal code such as :examples.',
+        ], 'en');
+
+        $validator = Validator::make(['value' => '1234'], ['value' => 'postal_code:NL']);
+
+        self::assertFalse($validator->passes());
+        self::assertSame(['Value should be a valid postal code such as 1234 AB.'], $validator->messages()->all());
+    }
+
+    public function testItValidatesPostalCodeForCountryCodeField(): void
+    {
+        Lang::addLines([
+            'validation.postal_code' => ':Attribute should be a valid :countries postal code.',
+        ], 'en');
+
+        $validator = Validator::make(
+            ['value' => '1234', 'other' => 'NL'],
+            ['value' => 'postal_code:other'],
+        );
+
+        self::assertFalse($validator->passes());
+        self::assertSame(['Value should be a valid NL postal code.'], $validator->messages()->all());
+    }
+}
