Administrative Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require lcjury/administrative
   

   Add the provider to config/app.php:

   'providers' => [
       Lcjury\Administrative\AdministrativeServiceProvider::class,
   ],
   

2. Generate Administrative Structure Run the scaffold command:

   php artisan make:administrative
   

   This creates:

   • Models (Region, Province, Commune)
   • Migrations (regions, provinces, communes)
   • Seeders (pre-populated with Chile data by default)

3. Seed the Database Update database/seeders/DatabaseSeeder.php:

   public function run()
   {
       $this->call(PoliticalTablesSeeder::class);
   }
   

   Run migrations and seed:

   php artisan migrate --seed
   

First Use Case

Display a Commune Hierarchy

// In a controller or blade view
$regions = \App\Models\Region::with('provinces.communes')->get();

Use this to render dropdowns or nested structures (e.g., for location selectors).

Implementation Patterns

Core Workflows

1. Hierarchical Data Access Define relationships in models (auto-generated by the package):

   // Example: Region.php
   public function provinces()
   {
       return $this->hasMany(Province::class);
   }
   

   Use eager loading to avoid N+1 queries:

   $region = Region::with('provinces.communes')->find(1);
   

2. Customizing for Other Countries Override the seeder or extend the package:

   • Copy PoliticalTablesSeeder to database/seeders/CustomCountrySeeder.
   • Replace the call() in DatabaseSeeder.php with your custom seeder.
   • Manually add data via migrations or API calls (e.g., scrape government sources).

3. Validation and Forms Use the models for form validation (e.g., Laravel’s FormRequest):

   public function rules()
   {
       return [
           'region_id' => 'required|exists:regions,id',
           'province_id' => 'required|exists:provinces,id',
           'commune_id' => 'required|exists:communes,id',
       ];
   }
   

4. API Responses Serialize hierarchical data for APIs:

   return Region::with(['provinces.communes' => function($query) {
       $query->select('id', 'name'); // Limit fields
   }])->get();
   

Integration Tips

• Laravel Scout: Index communes for search:

  class Commune extends Model
  {
      use \Laravel\Scout\Searchable;
  }
  

• Laravel Nova: Display hierarchical data in a custom card or detail view.
• Frontend Frameworks: Use Vue/React to render nested select components (e.g., vue-select with async data).

Gotchas and Tips

Pitfalls

1. Hardcoded Country Data

   • The package only seeds Chile by default. For other countries:
     • Manually edit the seeder or write a custom one.
     • Check if the package supports updates (none yet; star the repo to encourage maintenance).
   • Workaround: Use the migrations as a template and populate via API (e.g., RESTCountries).

2. Migration Conflicts

   • If you’ve already created regions/provinces tables, the package’s migrations will fail.
   • Solution: Rename existing tables or drop them before running make:administrative.

3. Relationship Assumptions

   • The package assumes a strict Region → Province → Commune hierarchy. Customize if your country uses a different structure (e.g., states/districts).
   • Fix: Extend the models or use traits to override relationships.

4. Seeder Overwrites

   • Running php artisan db:seed repeatedly will overwrite existing data.
   • Tip: Use --class=CustomSeeder or conditionally insert data in the seeder.

Debugging

• Missing Data: Verify the seeder ran:

  php artisan db:seed --class=PoliticalTablesSeeder
  

• Relationship Errors: Check foreign keys in migrations (e.g., province_id in communes table).
• Package Updates: Monitor the repo for breaking changes (currently at ^0.0.0).

Extension Points

1. Add Custom Fields Extend the migrations or models:

   // app/Models/Province.php
   protected $fillable = ['name', 'code', 'custom_field'];
   

   Update the seeder to include new fields.

2. Localization Store translated names in a localizations table and use Laravel’s localize() or a package like spatie/laravel-translatable.

3. Geospatial Data Add latitude/longitude to communes and use spatie/laravel-geotools for distance queries:

   class Commune extends Model
   {
       use \Spatie\Geo\HasGeoCoordinates;
   }
   

4. Soft Deletes Enable soft deletes in models:

   use \Illuminate\Database\Eloquent\SoftDeletes;
   protected $dates = ['deleted_at'];
   

   Update migrations to add deleted_at columns.

Performance

• Index Foreign Keys: Add indexes to region_id, province_id in migrations for faster joins.
• Caching: Cache hierarchical data if frequently accessed:

  $regions = Cache::remember('regions.hierarchy', now()->addHours(1), function() {
      return Region::with('provinces.communes')->get();
  });