plin-code/laravel-istat-geography

Laravel package for importing and managing Italian geography data from ISTAT

v1.0.1 2025-08-07 13:17 UTC

Requires

• php: ^8.3
• guzzlehttp/guzzle: ^7.0
• illuminate/contracts: ^12.0
• league/csv: ^9.24
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9||^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/extension-installer: ^1.3
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0

MIT

• Daniele Barbaro

• geography
• laravel
• countries
• regions
• provinces
• italy
• municipalities
• istat
• PlinCode

README

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

Features

• 🇮🇹 Import Italian regions, provinces, and municipalities from ISTAT
• 📊 Daily CSV caching to avoid unnecessary requests
• 🔗 Eloquent models with hierarchical relationships
• ⚡ Artisan command for easy data import
• 🔧 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

composer require plin-code/laravel-istat-geography

Quick Start

1. Install the package:

composer require plin-code/laravel-istat-geography

1. Publish the configuration:

php artisan vendor:publish --provider="PlinCode\IstatGeography\IstatGeographyServiceProvider"

1. Run migrations:

php artisan migrate

1. Import the data:

php artisan geography:import

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

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="PlinCode\IstatGeography\IstatGeographyServiceProvider"

Migrations

Run the migrations to create the necessary tables:

php artisan migrate

Usage

Data Import

To import all geographical data from ISTAT:

php artisan geography:import

Models

The package provides three Eloquent models:

Region

use PlinCode\IstatGeography\Models\Geography\Region;

$region = Region::where('name', 'Piemonte')->first();
$provinces = $region->provinces;

Province

use PlinCode\IstatGeography\Models\Geography\Province;

$province = Province::where('code', 'TO')->first();
$municipalities = $province->municipalities;
$region = $province->region;

Municipality

use PlinCode\IstatGeography\Models\Geography\Municipality;

$municipality = Municipality::where('name', 'Torino')->first();
$province = $municipality->province;

Integration Example in Main Project

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

// app/Models/Region.php
namespace App\Models;

use PlinCode\IstatGeography\Models\Geography\Region as BaseRegion;

class Region extends BaseRegion
{
    // Add your project-specific logic here
    public function customMethod()
    {
        return $this->provinces()->count();
    }
}

// app/Models/Province.php
namespace App\Models;

use PlinCode\IstatGeography\Models\Geography\Province as BaseProvince;

class Province extends BaseProvince
{
    // Add your project-specific logic here
}

// app/Models/Municipality.php
namespace App\Models;

use PlinCode\IstatGeography\Models\Geography\Municipality as BaseMunicipality;

class Municipality extends BaseMunicipality
{
    // Add your project-specific logic here
}

Replacing Existing Command

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

// In app/Console/Kernel.php or in your existing command
Artisan::command('geography:import', function () {
    $this->info('Starting geographical data import...');

    try {
        $count = \PlinCode\IstatGeography\Facades\IstatGeography::import();
        $this->info("Import completed successfully! Imported {$count} municipalities.");
    } catch (\Exception $e) {
        $this->error('Error during import: ' . $e->getMessage());
    }
})->purpose('Import regions, provinces and municipalities from ISTAT');

Configuration

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
• Temporary file name: Customize the cache file name

Example Configuration

return [
    'tables' => [
        'regions' => 'my_regions',
        'provinces' => 'my_provinces', 
        'municipalities' => 'my_municipalities',
    ],
    'models' => [
        'region' => \App\Models\Region::class,
        'province' => \App\Models\Province::class,
        'municipality' => \App\Models\Municipality::class,
    ],
    'import' => [
        'csv_url' => 'https://custom-url.com/data.csv',
        'temp_filename' => 'my_istat_data.csv',
    ],
];

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)
• created_at, updated_at, deleted_at

Relationships

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

Testing

Run the test suite:

composer test

The package includes:

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

Test Coverage

• Models and their relationships
• Import service with CSV processing
• Artisan command functionality
• Configuration handling

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.