Location Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require chaplean/location-bundle in your Symfony 2.8+ project. Register the bundle in AppKernel.php:

   new Chaplean\Bundle\LocationBundle\ChapleanLocationBundle(),
   

2. Load Default Data Populate cities via CLI:

   php bin/console location:load:cities
   

   (Note: Requires external data sources—see Resources for INSEE/Postal Code APIs.)

3. First Use Case Inject and query locations in a controller/service:

   use Chaplean\Bundle\LocationBundle\Model\LocationInterface;
   
   public function getCityByName(LocationInterface $locationManager)
   {
       $city = $locationManager->findCityByName('Paris');
       return $json($city);
   }
   

Implementation Patterns

Core Workflows

1. Data Loading

   • Manual: Use location:load:cities for one-time imports.
   • Automated: Embed in migrations (as shown in README) for CI/CD pipelines.
   • Custom Sources: Extend Chaplean\Bundle\LocationBundle\Command\LoadCitiesCommand to fetch from private APIs.

2. Dependency Injection

   • Inject LocationInterface (e.g., CityManager, RegionManager) into services/controllers.
   • Example:

     # services.yaml
     App\Service\LocationService:
         arguments:
             $regionManager: '@chaplean_location.region.manager'
     

3. Validation & Filtering

   • Use built-in validators (e.g., PostalCodeValidator) for form handling:

     $validator = $this->get('validator');
     $errors = $validator->validate($entity, ['Constraints\ValidPostalCode']);
     

4. API Integration

   • Fetch real-time data via LocationApiClient (if extended):

     $client = $this->container->get('chaplean_location.api_client');
     $response = $client->getDepartments();
     

Integration Tips

• Database Schema: The bundle assumes tables like city, department, region. Align your Doctrine mappings:

  # config/doctrine/orm.yml
  Chaplean\Bundle\LocationBundle\Entity\City:
      type: entity
      table: city
  

• Translation: Override default labels (e.g., "Département") in translations/messages.fr.yml:

  chaplean_location:
      department: "Région administrative"
  

• Caching: Decorate LocationManager to cache frequent queries (e.g., city lookups):

  $cache = $this->container->get('cache.app');
  $cachedCity = $cache->get("city_{$name}");
  

Gotchas and Tips

Pitfalls

1. Outdated Data

   • The bundle relies on external APIs (INSEE, Data.gouv.fr). Verify data freshness post-import:

     php bin/console location:validate:cities
     

   • Fix: Schedule periodic updates via cron or Symfony’s CronExpression.

2. Missing Regions

   • The README lacks a clear source for "Regions" (vs. Départements). Use INSEE’s regional codes manually.

3. Command Exit Codes

   • location:load:cities exits with 1 on failure (e.g., API downtime). Handle in migrations:

     if ($exitCode !== 0) {
         throw new \RuntimeException('Failed to load cities. Check logs.');
     }
     

4. Doctrine Conflicts

   • If using custom entity namespaces, override the bundle’s default mappings in config/packages/chaplean_location.yaml:

     chaplean_location:
         entity:
             city: App\Entity\CustomCity
     

Debugging

• Log Commands: Enable debug mode to see API responses:

  APP_DEBUG=1 php bin/console location:load:cities
  

• SQL Queries: Use Doctrine’s profiler to check for missing joins:

  $profiler = $this->container->get('profiler');
  $profiler->collect();
  

Extension Points

1. Custom Data Sources

   • Override Chaplean\Bundle\LocationBundle\DataLoader\CityLoader to use a private database:

     class CustomCityLoader extends CityLoader {
         public function load() {
             return $this->entityManager->getRepository(CustomCity::class)->findAll();
         }
     }
     

   • Register as a service:

     services:
         chaplean_location.city_loader:
             class: App\DataLoader\CustomCityLoader
             tags: ['chaplean_location.city_loader']
     

2. Add New Location Types

   • Extend the LocationInterface and create a new manager (e.g., NeighborhoodManager):

     class NeighborhoodManager implements LocationInterface {
         public function findByPostalCode($code) { ... }
     }
     

   • Register in Resources/config/services.xml:

     <service id="chaplean_location.neighborhood.manager" class="App\Manager\NeighborhoodManager" />
     

3. API Clients

   • Replace the default LocationApiClient with a GraphQL/REST client:

     class CustomApiClient implements LocationApiClientInterface {
         public function getDepartments() {
             return $this->httpClient->request('GET', 'https://api.example.com/departments');
         }
     }
     

Config Quirks

• Default Locale: The bundle assumes French (fr) for INSEE data. Change in config/packages/chaplean_location.yaml:

  chaplean_location:
      locale: 'en' # For English labels
  

• Environment Variables: Store API keys in .env:

  CHAPLEAN_LOCATION_API_KEY=your_key_here