Laravel Istat Geography Laravel Package

Technical Evaluation

Architecture fit. plin-code/laravel-istat-geography is a data-domain package: it ships ISTAT geography reference data (regions, provinces, municipalities) as Eloquent models plus a base migration, and exposes artisan commands under the geography:* namespace (notably geography:download-cap, which writes storage/app/cap-boundaries.geojson). Architecturally this is a low-coupling fit for any Laravel application that needs Italian administrative hierarchy as a first-class relational model rather than a hardcoded lookup table. The v1.5.0 release materially improves fit for two audiences: (a) teams running multi-tenant or legacy schemas, via the now-functional tables config mapping; and (b) teams using AI-assisted development, via Laravel Boost guidelines that steer agents toward the package's models instead of generating competing geography tables. The latter is a genuine differentiator for TPMs shipping with agentic tooling in the loop.

Integration feasibility. High. Installation is a composer require plus php artisan migrate; no external service, no credentials, no queue worker, no scheduled job is implied. The v1.5.0 change removing the direct guzzlehttp/guzzle requirement reduces the dependency footprint to Laravel's Http facade and lets the host application's Laravel version govern the Guzzle major (7 on Laravel 12, 7 or 8 on Laravel 13) — this eliminates a classic transitive-constraint conflict during composer update and lowers the chance of the package pinning the app's HTTP stack. The Laravel 12/13 requirement is the single meaningful gate: applications on Laravel 10 or 11 fall outside the documented support matrix and should be treated as unsupported rather than "probably fine."

Technical risk. Moderate, concentrated in two areas. First, the tables config fix is a configuration-ordering hazard: the base migration and models now honor configured table names, but changing the config after migrations have run will not rename existing tables — it will simply cause the models to query tables that do not exist. This is not a breaking change in the semver sense (defaults unchanged, no new migration) but it is a breaking change in behavior for anyone who set tables in v1.4.0 expecting a rename that never happened, then migrated. Those applications may now have data in default-named tables with models pointed elsewhere. Second, the models config now governs the concrete classes returned by provinces(), region(), municipalities(), and province() while foreign keys are unchanged. Any app that type-hinted the package's concrete classes, or that extended a package model without registering it under models, can hit instanceof and return-type mismatches at runtime rather than at boot. Both risks are silent — they surface as query errors or type errors in feature paths, not as install failures.

Key questions.

• Which Laravel versions are actually in our fleet today, and does any app sit on 10/11 with no near-term upgrade path?
• Did any application set tables in config under v1.4.0 and migrate against it? If so, we need a data-migration plan before upgrading, not after.
• Do we extend any of the geography models locally? If yes, are those subclasses registered in models so relations resolve correctly?
• Is Laravel Boost in use or planned? If not, the guidelines file is inert but harmless; if yes, it is worth validating that agents actually honor it.
• What is our stance on the CAP GeoJSON import — is geography:download-cap run in CI, at deploy, or manually, and where does that 100MB-class artifact live?

Integration Approach

Stack fit. The package assumes Laravel 12 or 13, PHP with Eloquent, and a relational database that supports the shipped base migration. It fits cleanly as a read-mostly reference-data layer beneath any domain model that needs region/province/municipality foreign keys — addresses, shipping zones, tax jurisdictions, user profiles, store locators. It does not fit applications needing real-time ISTAT updates or non-Italian geographies; the dataset is bundled and command-refreshed, not synchronized.

Migration path. Treat v1.5.0 as a low-drama upgrade with two pre-flight checks. (1) Run php artisan vendor:publish review and diff the published config against the package default before touching the database — if tables was previously customised and migrations already ran, resolve the naming mismatch manually with explicit RENAME TABLE statements rather than expecting the package to do it. (2) Grep the codebase for direct references to the package's model classes and for any local subclasses, and reconcile against the models config. Beyond that, the upgrade is composer update plin-code/laravel-istat-geography with no new migration and no default changes — which means it is safe to land as a routine dependency bump in a normal sprint.

Compatibility. Verify the host app's Guzzle resolution after the bump. Because the package no longer requires Guzzle directly, whichever version Laravel pulls becomes authoritative; on Laravel 13 that can be Guzzle 8, which may conflict with other packages still pinning ^7.0. This is a reduction in the package's own coupling but a potential shift in the app's resolved graph — worth a composer why guzzlehttp/guzzle check and one integration test hitting any outbound HTTP path that shares the client.

Sequencing.

1. Inventory Laravel versions and Guzzle resolution across affected apps.
2. Audit tables and models config usage and any model subclassing.
3. Upgrade in a non-production environment; run migrations from scratch on a clean database and run the upgrade path on a restored production-shaped database — both, because the two paths exercise different failure modes.
4. Exercise each geography:* command, including --help on download-cap to confirm the corrected default path.
5. Promote; defer the optional Boost guidelines adoption to a separate, non-blocking change.

Operational Impact

Maintenance. Low steady-state burden. The package is reference data plus a migration; there is no daemon, no cron, no queue. The main recurring task is refreshing the underlying ISTAT dataset when upstream publishes changes — that is a deliberate, scheduled exercise (re-run the geography commands, diff row counts, re-import), not passive drift. The Boost guidelines file adds a small ongoing maintenance obligation only if we adopt Boost: it lives in resources/boost/guidelines/ and should be reviewed when we bump the package, since it encodes command and config knowledge that can go stale.

Support. Support surface is small and well-bounded: the package's own commands and config, plus the seam where our models reference its models. The documentation correction in this release (Laravel 12/13, real download-cap default path) reduces a known source of support tickets — the previous README pointed at the wrong GeoJSON path, which would have produced "import succeeded but file not found" reports. That is a quiet but real reduction in first-line support load.

Scaling. The dataset scales fine for typical use; municipalities number in the thousands, which is trivial for indexed lookups. Two caveats. First, the CAP GeoJSON boundary file is a large single artifact written to storage/app/ — do not place it on a shared network volume read by every web node during requests, and do not run the download command per-node in a horizontally scaled deploy. Fetch once, distribute as a build artifact. Second, seeding/importing the full dataset during deploys adds time; prefer migrating the schema at deploy and importing data as a one-time or versioned step.

Failure modes. (a) Table config drift — models query configured table names that do not exist because the config was changed post-migration; symptom is a hard SQL error on any geography relation, discovered at request time. Mitigate with a smoke test that touches one relation per model. (b) Model substitution mismatch — relations return configured classes with unchanged foreign keys, so an incompletely migrated models config yields type errors or wrong-class hydration. Mitigate by asserting instanceof in tests for each relation. (c) Dependency graph shift — Guzzle resolution changes under us on Laravel 13, surfacing as a conflict in an unrelated HTTP-integrating package. Mitigate with a CI composer validate and one outbound-HTTP integration test. (d) Stale boundary data — CAP GeoJSON downloaded once and never refreshed; silent accuracy decay rather than an error. Mitigate by recording the download date and reviewing annually.

Ramp-up. Effectively zero for a Laravel-fluent engineer: read the README, publish config, migrate, use the models. The non-obvious knowledge — that table names are frozen at migration time, and that relations resolve through models — should be captured in an ADR or a two-paragraph internal runbook rather than left in the release notes. Budget roughly half a day for the first integration including the config and model audit, and under an hour for subsequent apps on the same stack. The Boost guidelines are a nice accelerator if the team already uses agentic tooling and a distraction if not; scope them as optional.