Algerian Cities Laravel Package

Getting Started

The v4.1.2 release is a compatibility/maintenance update rather than a feature release — its headline change is Laravel 12 support, alongside PHP 8.4 CI coverage and Larastan 3.0 for static analysis. Practically: if you were blocked from upgrading to Laravel 12 because of this package's version constraint, bump kossa/algerian-cities to ^4.1.2 in composer.json and run composer update kossa/algerian-cities.

Minimal setup for a fresh install:

1. composer require kossa/algerian-cities
2. Publish the package assets (migrations and/or config): php artisan vendor:publish --tag="algerian-cities" — check config/algerian-cities.php after publishing.
3. Run migrations. The package ships a large dataset of wilayas (58 provinces) and communes, so seeding is the slow step — run it once and commit your DB dump if you can't afford re-seeding.
4. First use case: a dependent <select> for wilaya → commune in a registration or shipping address form. Wilaya::all() for the top-level dropdown, then Commune::where('wilaya_id', $id) for the dependent one.

Look first at:

• The published config file (table names, model overrides, API toggles).
• The package's migrations to confirm column names (id/code/name/wilaya_id vs daira_id) — the schema is what most integration bugs hinge on.
• The models' traits/relationships, since you'll be extending these in your own app.

Implementation Patterns

Form selects with validation. Load wilayas via a cached repository, validate the pair server-side with a scoped exists rule:

$request->validate([
    'wilaya_id' => ['required', 'exists:wilayas,id'],
    'commune_id' => [
        'required',
        Rule::exists('communes', 'id')->where('wilaya_id', $request->wilaya_id),
    ],
]);

The nested where is essential — a plain exists lets a user submit a valid commune that doesn't belong to the chosen wilaya, which is the classic address-corruption bug with this kind of data.

Cache aggressively. The dataset is static. Wrap lookups:

$wilayas = Cache::rememberForever('wilayas.all', fn () => Wilaya::orderBy('name')->get());
$communes = Cache::rememberForever("communes.{$wilayaId}", fn () => Commune::where('wilaya_id', $wilayaId)->orderBy('name')->get());

Flush these keys in your deploy script or in a custom seeder command since the dataset effectively never changes between deploys.

Extend the models rather than referencing the vendor namespace. Subclass or alias:

namespace App\Models;

use Kossa\AlgerianCities\Models\Wilaya as BaseWilaya;

class Wilaya extends BaseWilaya
{
    public function addresses() { return $this->hasMany(Address::class); }
}

Then override the model class in the published config so package internals (API controllers, relations) use your subclass.

API consumption. If the package exposes routes, keep them behind a rate-limited group and version the endpoint in your own route file (/api/v1/wilayas) so a vendor route rename doesn't break consumers. If your frontend is a livewire/vue app, serialize the wilaya→commune structure once at boot as a single JSON payload rather than N requests.

Migration strategy in tests. Re-seeding the full dataset per test case is prohibitively slow. In TestCase, either seed once via a trait and use transactions, or use a tiny fixture set of 2–3 wilayas — the package's relationship logic doesn't care about dataset size.

Gotchas and Tips

• The Laravel 12 constraint is the only real signal in v4.1.2. The CI/Pint/dependabot bumps are invisible to you. Confirm in the package's composer.json that Laravel 12 is actually in the illuminate/* constraint before planning an upgrade; if your app is on Laravel 11 or older, there is nothing in this release you need.
• PHP 8.4 CI coverage does not mean PHP 8.4 is your production target. The workflow additions prove the package compiles on 8.4; if you're on 8.2 with larastan ^3.0 in your own app, be aware the package now assumes Larastan 3.x — mixing Larastan 2.x in a monorepo can produce conflicting dependency resolutions.
• Naming is the #1 source of confusion. "Wilaya" = province, "Daira" = district, "Commune"/"Baladiya" = municipality. The French/Arabic transliteration can differ between the DB, the config, and the column names. Read the actual migration before writing whereHas('daira').
• Dataset drift. Algeria has had administrative changes over the years (new wilayas added; the count moved from 48 to 58). Pin the package version in composer.lock and diff the seed data between upgrades if you expose wilaya lists to end users; an ID shift can silently re-map stored addresses.
• vendor:publish tag collisions. If you've published the migrations, later package migration updates won't apply automatically. Keep a note in your upgrade runbook to re-publish on minor version bumps.
• Seeder performance. Bulk-insert the commune data or wrap in a transaction with disableForeignKeyConstraints(); a naive per-row migration can take minutes on shared hosting.
• Testing pitfall. RefreshDatabase will drop the seeded tables between tests. Use DatabaseTransactions for tests that need the dataset, and a separate trait for fixture-seeded schema tests.
• Extension point: if you need extra attributes (postal codes, geo coordinates), prefer a side table keyed on the wilaya/commune code over editing the vendor migrations — that survives upgrades cleanly.

Upgrade checklist for this release: bump to ^4.1.2, run composer update, run your static analyser (Larastan 3 expects stricter typing — watch for new errors in code that touches these models), and smoke-test the form flows and any cached lookup keys.