Address Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require eckinox/address-bundle

Publish the bundle's configuration and migrations:

php artisan vendor:publish --provider="Eckinox\AddressBundle\AddressServiceProvider"
php artisan migrate

The package now dynamically sets AJAX routes based on the firewall configuration (introduced in v5.1.0). Verify your config/address-bundle.php includes proper firewalls settings for API routes:

'firewalls' => [
    'api' => ['ajax' => true], // Enable AJAX for API routes
],

Test AJAX functionality by calling protected endpoints (e.g., GET /api/addresses).

Implementation Patterns

Dynamic AJAX Route Handling

Leverage the new firewall-based AJAX route system to:

1. Conditionally enable AJAX for specific routes by defining ajax: true in the firewall config.
2. Use middleware to validate AJAX requests:

   Route::get('/addresses', [AddressController::class, 'index'])
       ->middleware(['web', 'address.firewall:api']); // Uses 'api' firewall
   

3. Frontend integration: Ensure AJAX calls include the X-Requested-With: XMLHttpRequest header or use the address-bundle:ajax middleware.

Workflow for Address Management

1. Fetch addresses via AJAX:

   fetch('/api/addresses', {
       headers: { 'X-Requested-With': 'XMLHttpRequest' }
   });
   

2. Validate responses using the bundle’s built-in AJAX error handling (e.g., 422 for validation errors).
3. Update addresses via PATCH/POST routes protected by the api firewall.

Integration with Existing Systems

• API Resources: Extend Eckinox\AddressBundle\Http\Resources\AddressResource for custom JSON responses.
• Form Requests: Use Eckinox\AddressBundle\Http\Requests\StoreAddressRequest as a base for validation logic.

Gotchas and Tips

Pitfalls

1. Firewall Misconfiguration:
   • Forgetting to set ajax: true in the firewall config will break AJAX routes.
   • Fix: Verify config/address-bundle.php and test with:

     php artisan address:test-firewall api
     

2. CSRF Protection:
   • AJAX routes in the web firewall may still require CSRF tokens unless explicitly excluded.
   • Fix: Use csrf_exclude middleware or disable CSRF for API firewalls:

     'firewalls' => [
         'api' => ['ajax' => true, 'csrf' => false],
     ],
     

3. Route Caching:
   • Clear route cache after updating firewall configs:

     php artisan route:clear
     

Debugging Tips

• Check AJAX Headers: Use browser dev tools to confirm X-Requested-With is sent.
• Log Firewall Rules: Add temporary logging in app/Providers/AddressServiceProvider.php to debug route assignment:

  \Log::debug('Firewall config:', ['config' => config('address-bundle.firewalls')]);
  

• Test Endpoints: Use php artisan route:list to verify AJAX routes are registered under the correct firewall.

Extension Points

1. Custom Firewalls: Extend the firewall system by publishing and modifying the config:

   php artisan vendor:publish --tag="address-bundle-config"
   

2. Middleware Overrides: Override the address.firewall middleware in app/Http/Kernel.php for custom logic:

   'address.firewall' => \App\Http\Middleware\CustomAddressFirewall::class,
   

3. Event Listeners: Listen for address.firewall.assigned events to log or modify route assignments:

   Event::listen('address.firewall.assigned', function ($route, $firewall) {
       \Log::info("Route {$route->uri()} assigned to firewall {$firewall}");
   });