Download the PHP package plin-code/laravel-istat-geography without Composer

Laravel ISTAT Geography

A Laravel package for importing and managing Italian geographical data from ISTAT.

Features

• 🇮🇹 Import Italian regions, provinces, and municipalities from ISTAT
• 📮 Import Italian postal codes (CAP) with support for multi-CAP municipalities
• 🔄 Incremental updates: add new records, update changes, soft-delete removed ones
• 📊 Daily CSV caching to avoid unnecessary requests
• 🔗 Eloquent models with hierarchical relationships
• ⚡ Artisan commands for easy data import and synchronization
• 🔧 Fully configurable via configuration file
• 🆔 UUID primary keys and soft deletes support
• 🧪 Comprehensive test suite with mocked HTTP requests

Requirements

• PHP 8.3+
• Laravel 11.0+ or 12.0+
• league/csv 9.0+
• guzzlehttp/guzzle 7.0+

Installation

Quick Start

1. Install the package:

2. Publish the configuration:

3. Run migrations:

4. Import the data:

That's it! You now have all Italian geographical data in your database.

Commands

geography:import

Performs a full import of all geographical data from ISTAT. Use this for the initial data load.

Options

Examples

Note: The remote GeoJSON with geometries is ~464MB. Using --cap-file with a preprocessed JSON file (~3MB) is recommended for better performance.

geography:download-cap

Downloads CAP GeoJSON data and saves it locally for offline import. Useful when you want to download once and import multiple times.

After downloading, import with:

geography:update

Incrementally synchronizes your database with the latest ISTAT data. It compares the current ISTAT CSV against your existing records and applies only the differences: new records are added, changed records are updated, and records no longer present in ISTAT are soft-deleted.

Options

Verbosity Levels

Examples

All database operations are wrapped in a transaction. If any error occurs (and --force is not set), all changes are automatically rolled back.

Configuration

Publish the configuration file:

The config/istat-geography.php file allows you to customize:

• Table names: Customize the database table names
• Model classes: Use your own model classes by extending the base ones
• CSV URL: Change the ISTAT data source URL (also via ISTAT_CSV_URL env)
• CAP GeoJSON URL: Change the CAP data source URL (also via CAP_GEOJSON_URL env)
• Temporary file name: Customize the cache file name

Example Configuration

Models

The package provides three Eloquent models:

Region

Province

Municipality

ISTAT Fields

Each model exposes a static istatFields() method that returns the list of fields managed by ISTAT data. These are the fields that the geography:update command is allowed to overwrite. Any additional fields you add to your extended models will not be touched during updates.

Extending Models

If you want to use the package models in your main project, you can extend them:

Remember to update the models section in the configuration file to point to your custom classes.

Database Structure

Regions

• id (UUID, primary key)
• name (string)
• istat_code (string, unique)
• created_at, updated_at, deleted_at

Provinces

• id (UUID, primary key)
• region_id (UUID, foreign key)
• name (string)
• code (string, unique)
• istat_code (string, unique)
• created_at, updated_at, deleted_at

Municipalities

• id (UUID, primary key)
• province_id (UUID, foreign key)
• name (string)
• istat_code (string, unique)
• bel_code (string, nullable) - Cadastral/Belfiore code for CAP matching
• postal_code (string, nullable) - Primary postal code (CAP)
• postal_codes (string, nullable) - Range of postal codes for large municipalities (e.g., "00118-00199")
• created_at, updated_at, deleted_at

Relationships

• Region → hasMany → Province
• Province → belongsTo → Region
• Province → hasMany → Municipality
• Municipality → belongsTo → Province

Replacing Existing Command

If you already have a geography:import command in your project, you can replace it with the package's command:

Testing

Run the test suite:

The package includes:

• ✅ Unit tests for models and relationships
• ✅ Feature tests for the import service
• ✅ Feature tests for the update command and services
• ✅ Mocked HTTP requests (no external dependencies)
• ✅ PHPStan static analysis
• ✅ Pest PHP testing framework

Test Coverage

• Models and their relationships
• Import service with CSV processing
• Compare service for detecting changes
• Update service for applying changes
• Artisan command functionality (import and update)
• Configuration handling

Data Sources

ISTAT Data

Geographic data (regions, provinces, municipalities) is sourced from ISTAT (Italian National Institute of Statistics), the official Italian government statistics agency.

Postal Codes (CAP)

Postal code data is sourced from Zornade Data Downloads.

A huge thanks to Zornade for their incredible work in making Italian public data freely available. Their dedication to open data helps developers build better applications for Italian users.

Contributing

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

The MIT License (MIT). Please see License File for more information.