Weave Code
Laravel Istat Geography Laravel Package
plin-code/laravel-istat-geography
Laravel package for Italian ISTAT geography data, providing regions, provinces, and municipalities (comuni) ready to use in your app. Simple Eloquent integration for addresses, filters, and location-based features.
🇮🇹 Laravel package for importing Italian geography data from ISTAT. Features daily CSV caching, Eloquent models with relationships, and Artisan commands. Supports regions, provinces, and municipalities with soft deletes and UUID primary keys.
Frequently asked questions about Laravel Istat Geography
- Which Laravel versions does plin-code/laravel-istat-geography support?
- The package targets Laravel 12 and Laravel 13, and that is the documented support matrix. Applications still on Laravel 10 or 11 should be treated as unsupported rather than probably fine, so plan an upgrade path before adopting it. Because v1.5.0 no longer requires guzzlehttp/guzzle directly, your application's Laravel version governs the Guzzle major pulled in.
- How do I install plin-code/laravel-istat-geography in a Laravel app?
- Install it with composer require plin-code/laravel-istat-geography, then run php artisan migrate to create the geography tables from the shipped base migration. No API credentials, external service, queue worker, or scheduled job are required. After migrating you get Eloquent models for regions, provinces, and municipalities (comuni) ready to relate to your own tables.
- Does the package call ISTAT on every request, or does it cache the CSV data?
- It uses daily CSV caching, so the remote ISTAT CSV files are fetched and cached rather than downloaded on every request. Data access afterwards goes through Eloquent models against your local database, which keeps lookups fast and predictable. Network access is only needed when the cache is refreshed, not for normal read paths.
- Can I change the table names used by the geography models?
- Yes, the tables config mapping is functional as of v1.5.0 and is honored by both the base migration and the models, which suits multi-tenant or legacy schemas. Set your table names before running the migration. Changing the config after migrations have run will not rename existing tables, it will just point the models at tables that do not exist.
- Can I extend the package's Eloquent models with my own classes?
- You can, but you must register your subclasses in the models config so relations resolve them. Since v1.5.0 the models config governs the concrete classes returned by provinces(), region(), municipalities(), and province(), while foreign keys stay unchanged. If you type-hint or extend a package model without registering it, you can hit instanceof or return-type mismatches at runtime rather than at boot.
- Does the package work offline or in CI without network access?
- Normal model queries work fine without network access because the geography data lives in your database. Only the CSV download and the geography:download-cap command need outbound connectivity. In CI, decide deliberately whether to run the CAP download, since it produces a 100MB-class GeoJSON artifact.
- What does the geography:download-cap Artisan command do?
- geography:download-cap fetches CAP boundary data and writes it to storage/app/cap-boundaries.geojson. It is separate from the region, province, and municipality import, so you only need it if your app uses those boundaries. Decide whether it runs in CI, at deploy time, or manually, and make sure the large artifact has a defined storage location.
- Will this package cause Composer dependency conflicts with Guzzle?
- It is much less likely since v1.5.0 removed the direct guzzlehttp/guzzle requirement. The package relies on Laravel's Http facade, which lets your application's Laravel version choose the Guzzle major (7 on Laravel 12, 7 or 8 on Laravel 13). This avoids pinning your HTTP stack and reduces the classic transitive constraint conflict during composer update.
- Does the package support UUID primary keys and soft deletes?
- Yes, the shipped models use UUID primary keys and support soft deletes on the geography records. That makes the tables easier to merge into applications that already standardize on UUIDs for their own domain models. The base migration reflects these defaults, so you can add foreign keys from your own tables without a type mismatch.
- Is upgrading from v1.4.0 safe if I already set custom tables in the config?
- Treat it carefully, because the tables config in v1.4.0 did not actually rename tables during migration. If you set custom table names and migrated under v1.4.0, your data may sit in default-named tables while the now-functional config points the models elsewhere. Write a data-migration plan before upgrading, and audit any locally extended models to confirm they are registered in the models config.
Weaver
How can I help you explore Laravel packages today?