Freguesias Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require luismarcelino/freguesias:dev-master
   

   Add to config/app.php:

   'providers' => [
       Luismarcelino\Freguesias\FreguesiasServiceProvider::class,
   ],
   'aliases' => [
       'Freguesias' => Luismarcelino\Freguesias\FreguesiasFacade::class,
   ]
   

2. Database Setup Run the migration and seeder:

   php artisan freguesias:migration
   php artisan migrate:refresh
   php artisan db:seed --class=FreguesiasSeeder
   

3. First Use Case Fetch all freguesias (parishes) in a district:

   $district = Freguesias::findDistrict('Lisboa');
   $freguesias = $district->freguesias;
   

Implementation Patterns

Core Workflows

1. Hierarchical Data Access Retrieve nested structures (district → concelho → freguesia):

   $concelho = Freguesias::findConcelho('Lisboa', 'Lisboa'); // District, Concelho name
   $freguesias = $concelho->freguesias;
   

2. Filtering by Attributes Use Eloquent query builder for dynamic filtering:

   $freguesias = Freguesias::where('district', 'Porto')->get();
   

3. Integration with Forms Populate dropdowns for multi-level selects:

   $districts = Freguesias::districts()->pluck('name', 'id');
   $concelhos = Freguesias::concelhos('Porto')->pluck('name', 'id');
   

Common Use Cases

• Address Validation Check if a postal code belongs to a valid freguesia:

  $freguesia = Freguesias::where('postal_code', '1200-123')->first();
  

• Geospatial Queries Find freguesias near a coordinate (requires spatial DB setup):

  $freguesias = Freguesias::whereRaw("ST_DWithin(geometry, ST_MakePoint(?, ?), 10000, true)", [-9.136, 38.722]);
  

• API Responses Serialize hierarchical data for frontend:

  return response()->json(Freguesias::all()->toTree());
  

Gotchas and Tips

Pitfalls

1. Database Schema Assumptions

   • The package assumes a default table name (freguesias). Customize via config:

     'table' => 'custom_freguesias_table',
     

   • Gotcha: Running migrate:refresh without the seeder will leave the table empty.

2. Data Integrity

   • Postal codes may not be unique across freguesias. Validate with:

     $freguesias = Freguesias::where('postal_code', 'LIKE', '1200%')->get();
     

3. Performance

   • Avoid eager-loading entire hierarchies in loops. Use lazy loading:

     foreach (Freguesias::districts()->cursor() as $district) {
         $district->concelhos()->with(['freguesias' => function($q) {
             $q->limit(10);
         }])->get();
     }
     

Debugging Tips

• Missing Data? Verify the seeder ran:

  php artisan db:seed --class=FreguesiasSeeder --force
  

• Query Issues Enable query logging in config/database.php:

  'logging' => true,
  

  Then check storage/logs/laravel.log.

Extension Points

1. Custom Fields Extend the Freguesia model:

   namespace App\Models;
   use Luismarcelino\Freguesias\Models\Freguesia as BaseFreguesia;
   
   class Freguesia extends BaseFreguesia {
       protected $appends = ['full_name'];
       public function getFullNameAttribute() {
           return "{$this->concelho->name}, {$this->name}";
       }
   }
   

2. Local Overrides Publish and modify the seeder to add custom freguesias:

   php artisan vendor:publish --tag=freguesias-seeders
   

3. API Endpoints Create a controller to expose filtered data:

   Route::get('/api/freguesias', function () {
       return Freguesias::where('district', request('district'))
           ->with('concelho')
           ->get();
   });