Postal Pt Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require luismarcelino/postal-pt:dev-master
   

2. Register Service Provider & Facade Add to config/app.php:

   'providers' => [
       Luismarcelino\PostalPt\CodigosPostaisServiceProvider::class,
   ],
   'aliases' => [
       'PostalPt' => Luismarcelino\PostalPt\CodigosPostaisFacade::class,
   ]
   

3. Run Migration & Seed

   php artisan postalpt:migration
   php artisan migrate
   php artisan postalpt:seed
   

4. First Query

   use PostalPt;
   
   $postalCode = PostalPt::find('1000-001'); // Returns district/freguesia data
   

Where to Look First

• Facade API: PostalPt::find($code) for direct lookups.
• Model: App\Models\PostCodePT (auto-registered) for Eloquent queries.
• Migration/Seed: Check database/migrations/ for table structure.

Implementation Patterns

Core Workflows

1. Postal Code Validation

   if (PostalPt::isValid('1000-001')) {
       // Process valid Portuguese postal code
   }
   

2. Freguesia/District Lookup

   $data = PostalPt::find('1000-001');
   // Returns: ['district' => 'Lisboa', 'freguesia' => 'Areeiro', ...]
   

3. Querying via Eloquent

   $freguesias = \App\Models\PostCodePT::where('district', 'Lisboa')->get();
   

4. Bulk Validation

   $codes = ['1000-001', '4000-000', '9999-999'];
   $validCodes = array_filter($codes, fn($code) => PostalPt::isValid($code));
   

Integration Tips

• Form Validation: Use in Laravel's FormRequest:

  public function rules() {
      return ['postal_code' => 'required|postal_code_pt'];
  }
  

  (Requires custom validation rule; see Gotchas).

• API Responses: Attach freguesia data to user addresses:

  $user->address->postal_code = '1000-001';
  $user->address->freguesia = PostalPt::find($user->address->postal_code)?->freguesia;
  

• Geocoding: Combine with spatie/laravel-geocoder for latitude/longitude:

  $geocode = Geocoder::geocode('Areeiro, Lisboa');
  

Gotchas and Tips

Pitfalls

1. Hyphenated Format

   • Always use 1000-001 (not 1000001). The package expects hyphenated codes.
   • Fix: Normalize input:

     $normalized = str_replace('-', '', $input); // Then validate
     

2. Missing Validation Rule

   • The package doesn’t include a built-in validation rule. Add this to AppServiceProvider:

     Validator::extend('postal_code_pt', function ($attribute, $value, $parameters, $validator) {
         return PostalPt::isValid(str_replace('-', '', $value));
     });
     

3. Seed Command Warning

   • postalpt:seed may time out for large databases. Run in chunks:

     php artisan postalpt:seed --chunk=1000
     

   • Alternative: Use db:seed with a custom seeder if the package’s command fails.

4. Case Sensitivity

   • District/freguesia names are case-sensitive in queries. Use strtolower():

     \App\Models\PostCodePT::where('district', strtolower('Lisboa'))->get();
     

Debugging

• Check Table Data:

  php artisan tinker
  >>> \App\Models\PostCodePT::count(); // Verify records exist
  >>> \App\Models\PostCodePT::first(); // Inspect structure
  

• Log Missing Codes:

  if (!$postalCode = PostalPt::find('9999-999')) {
      Log::warning("Invalid postal code: 9999-999");
  }
  

Extension Points

1. Custom Fields

   • Extend the PostCodePT model to add computed properties:

     public function getFullLocationAttribute() {
         return "{$this->district}, {$this->freguesia}";
     }
     

2. Autocomplete API

   • Build a route for frontend searches:

     Route::get('/api/postal-codes', function () {
         return \App\Models\PostCodePT::select('post_code', 'freguesia')
             ->where('post_code', 'like', request('q').'%')
             ->limit(10)
             ->get();
     });
     

3. Local Overrides

   • Publish and modify the migration to add custom columns:

     php artisan vendor:publish --tag=postalpt-migrations
     

   • Then run:

     php artisan migrate
     php artisan postalpt:seed