Laravel Postal Code Validation Laravel Package

Getting Started

Install via Composer:

composer require axlon/laravel-postal-code-validation

First use case: Validate a postal code for a specific country in a form request.

use Illuminate\Validation\Rule;

$request->validate([
    'postal_code' => ['required', Rule::postal_code('US')],
]);

Where to look first:

1. Usage section in the README for rule syntax.
2. Available rules to understand postal_code vs. postal_code_with.
3. Error messages for localization.

Implementation Patterns

1. Form Validation (Most Common)

Pattern: Use postal_code rule with ISO country codes (e.g., US, DE).

$request->validate([
    'country' => 'required|string|size:2',
    'postal_code' => 'required|postal_code:'.$request->country,
]);

Fluent API Alternative (for dynamic countries):

use Axlon\PostalCodeValidation\Rules\PostalCode;

$request->validate([
    'postal_code' => [new PostalCode($request->country)],
]);

2. Conditional Validation (e.g., Shipping/Billing)

Pattern: Use postal_code_with when country is dynamic or optional.

$request->validate([
    'billing_country' => 'required|string|size:2',
    'shipping_country' => 'nullable|string|size:2',
    'shipping_postal_code' => 'postal_code_with:billing_country,shipping_country',
]);

Fluent API:

'shipping_postal_code' => [
    new PostalCode->with('billing_country')->or('shipping_country'),
],

3. Manual Validation (Outside Requests)

Pattern: Use the PostalCodes facade for standalone checks.

use Axlon\PostalCodeValidation\Facades\PostalCodes;

if (PostalCodes::passes('US', '90210')) {
    // Valid
}

Use case: Validate addresses in cron jobs, API responses, or non-form contexts.

4. Overriding Patterns (Edge Cases)

Pattern: Customize regex for specific countries (e.g., legacy formats).

// In a service provider or config file
PostalCodes::override('US', '/^\d{5}(-\d{4})?$/'); // ZIP+4 support

Use case: Override patterns for internal systems (e.g., company-specific codes).

5. Localization

Pattern: Extend validation messages in resources/lang/{locale}/validation.php.

'postal_code' => 'The :attribute must be a valid postal code for :countries (e.g., :examples).',

Placeholder examples:

• :countries → US, CA
• :examples → 90210, K1A 0B1

6. Testing

Pattern: Mock the facade for unit tests.

PostalCodes::shouldReceive('passes')
    ->once()
    ->with('US', '90210')
    ->andReturn(true);

Use case: Isolate validation logic from external dependencies.

Gotchas and Tips

Pitfalls

1. Case Sensitivity:

   • Country codes are case-insensitive (US = us), but ensure consistency in your codebase.

2. Missing Arguments:

   • Rules require country codes (e.g., postal_code:US).
   • Fix: Add a fallback or default country:

     'postal_code' => 'postal_code:'.$request->country ?? 'US',
     

3. Dynamic Arrays:

   • For nested arrays (e.g., addresses.*.postal_code), use dot notation:

     'addresses.*.postal_code' => 'postal_code_with:addresses.*.country',
     

4. Deprecated postal_code_for:

   • Use postal_code_with instead (same functionality, no deprecation warnings).

5. Performance:

   • Avoid validating every request field with this rule (e.g., in bulk imports). Cache results if needed.

Debugging Tips

1. Validate Manually: Use PostalCodes::passes() to debug specific cases:

   dd(PostalCodes::passes('NL', '1234AB')); // true/false
   

2. Check Patterns: Inspect the underlying regex for a country:

   dd(PostalCodes::pattern('US')); // e.g., '/^\d{5}(-\d{4})?$/'
   

3. Error Messages: If placeholders (:countries, :examples) are empty, ensure the rule received valid arguments.

4. Lumen Users: Explicitly register the provider in bootstrap/app.php if using Lumen.

Extension Points

1. Custom Rules: Extend the PostalCode class to add logic (e.g., validate against a database):

   use Axlon\PostalCodeValidation\Rules\PostalCode as BasePostalCode;
   
   class CustomPostalCode extends BasePostalCode {
       public function passes($attribute, $value) {
           return parent::passes($attribute, $value) &&
                  DB::table('valid_codes')->where('code', $value)->exists();
       }
   }
   

2. Add Countries: Contribute missing patterns via GitHub Issues.

3. Batch Validation: For bulk validation (e.g., CSV imports), use the facade in a loop:

   foreach ($addresses as $address) {
       if (!PostalCodes::passes($address['country'], $address['postal_code'])) {
           $errors[] = "Invalid code: {$address['postal_code']}";
       }
   }
   

Config Quirks

1. Service Provider: If using Laravel <8.0, manually register the provider in config/app.php:

   'providers' => [
       Axlon\PostalCodeValidation\ValidationServiceProvider::class,
   ],
   

2. Facade Alias: The PostalCodes facade is auto-discovered. No additional config needed.

3. PHP 8+: Uses named arguments in some methods (e.g., PostalCode::for()). Ensure your IDE supports PHP 8 syntax hints.

Pro Tips

1. Combine with Other Rules: Add length checks or alphanumeric constraints:

   'postal_code' => 'postal_code:US|min:5|max:10',
   

2. API Responses: Return formatted errors with examples:

   return response()->json([
       'error' => 'Invalid postal code for US (e.g., 90210).',
   ], 422);
   

3. Frontend Integration: Use the package’s examples in JavaScript for real-time validation:

   // Show examples like "1234 AB" for NL in your form hints.
   

4. Logging: Log invalid codes for analytics:

   if (!PostalCodes::passes($country, $code)) {
       Log::warning("Invalid postal code: {$code} for {$country}");
   }