Laravel Istat Geography Laravel Package

Product Decisions This Supports

• Build vs. buy for Italian geography data: the package ships the full ISTAT dataset (regions, provinces, municipalities) plus geography:* artisan commands for downloading/importing boundaries. That removes a multi-week data-sourcing and validation task from the roadmap and replaces it with a dependency review — a strong buy signal for any product shipping Italian addresses, delivery zones, or territorial reporting.
• Feature scoping for localization: if "Italy" is on the roadmap, this is the cheapest way to validate demand. If it isn't, this package should not enter the codebase — it is domain-specific, not a general geocoding solution.
• Multi-brand / multi-tenant architecture (v1.5.0): configurable table names and configurable model classes now actually work end-to-end. This makes it viable to install the geography tables under a prefix or per-tenant schema, and to subclass the models (e.g. adding localized accessors or scopes) with relations resolving to your classes rather than the vendor's. Previously this was a fork-or-patch decision; now it's a config decision.
• AI-assisted development velocity (v1.5.0): shipped Laravel Boost guidelines steer coding agents to use the package's models and relations instead of hallucinating their own regions/provinces tables — a recurring failure mode in agent-assisted Laravel work. laravel/boost is only suggested, so adopting the guidelines costs nothing in production dependencies.
• Upgrade/roadmap planning: Laravel 12 and 13 are the supported targets. If the product is still on Laravel 10/11, this release is not adoptable and should be scheduled behind the framework upgrade, not alongside it.
• Dependency-risk sign-off (v1.5.0): dropping the hard guzzlehttp/guzzle requirement removes a version-pin collision point in large monorepos and hands Guzzle selection back to the framework. Lowers the "will this block our next Laravel bump?" risk that PMs get asked about.

When to Consider This Package

Adopt when:

• The product has a concrete Italian-market requirement: address forms, shipping/delivery zones, territorial segmentation, or reporting by region/province/municipality.
• You are on Laravel 12 or 13, or can plan the upgrade.
• You want ISTAT codes (the canonical Italian administrative identifiers) rather than free-text city strings — this is the difference between a joinable dataset and dirty data.
• You need to customize the schema: with v1.5.0 you can set tables and models in config. Decide table names before the first migration — renaming later does not migrate existing tables, so this is a one-way setup decision that belongs in the initial architecture review, not in a later refactor.
• You extend the models. Relations now return your configured classes with unchanged foreign keys, so subclassing is supported rather than fragile.

Look elsewhere when:

• You need global coverage or geocoding/reverse-geocoding. This is Italian administrative data, not a geocoder.
• You are on Laravel 10/11 and cannot upgrade — pin an older release or defer.
• You need historical boundary changes, cadastral data, or anything ISTAT does not publish as a stable snapshot.
• Your volumes make a full municipality import undesirable and a hosted lookup service is a better fit.
• Note the tables config was previously non-functional; if you built workarounds around hardcoded table names or base model classes, audit them. The relation change is a fix, but anything that type-hinted the vendor's base classes or relied on the old table names is a silent behavior change, not a compile error. Test the relation paths before merging.

Upgrade notes for a PM to track: defaults unchanged, no new migration, so the upgrade is low risk for existing installs. The only decision requiring your attention is whether to adopt custom table/model names now — and it must be made before migrations run.

How to Pitch It (Stakeholders)

To executives: this is a small, free, well-maintained Laravel package that supplies the official Italian geography dataset — regions, provinces, and municipalities with their ISTAT codes. It converts a data-sourcing project into a dependency we can adopt in a day, and it de-risks the Italian launch by giving us canonical identifiers instead of free-text city names. The new release also lets us fit it into our existing database naming conventions and gives our AI coding assistants accurate guidance about the schema, which reduces the "agent invents its own table" class of bug. No production dependencies added; no breaking changes.

To engineering: v1.5.0 makes the tables and models config keys actually functional — relations now resolve to your configured classes with foreign keys unchanged, and the base migration uses configured table names. Set them before running migrations; changing later won't rename existing tables, and a model-level $table still overrides. Guzzle is no longer a hard requirement (it uses Laravel's Http facade), so Composer resolves Guzzle from your framework version. Laravel Boost guidelines ship in resources/boost/guidelines/core.blade.php; laravel/boost is suggested only. Requirements are Laravel 12–13. Defaults unchanged, no new migration, low-risk upgrade — but grep for hardcoded geography table names and base-class type hints from pre-1.5 workarounds.