Laravel Addresses Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require metamel/laravel-addresses
   php artisan vendor:publish --tag=addresses-config
   php artisan migrate
   

   • Verify the addresses and addressables tables exist in your database.

2. First Use Case: Attach the Addressable trait to a model (e.g., User):

   use Metamel\Addresses\Traits\Addressable;
   
   class User extends Model
   {
       use Addressable;
     }
   

   • Now, any User instance will have an addresses() relationship and addresses() method.

3. Quick Test:

   $user = User::find(1);
   $user->addresses()->create([
       'label' => 'Home',
       'street' => '123 Main St',
       'city' => 'Anytown',
       'postcode' => '12345',
       'country' => 'US'
   ]);
   

   • Check the database to confirm the address was created under the addressables table.

Implementation Patterns

Core Workflows

1. Polymorphic Address Management:

   • Use the trait on any Eloquent model (e.g., User, Vendor, Store) to enable address storage.
   • Example:

     class Vendor extends Model
     {
         use Addressable;
     }
     

   • Addresses are stored in the addresses table with a polymorphic addressable_id and addressable_type.

2. Address Retrieval:

   • Fetch all addresses for a model:

     $user->addresses; // Collection of Address models
     

   • Filter by label or type:

     $user->addresses()->where('label', 'Work')->get();
     

3. Validation:

   • Use the built-in validation rules (published in config/addresses.php):

     use Metamel\Addresses\Rules\AddressRules;
     
     $validated = $request->validate([
         'street' => ['required', new AddressRules\Street],
         'city' => ['required', new AddressRules\City],
     ]);
     

4. Geocoding (Optional):

   • Enable geocoding in the config and use:

     $address = $user->addresses()->create([...]);
     $address->geocode(); // Updates lat/long via config service (e.g., Google Maps)
     

5. API Responses:

   • Serialize addresses in API responses:

     return User::with('addresses')->find(1);
     

   • Customize serialization via AppServiceProvider:

     Address::addHidden(['internal_field']);
     

Integration Tips

• Events: Listen for AddressCreated, AddressUpdated, or AddressDeleted events to trigger notifications or sync external services.

  event(new AddressCreated($address));
  

• Scopes: Add global scopes to filter addresses (e.g., active only):

  use Metamel\Addresses\Scopes\ActiveScope;
  
  class User extends Model
  {
      use Addressable;
      protected static function booted()
      {
          static::addGlobalScope(new ActiveScope);
      }
  }
  

• Testing: Use factories to seed test addresses:

  $user = User::factory()->create();
  $user->addresses()->createMany([
      ['label' => 'Home', 'street' => '123 Test St'],
      ['label' => 'Work', 'street' => '456 Office Ave'],
  ]);
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If you manually modify the addresses or addressables tables, future migrations may fail. Always run php artisan migrate:fresh after manual changes.

2. Polymorphic Relationships:

   • Forgetting to use the Addressable trait on a model will break polymorphic queries. Double-check:

     // ❌ Fails silently if trait is missing
     $user->addresses()->get();
     

3. Geocoding Failures:

   • If geocoding fails (e.g., invalid API key), the lat/lng fields will be null. Handle this in your UI:

     $address->lat ?? 'N/A'
     

4. Soft Deletes:

   • The package does not support soft deletes by default. Enable it manually in the Address model:

     use SoftDeletes;
     class Address extends Model
     {
         use SoftDeletes;
     }
     

     Then update the addresses table migration to add deleted_at.

5. Label Uniqueness:

   • Labels (e.g., "Home", "Work") are not enforced as unique per model by default. Add validation if needed:

     $request->validate([
         'label' => ['required', Rule::unique('addresses')->where('addressable_id', $user->id)],
     ]);
     

Debugging

1. Missing Addresses:

   • Verify the addressable_type matches the model's fully qualified class name (e.g., App\Models\User).
   • Check for typos in the relationship method (addresses() vs. address()).

2. Query Issues:

   • Use toSql() to debug raw queries:

     $query = $user->addresses()->where('label', 'Home');
     dd($query->toSql(), $query->getBindings());
     

3. Config Overrides:

   • Published config (config/addresses.php) may override defaults. Review:

     'geocoding' => [
         'service' => 'google', // or 'openstreetmap'
         'api_key' => env('GOOGLE_MAPS_API_KEY'),
     ],
     

Extension Points

1. Custom Address Fields:

   • Extend the Address model to add fields (e.g., floor, unit):

     class Address extends \Metamel\Addresses\Models\Address
     {
         protected $fillable = ['floor', 'unit'];
     }
     

   • Update the migration and config validation rules accordingly.

2. Custom Validation:

   • Override validation rules in a service provider:

     AddressRules::extend('postcode', function ($attribute, $value, $fail) {
         if (!preg_match('/^\d{5}(-\d{4})?$/', $value)) {
             $fail('Invalid US ZIP code.');
         }
     });
     

3. Address Types:

   • Add a type field to categorize addresses (e.g., "billing", "shipping") and filter:

     $user->addresses()->where('type', 'shipping')->get();
     

4. Localization:

   • Override label translations in resources/lang/en/addresses.php:

     return [
         'label' => 'Address Label',
         'street' => 'Street Address',
     ];
     

5. API Resources:

   • Create a dedicated resource for addresses:

     php artisan make:resource AddressResource
     

     Then customize the response:

     public function toArray($request)
     {
         return [
             'full_address' => $this->formatFullAddress(),
             'distance' => $this->calculateDistance($request->user()),
         ];
     }