Addresses Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tipoff/addresses
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="Tipoff\Addresses\AddressesServiceProvider"
   php artisan migrate
   

2. First Use Case: Storing an Address

   use Tipoff\Addresses\Models\Address;
   
   $address = Address::create([
       'name' => 'John Doe',
       'street' => '123 Main St',
       'city' => 'New York',
       'state' => 'NY',
       'postal_code' => '10001',
       'country' => 'US',
   ]);
   

3. Where to Look First

   • Config File: config/addresses.php (API keys, default settings).
   • Models: Tipoff\Addresses\Models\Address (core model).
   • API Service: Tipoff\Addresses\Services\AddressApiService (for external API interactions).

Implementation Patterns

Core Workflows

1. CRUD Operations Use Eloquent methods directly on the Address model:

   // Fetch an address
   $address = Address::find(1);
   
   // Update an address
   $address->update(['postal_code' => '10002']);
   
   // Delete an address
   $address->delete();
   

2. Validation Leverage Laravel’s built-in validation with the package’s rules:

   use Tipoff\Addresses\Rules\ValidPostalCode;
   
   $request->validate([
       'postal_code' => ['required', new ValidPostalCode],
   ]);
   

3. API Integration Use the AddressApiService to interact with external APIs (e.g., geocoding):

   $api = app(\Tipoff\Addresses\Services\AddressApiService::class);
   $result = $api->validateAddress($address->toArray());
   

4. Relationships Attach addresses to users or other models via polymorphic relationships:

   // In User model
   public function addresses()
   {
       return $this->morphMany(\Tipoff\Addresses\Models\Address::class, 'addressable');
   }
   

5. Events and Observers Extend functionality with events (e.g., AddressCreated):

   // In EventServiceProvider
   protected $listen = [
       \Tipoff\Addresses\Events\AddressCreated::class => [
           \App\Listeners\SendAddressWelcomeEmail::class,
       ],
   ];
   

Gotchas and Tips

Common Pitfalls

1. API Key Configuration

   • Ensure config/addresses.api_key is set for external API calls.
   • Test locally with a mock API or disabled API calls in config:

     'api_enabled' => env('ADDRESSES_API_ENABLED', false),
     

2. Postal Code Validation

   • The ValidPostalCode rule defaults to US formats. Override in config:

     'postal_code' => [
         'regex' => '/^[A-Z]{1,2}\d[A-Z0-9]? ?\d[A-Z]{2}$/i', // UK format
     ],
     

3. Migration Conflicts

   • If extending the addresses table, run:

     php artisan migrate:fresh --env=testing
     

     to avoid conflicts in test environments.

4. Polymorphic Relationships

   • Ensure the addressable table has addressable_type and addressable_id columns:

     Schema::table('addresses', function (Blueprint $table) {
         $table->morphs('addressable');
     });
     

Debugging Tips

1. API Response Logging Enable debug mode in config:

   'debug' => true,
   

   Logs will appear in storage/logs/laravel.log.

2. Model Events Listen for model events to debug lifecycle:

   Address::created(function ($address) {
       Log::debug('Address created:', $address->toArray());
   });
   

Extension Points

1. Custom Address Types Extend the Address model or create a trait for domain-specific logic:

   namespace App\Models;
   
   use Tipoff\Addresses\Models\Address as BaseAddress;
   
   class ShippingAddress extends BaseAddress
   {
       protected $attributes = [
           'is_shipping' => true,
       ];
   }
   

2. API Service Decorators Decorate AddressApiService to add custom logic:

   class CustomAddressApiService extends \Tipoff\Addresses\Services\AddressApiService
   {
       public function validateAddress(array $data)
       {
           // Custom logic
           return parent::validateAddress($data);
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(
       \Tipoff\Addresses\Services\AddressApiService::class,
       \App\Services\CustomAddressApiService::class
   );
   

3. Testing Use factories and seeders for testing:

   // database/factories/AddressFactory.php
   $factory->define(\Tipoff\Addresses\Models\Address::class, function (Faker $faker) {
       return [
           'name' => $faker->name,
           'street' => $faker->streetAddress,
           // ...
       ];
   });