Laravel Id Provinces Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require ferdirn/laravel-id-provinces:dev-master
   

   Update dependencies:

   composer update
   

2. Register Provider & Facade Add to config/app.php under providers:

   Ferdirn\Provinces\ProvincesServiceProvider::class,
   

   Add to aliases:

   'Provinces' => Ferdirn\Provinces\ProvincesFacade::class,
   

3. Publish Configuration (Optional)

   php artisan vendor:publish --provider="Ferdirn\Provinces\ProvincesServiceProvider"
   

   Config file will be published to config/provinces.php.

4. First Use Case Fetch all provinces in a controller or service:

   use Provinces;
   
   $provinces = Provinces::all();
   return response()->json($provinces);
   

   Or use the facade directly:

   $jakarta = Provinces::findByName('DKI Jakarta');
   

Implementation Patterns

Core Workflows

1. Fetching Provinces

   • All Provinces: Provinces::all() returns a collection of all provinces with attributes: id, name, country_code, capital, and area.
   • Single Province by ID: Provinces::find($id).
   • Single Province by Name: Provinces::findByName('Name') (case-insensitive).

2. Integration with Eloquent Models Add a province_id foreign key to a model (e.g., User, Address) and use the facade to validate or fetch province data:

   use Provinces;
   
   public function store(Request $request)
   {
       $validated = $request->validate([
           'province_id' => 'required|exists:provinces,id',
       ]);
   
       $province = Provinces::find($validated['province_id']);
       // Use $province->name, $province->capital, etc.
   }
   

3. Dynamic Data in Views Cache province data in a service provider for reuse:

   // In a service provider's boot method
   view()->share('provinces', Provinces::all()->pluck('name', 'id'));
   

   Then use in Blade:

   <select name="province_id">
       @foreach ($provinces as $id => $name)
           <option value="{{ $id }}">{{ $name }}</option>
       @endforeach
   </select>
   

4. API Responses Return province data in API responses:

   return response()->json([
       'province' => Provinces::find($request->province_id),
   ]);
   

5. Localization Extend the package by publishing the config and customizing province names/capitals for localized apps:

   // config/provinces.php
   'custom_names' => [
       'DKI Jakarta' => 'Jakarta Raya',
   ],
   

Gotchas and Tips

Pitfalls

1. Dev-Master Dependency The package is in dev-master state. Pin the version in composer.json to avoid unexpected updates:

   "ferdirn/laravel-id-provinces": "dev-master as 1.0.0"
   

2. Case Sensitivity in findByName The findByName method is case-insensitive but may return unexpected results if the input has extra spaces or typos. Trim and sanitize inputs:

   $province = Provinces::findByName(trim($request->province_name));
   

3. Database Migration Conflicts If you manually create a provinces table, the package’s migrations will fail. Either:

   • Skip migrations by setting 'migrate' => false in config/provinces.php.
   • Drop the table and let the package migrate it.

4. Facade vs. Service Container Avoid instantiating the Provinces class directly. Always use the facade (Provinces::) or resolve via the container (app(Provinces::class)) for consistency.

Debugging

1. Check Published Config If provinces aren’t loading, verify config/provinces.php exists and is correctly configured. Default values may override custom settings.

2. Data Integrity Validate province data by dumping a sample:

   dd(Provinces::all()->first());
   

   Ensure id, name, country_code, capital, and area are present.

3. Service Provider Binding If the facade throws Class not found, ensure the ProvincesServiceProvider is registered in config/app.php after Laravel’s core providers.

Extension Points

1. Custom Province Attributes Extend the Province model (published at app/Province.php after publishing) to add methods:

   // app/Province.php
   public function isCapital()
   {
       return $this->capital === $this->name;
   }
   

2. Override Data Source Replace the default provinces data by binding a custom collection in a service provider:

   $this->app->bind('provinces', function () {
       return collect([/* custom provinces */]);
   });
   

3. Add Cities or Districts Pair this package with ferdirn/laravel-id-cities (if available) or create a similar package for cities/districts to build a hierarchical location system.

4. Caching Cache province data in a service provider to reduce database queries:

   $this->app->singleton('provinces', function () {
       return Cache::remember('provinces', now()->addDays(30), function () {
           return Provinces::all();
       });
   });
   

5. Testing Mock the facade in tests:

   Provinces::shouldReceive('findByName')->once()->andReturn($mockProvince);