Laravel Postal Code Validation Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require axlon/laravel-postal-code-validation
   

   • Laravel/Lumen 5.5+ auto-registers via package discovery. For manual registration, add to config/app.php:

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

2. First Use Case: Validate a postal code for a specific country in a form request:

   // app/Http/Requests/StoreAddressRequest.php
   public function rules()
   {
       return [
           'postal_code' => 'required|postal_code:US', // US = ISO 3166-1 alpha-2
       ];
   }
   

3. Key Files to Review:

   • resources/lang/en/validation.php: Customize error messages.
   • app/Providers/AppServiceProvider.php: Override country patterns if needed (see Implementation Patterns).

Implementation Patterns

Core Workflows

1. Form Validation (Most Common)

• String Syntax:

  'postal_code' => 'postal_code:NL,DE,FR', // Valid for Netherlands, Germany, or France
  

• Fluent API (for dynamic country selection):

  'postal_code' => [
      PostalCode::for('NL')->or('BE'), // Valid for NL or BE
  ],
  

• Conditional Validation (e.g., shipping address):

  'shipping.postal_code' => [
      PostalCode::with('shipping.country')->or('billing.country'),
  ],
  

  Note: Uses postal_code_with (replaces deprecated postal_code_for).

2. Manual Validation (Non-Form Logic)

use Axlon\PostalCodeValidation\Facades\PostalCodes;

$isValid = PostalCodes::passes('US', '90210'); // true

3. Dynamic Country Handling

• From Request Data:

  'country' => 'required|string|max:2',
  'postal_code' => 'required|postal_code_with:country',
  

• Array Fields (e.g., multi-address forms):

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

4. Error Handling

• Custom Messages:

  // resources/lang/en/validation.php
  'postal_code' => 'The :attribute must be a valid postal code for :countries (e.g., :examples).',
  

• Placeholders:
  • :attribute: Field name (e.g., "Shipping Postal Code").
  • :countries: Comma-separated ISO codes (e.g., "US,CA").
  • :examples: Country-specific examples (e.g., "90210, M5V 3L9").

Integration Tips

With Laravel Validation

• Form Requests:

  public function rules()
  {
      return [
          'user.address.postal_code' => 'postal_code:GB', // UK-specific
      ];
  }
  

• API Resources:

  $validator = Validator::make($request->all(), [
      'postal_code' => 'postal_code:JP', // Japan
  ]);
  

With Livewire/Alpine.js

• Frontend Validation:

  // Alpine.js
  <input x-model="postalCode" x-data="{ error: null }"
         @blur="validatePostalCode($event.target.value, 'US')">
  
  // Backend (Livewire)
  public function validatePostalCode($postalCode, $country)
  {
      return PostalCodes::passes($country, $postalCode);
  }
  

With Eloquent Models

• Observer for Validation:

  // app/Models/User.php
  protected static function boot()
  {
      static::saving(function ($user) {
          if ($user->address && !$user->address->isValidPostalCode()) {
              throw new \Exception('Invalid postal code for ' . $user->address->country);
          }
      });
  }
  

Testing

• Unit Tests:

  use Axlon\PostalCodeValidation\Facades\PostalCodes;
  
  public function testValidPostalCode()
  {
      $this->assertTrue(PostalCodes::passes('DE', '10115'));
      $this->assertFalse(PostalCodes::passes('DE', 'INVALID'));
  }
  

• Feature Tests:

  $response = $this->post('/addresses', [
      'postal_code' => 'INVALID',
      'country' => 'US',
  ]);
  $response->assertSessionHasErrors('postal_code');
  

Gotchas and Tips

Pitfalls

1. Deprecated postal_code_for Rule:

   • Use postal_code_with instead (added in v3.1.2). The old rule triggers deprecation warnings.

2. Case Sensitivity:

   • Country codes (e.g., US, us) are case-insensitive, but regex patterns are not. Override patterns if needed.

3. Empty Input Handling:

   • The validator fails silently for null/empty inputs. Add required or nullable explicitly:

     'postal_code' => 'nullable|postal_code:CA',
     

4. Performance:

   • Avoid dynamic country lists in loops (e.g., postal_code:.implode($countries)). Cache or pre-validate:

     $validCountries = ['US', 'CA'];
     $rule = 'postal_code:' . implode(',', $validCountries);
     

5. Google ADS Dependencies:

   • Patterns are static (updated via package releases). For real-time validation, consider integrating Google’s Address Validation API directly.

6. Edge Cases:

   • Canary Islands (ES): Use ES (Spain) or override with IC (ISO 3166-2).
   • Overrides: Test thoroughly after overriding patterns (e.g., PostalCodes::override('NL', '/^[1-9]\d{3}[A-Za-z]{2}$/')).

Debugging Tips

1. Validate Patterns:

   • Check if a country’s pattern matches expectations:

     $pattern = PostalCodes::getPattern('US'); // Returns regex for US
     

2. Error Messages:

   • Debug placeholders with:

     $translator = app('translator');
     $message = $translator->get('validation.postal_code', [
         'attribute' => 'postal_code',
         'countries' => 'US,CA',
         'examples' => '90210, M5V 3L9',
     ]);
     

3. Logging:

   • Log validation attempts for troubleshooting:

     \Log::debug('Postal code validation', [
         'country' => $country,
         'code' => $postalCode,
         'valid' => PostalCodes::passes($country, $postalCode),
     ]);
     

Extension Points

1. Custom Patterns:

   • Override patterns globally (e.g., for testing or edge cases):

     // In a Service Provider
     PostalCodes::override([
         'XX' => '/^TEST\d{5}$/', // Custom test country
     ]);
     

2. Extending Validation:

   • Create a custom rule for business logic:

     use Axlon\PostalCodeValidation\PostalCodeValidator;
     
     class ValidBusinessPostalCode extends \Illuminate\Validation\Rule
     {
         public function passes($attribute, $value)
         {
             $country = request()->input('country');
             return PostalCodeValidator::passes($country, $value) &&
                    in_array($country, ['US', 'CA']);
         }
     }
     

     Usage:

     'postal_code' => ['valid_business_postal_code'],
     

3. Adding New Countries:

   • Contribute patterns via GitHub Issues or fork the package.

4. Testing Overrides:

   • Use PostalCodes::swap() to temporarily replace patterns in tests:

     PostalCodes::swap(function () {
         PostalCodes::override('NL', '/^TEST$/');
     });
     try {
         $this->assertTrue(PostalCodes::passes('NL', 'TEST'));
     } finally {
         PostalCodes::stopSwapping();
     }
     

Pro Tips

1. Batch Validation:
   • Validate multiple addresses efficiently:

     $addresses = [
         ['country' => 'US', 'postal_code'