Laravel Portugal Cities Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require laurentino-dev/laravel-portugal-cities dev-master
   

   Update config/app.php to include:

   'providers' => [
       Laurentinodev\Cities\CitiesServiceProvider::class,
   ],
   'aliases' => [
       'Cities' => Laurentinodev\Cities\CitiesFacade::class,
   ]
   

2. Publish & Migrate

   php artisan vendor:publish --provider="Laurentinodev\Cities\CitiesServiceProvider"
   php artisan cities:migration
   php artisan migrate --seed
   

3. First Use Case Access districts/concelhos via the facade:

   $districts = Cities::districts(); // Collection of all districts
   $concelhos = Cities::concelhos(); // Collection of all concelhos
   $concelhosInLisbon = Cities::concelhosInDistrict('Lisboa'); // Concelhos in a specific district
   

Implementation Patterns

Core Workflows

1. Data Retrieval

   • Districts: Fetch all districts or filter by name.

     $allDistricts = Cities::districts();
     $lisbonDistrict = Cities::district('Lisboa');
     

   • Concelhos: Fetch all, by district, or by name.

     $allConcelhos = Cities::concelhos();
     $lisbonConcelhos = Cities::concelhosInDistrict('Lisboa');
     $portoConcelho = Cities::concelho('Porto');
     

2. Integration with Eloquent Add a district_id or concelho_id foreign key to your models and use the package for validation/dropdowns:

   use Laurentinodev\Cities\CitiesFacade as Cities;
   
   public function rules()
   {
       return [
           'district_id' => 'required|exists:cities,district_id',
           'concelho_id' => 'required|exists:cities,concelho_id',
       ];
   }
   
   public function getDistrictOptions()
   {
       return Cities::districts()->pluck('name', 'district_id');
   }
   

3. API Responses Return structured data for APIs:

   return response()->json([
       'districts' => Cities::districts()->toArray(),
       'concelhos' => Cities::concelhos()->toArray(),
   ]);
   

4. Blade Templates Use in dropdowns or labels:

   <select name="district_id">
       @foreach (Cities::districts() as $district)
           <option value="{{ $district->district_id }}">
               {{ $district->name }}
           </option>
       @endforeach
   </select>
   

Advanced Patterns

1. Custom Queries Extend the facade or service container to add custom logic:

   // In a service provider or helper
   function concelhosByRegion($regionName)
   {
       return Cities::concelhos()
           ->where('region', $regionName)
           ->get();
   }
   

2. Caching Cache district/concelho data to reduce DB load:

   $districts = Cache::remember('portugal_districts', now()->addHours(1), function () {
       return Cities::districts();
   });
   

3. Localization Override names for localization (e.g., English/Portuguese):

   // Publish config and extend the seeder
   Cities::concelhos()->each(function ($concelho) {
       $concelho->english_name = Str::slug($concelho->name);
   });
   

Gotchas and Tips

Pitfalls

1. Laravel Version Mismatch

   • The package is Laravel 5-only. Avoid using with Laravel 6+ without forks or compatibility layers.
   • Fix: Use a polyfill or fork the package if upgrading.

2. Seeder Timing

   • The CitiesSeeder runs after migrations. Ensure your DatabaseSeeder calls it last to avoid conflicts:

     $this->call([
         // Other seeders...
         'CitiesSeeder',
     ]);
     

3. Table Name Collisions

   • Default table name is cities. Rename if conflicts exist (publish config first):

     'table' => 'portugal_cities',
     

4. Data Updates

   • The package pulls data from a static source. To update:

     composer update laurentino-dev/laravel-portugal-cities
     php artisan migrate:fresh --seed
     

   • Tip: Backup your cities table before updates.

Debugging

1. Missing Data

   • Verify the seeder ran:

     php artisan db:seed --class=CitiesSeeder
     

   • Check for errors in storage/logs/laravel.log.

2. Facade Not Found

   • Ensure the provider and alias are registered in config/app.php.
   • Clear config cache:

     php artisan config:clear
     

3. Method Not Found

   • The facade methods are case-sensitive (districts(), not Districts()).
   • Check the source for available methods.

Tips

1. Performance

   • Index columns (district_id, concelho_id) for faster queries:

     Schema::table('cities', function (Blueprint $table) {
         $table->index('district_id');
         $table->index('concelho_id');
     });
     

2. Testing

   • Mock the facade in tests:

     $this->app->instance('Cities', Mockery::mock('overload:Cities'));
     

3. Extending Functionality

   • Add custom attributes to the Cities model (extend the seeder):

     $concelho->population = $this->generatePopulation(); // Hypothetical
     

4. Geospatial Queries

   • Add latitude/longitude to the cities table for distance-based searches:

     $nearbyConcelhos = Cities::concelhos()
         ->where('latitude', '>', $lat - 0.5)
         ->where('latitude', '<', $lat + 0.5)
         ->get();