Location Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require avro/location-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Avro\LocationBundle\AvroLocationBundle::class => ['all' => true],
   ];
   

2. First Use Case Fetch a list of US states in a controller:

   use Avro\LocationBundle\Service\LocationService;
   
   class LocationController extends AbstractController
   {
       public function index(LocationService $locationService)
       {
           $states = $locationService->getStates('US');
           return $this->json($states);
       }
   }
   

3. Where to Look First

   • Service Layer: src/Service/LocationService.php for core functionality.
   • Data Sources: Resources/data/ for raw location data (CSV/JSON).
   • Twig Extensions: Twig/ for template helpers (if available).

Implementation Patterns

Common Workflows

1. Fetching Locations

   // Get all countries
   $countries = $locationService->getCountries();
   
   // Get Canadian provinces
   $provinces = $locationService->getProvinces('CA');
   
   // Get cities in a state (e.g., California)
   $cities = $locationService->getCities('US', 'CA');
   

2. Integration with Forms Use in Symfony Forms for address validation:

   use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
   
   $builder->add('state', ChoiceType::class, [
       'choices' => $locationService->getStates('US'),
       'choice_label' => 'name',
       'choice_value' => 'abbreviation',
   ]);
   

3. Caching Data Wrap service calls in a cache layer (e.g., Symfony Cache component):

   $cache = $this->get('cache.app');
   $key = 'locations:states:US';
   $states = $cache->get($key, function() use ($locationService) {
       return $locationService->getStates('US');
   });
   

4. Custom Data Sources Extend the bundle by adding new data files to Resources/data/ and update the service to parse them.

Dependency Injection

• Service Autowiring: The LocationService is autowireable (no manual DI config needed).
• Configuration: Check config/packages/avro_location.yaml for bundle-specific settings (if any).

Gotchas and Tips

Pitfalls

1. Data Accuracy

   • The bundle is WIP (Work in Progress). Validate data against official sources (e.g., USPS for US addresses).
   • Example: Canadian provinces may lack territories (Yukon, Nunavut) or have outdated abbreviations.

2. Performance

   • Loading large datasets (e.g., all US cities) may cause memory issues. Use pagination or lazy-loading:

     $locationService->getCities('US', 'CA', 0, 10); // Limit to 10 cities
     

3. Missing Features

   • No built-in geocoding (latitude/longitude). Integrate with Google Maps API or Nominatim if needed.
   • No address validation logic (e.g., checking if a ZIP code exists for a state).

4. Bundle Maturity

   • No tests or documentation beyond the README. Test edge cases (e.g., invalid country codes).
   • No Symfony 5/6 compatibility (assumes Symfony 2/3/4). Check for breaking changes if upgrading.

Debugging Tips

1. Inspect Data Structure Dump raw data to understand the format:

   dd($locationService->getCountries());
   

   Example output may look like:

   [
       ['code' => 'US', 'name' => 'United States', 'abbreviation' => 'USA'],
       ['code' => 'CA', 'name' => 'Canada', 'abbreviation' => 'CAN'],
   ]
   

2. Override Data Files Copy Resources/data/ to your project and extend/modify files (e.g., states.csv). The bundle likely loads from these paths by default.

3. Logging Add debug logs to track data loading:

   $this->get('logger')->debug('Loaded states for country: ' . $countryCode);
   

Extension Points

1. Custom Location Types Extend the service to support new location types (e.g., counties, postal codes):

   // In a custom service
   public function getCounties(string $stateCode): array
   {
       return $this->loadData('counties_' . $stateCode . '.json');
   }
   

2. Database Backend Replace the file-based data source with a database table. Override the loadData() method in a subclass of LocationService.

3. Twig Filters Add custom Twig filters for templating:

   // In a compiler pass or Twig extension
   $twig->addFilter(new \Twig\TwigFilter('format_location', [$locationService, 'formatLocation']));
   

   Usage in Twig:

   {{ city|format_location }}
   

4. API Integration Cache API responses (e.g., from GeoNames) and fall back to the bundle’s data:

   try {
       $data = $this->fetchFromGeoNamesApi();
   } catch (\Exception $e) {
       $data = $locationService->getFallbackData();
   }