Getting Started

Minimal Setup

Installation:

composer require sidm/laravel-subdivisions

Add to config/app.php:

'providers' => [
    Sidm\Subdivisions\SubdivisionsServiceProvider::class,
],
'aliases' => [
    'Subdivisions' => Sidm\Subdivisions\SubdivisionsFacade::class,
],

Publish config (if needed):

php artisan vendor:publish --provider="Sidm\Subdivisions\SubdivisionsServiceProvider"

First Use Case: Fetch all subdivisions for a country (e.g., US states):

$states = Subdivisions::getSubdivisions('US');

Or fetch a single subdivision:

$california = Subdivisions::getSubdivision('US', 'CA');

Database Migration: Run the included migration to store subdivisions in your DB:
```
php artisan migrate
```
(Ensure subdivisions table exists or matches the schema.)

Implementation Patterns

Common Workflows

Country-Specific Dropdowns: Dynamically populate a Blade dropdown for a country’s subdivisions:

// In Controller
$countryCode = request('country');
$subdivisions = Subdivisions::getSubdivisions($countryCode);

// In Blade
<select name="subdivision">
    @foreach($subdivisions as $subdivision)
        <option value="{{ $subdivision->code }}">{{ $subdivision->name }}</option>
    @endforeach
</select>

Validation Rules: Use the package’s validation logic:

use Sidm\Subdivisions\Rules\Subdivision;

$validator = Validator::make($request->all(), [
    'subdivision' => ['required', new Subdivision('US')],
]);

Caching Subdivisions: Cache subdivisions for performance (e.g., in AppServiceProvider):

public function boot()
{
    Cache::rememberForever('subdivisions.US', function () {
        return Subdivisions::getSubdivisions('US');
    });
}

API Responses: Return subdivisions as JSON:

return response()->json([
    'subdivisions' => Subdivisions::getSubdivisions('CA'),
]);

Form Requests: Extend FormRequest to validate subdivisions:

public function rules()
{
    return [
        'subdivision' => ['required', new Subdivision($this->countryCode)],
    ];
}

Integration Tips

Localization: Override subdivision names in your language files (e.g., lang/en/subdivisions.php) for custom translations. Example:
```
return [
    'US' => [
        'CA' => 'California (Custom Name)',
    ],
];
```

Custom Queries: Use the underlying Subdivision model to query the DB directly:

$subdivisions = \Sidm\Subdivisions\Models\Subdivision::where('country_code', 'US')->get();

Laravel Nova: Add a custom field for subdivisions in Nova resources:

use Sidm\Subdivisions\Nova\SubdivisionField;

SubdivisionField::make('State', 'state_code'),

Testing: Mock subdivisions in tests:

$this->app->instance(
    \Sidm\Subdivisions\SubdivisionsInterface::class,
    Mockery::mock(\Sidm\Subdivisions\SubdivisionsInterface::class)
        ->shouldReceive('getSubdivisions')
        ->andReturn([...])
        ->getMock()
);

Gotchas and Tips

Pitfalls

Laravel 4.2 Dependency:
- The package is not compatible with Laravel 5+. Use alternatives like laravel-countries or league/iso3166 for newer Laravel versions.
- Workaround: Fork the package and update dependencies if you must use it in Laravel 5/6/7/8.
Database Schema Mismatch:
- The migration expects a subdivisions table with columns: id, country_code, code, name, type. Verify your DB schema matches.
- Fix: Run php artisan vendor:publish --tag=migrations and adjust the migration if needed.
Caching Issues:
- Subdivisions are cached aggressively. Clear cache after updates:
```
php artisan cache:clear
php artisan config:clear
```
Country Code Sensitivity:
- Country codes (e.g., US, CA) are case-sensitive. Always use uppercase.
- Tip: Normalize input:
```
$countryCode = strtoupper($request->input('country'));
```
Missing Subdivisions:
- Some countries (e.g., microstates) may lack subdivisions in the dataset.
- Solution: Extend the Subdivisions facade or manually add missing entries via the DB.

Facade vs. Service Container:

Prefer dependency injection over the facade for better testability:

// Bad: Using facade
$subdivisions = Subdivisions::getSubdivisions('US');

// Good: Inject the service
public function __construct(Sidm\Subdivisions\SubdivisionsInterface $subdivisions) {
    $this->subdivisions = $subdivisions;
}

Debugging Tips

Check Data Existence: Verify subdivisions exist for a country:

dd(Subdivisions::getSubdivisions('XX')); // Replace 'XX' with your country code

Log Queries: Enable query logging in config/database.php:
```
'logging' => true,
```
Then check Laravel logs for SQL queries.

Override Data: Temporarily override subdivision data in app/Providers/AppServiceProvider.php:

public function boot()
{
    $this->app->singleton(\Sidm\Subdivisions\SubdivisionsInterface::class, function () {
        return new class {
            public function getSubdivisions($countryCode) {
                return collect([...]); // Return custom data
            }
        };
    });
}

Extension Points

Custom Subdivision Types: Extend the Subdivision model to add custom fields:
```
php artisan make:model CustomSubdivision --extends="Sidm\Subdivisions\Models\Subdivision"
```
Then update the migration and facade logic.

API Endpoints: Create a controller to expose subdivisions via API:

Route::get('/api/subdivisions/{country}', [SubdivisionController::class, 'index']);

// SubdivisionController.php
public function index($country)
{
    return Subdivisions::getSubdivisions($country);
}

Webhooks/Updates: Listen for subdivision updates (e.g., via a cron job) and refresh the DB:
```
php artisan subdivisions:update
```
(Note: The package may not include this command; implement manually.)

Frontend Integration: Use JavaScript to fetch subdivisions dynamically:

fetch(`/api/subdivisions/${countryCode}`)
    .then(response => response.json())
    .then(subdivisions => {
        subdivisions.forEach(sub => {
            // Populate dropdown
        });
    });

Laravel Subdivisions Laravel Package