Address Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require cmrweb/address-bundle in your Symfony project. For non-Flex projects, manually add Cmrweb\AddressBundle\AddressBundle::class to config/bundles.php.

2. First Use Case: Autocomplete Input Generate a search component with:

   symfony console make:address -b  # With Bootstrap 5 classes
   

   Embed it in Twig:

   <twig:SearchAddress />
   

3. First Address Retrieval Use the AddressTrait in a controller or entity:

   use Cmrweb\AddressBundle\Traits\AddressTrait;
   
   class MyController {
       use AddressTrait;
   
       public function showAddress() {
           $address = $this->getAddress(); // Returns Address Model
           $addressArray = $this->getAddressArray(); // Returns array
       }
   }
   

Implementation Patterns

Workflows

1. Frontend Integration

   • Use make:address to scaffold autocomplete inputs (supports Bootstrap 5 via -b flag).
   • Customize Twig templates in templates/address/ (override default paths).

2. Backend Integration

   • Attach AddressTrait to entities or controllers to fetch/save addresses via API.gouv.fr.
   • Example entity:

     use Cmrweb\AddressBundle\Traits\AddressTrait;
     
     class User {
         use AddressTrait;
         // ...
     }
     

3. API.gouv.fr Integration

   • The bundle abstracts API calls. Configure endpoints in config/packages/cmrweb_address.yaml:

     cmrweb_address:
         api_url: 'https://api-adresse.data.gouv.fr'
     

4. Validation & Form Handling

   • Use the AddressType form field for Symfony forms:

     $builder->add('address', AddressType::class);
     

Tips for Daily Use

• Lazy Loading: Address data is fetched on-demand via getAddress().
• Caching: Cache API responses with Symfony’s cache system (configure in cmrweb_address.yaml).
• Localization: Supports French addresses by default; extend for other locales via custom traits.

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • API.gouv.fr has usage limits. Cache responses aggressively:

     cmrweb_address:
         cache_enabled: true
         cache_lifetime: 3600  # 1 hour
     

2. Trait Conflicts

   • Avoid naming collisions with AddressTrait in other bundles. Prefix or namespace traits.

3. Twig Template Overrides

   • Override templates in templates/address/ but ensure the directory structure matches the bundle’s (e.g., templates/address/search.html.twig).

4. Bootstrap 5 Flag

   • The -b flag in make:address adds Bootstrap 5 classes. Remove manually if using another CSS framework.

Debugging

• API Errors: Check var/log/dev.log for API.gouv.fr response errors. Enable debug mode:

  cmrweb_address:
      debug: true
  

• Missing Data: Validate getAddressArray() returns expected keys (id, name, postcode, etc.). Extend the trait if needed.

Extension Points

1. Custom Address Fields

   • Extend the Address model by creating a custom trait:

     trait CustomAddressTrait extends AddressTrait {
         public function getFullLabel() {
             return $this->getAddressArray()['name'] . ', ' . $this->getAddressArray()['postcode'];
         }
     }
     

2. Alternative APIs

   • Override the API URL in config or create a decorator service for Cmrweb\AddressBundle\Service\AddressService.

3. Validation Rules

   • Extend the AddressType form field to add custom validation:

     $builder->add('address', AddressType::class, [
         'constraints' => [new NotBlank(), new CustomAddressConstraint()]
     ]);