README

A Laravel package for importing and managing foreign countries data from ISTAT (Italian National Institute of Statistics).

Features

• ???? Import continents, geographical areas, and foreign countries from ISTAT
• ???? Eloquent models with hierarchical relationships
• ⚡ Artisan command for easy data import
• ???? Fully configurable via configuration file
• ???? UUID primary keys and soft deletes support
• ????️ Multiple coding standards support (ISTAT, ISO, MIN, AT)

Requirements

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

Installation

composer require plin-code/laravel-istat-foreign-countries

Quick Start

1. Install the package:

composer require plin-code/laravel-istat-foreign-countries

1. Publish the configuration:

php artisan vendor:publish --provider="PlinCode\IstatForeignCountries\IstatForeignCountriesServiceProvider"

1. Run migrations:

php artisan migrate

1. Import the data:

php artisan foreign-countries:import

That's it! You now have all foreign countries data in your database.

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="PlinCode\IstatForeignCountries\IstatForeignCountriesServiceProvider"

Usage

Data Import

To import all foreign countries data from ISTAT:

php artisan foreign-countries:import

Models

The package provides three Eloquent models:

Continent

use PlinCode\IstatForeignCountries\Models\ForeignCountries\Continent; $continent = Continent::where('name', 'Europa')->first(); $areas = $continent->areas; $countries = $continent->countries;

Area

use PlinCode\IstatForeignCountries\Models\ForeignCountries\Area; $area = Area::where('name', 'Unione europea')->first(); $countries = $area->countries; $continent = $area->continent;

Country

use PlinCode\IstatForeignCountries\Models\ForeignCountries\Country; // Find by ISO alpha2 $country = Country::where('iso_alpha2', 'FR')->first(); // Find by ISO alpha3 $country = Country::where('iso_alpha3', 'FRA')->first(); // Find by ISTAT code $country = Country::where('istat_code', '215')->first(); // Access relationships $continent = $country->continent; $area = $country->area; // Check type if ($country->isState()) { echo "This is a state"; } if ($country->isTerritory()) { echo "This is a territory"; $parent = $country->parentCountry; } // Get territories of a country $france = Country::where('iso_alpha2', 'FR')->first(); $territories = $france->territories;

Facade Usage

use PlinCode\IstatForeignCountries\Facades\IstatForeignCountries; // Import data programmatically $count = IstatForeignCountries::import();

Available Codes

Each country includes multiple international coding standards:

• ISTAT Code: Italian statistical code
• ISO Alpha-2: Two-letter country code (e.g., "FR")
• ISO Alpha-3: Three-letter country code (e.g., "FRA")
• AT Code: Italian territorial code

Database Structure

Continents

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

Areas

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

Countries

• id (UUID, primary key)
• continent_id (UUID, foreign key)
• area_id (UUID, foreign key)
• parent_country_id (UUID, foreign key, nullable)
• type (string: 'S' for State, 'T' for Territory)
• name (string: Italian name)
• istat_code (string, unique)
• iso_alpha2 (string, 2 chars)
• iso_alpha3 (string, 3 chars)
• at_code (string)
• created_at, updated_at, deleted_at

Relationships

• Continent → hasMany → Area
• Continent → hasMany → Country
• Area → belongsTo → Continent
• Area → hasMany → Country
• Country → belongsTo → Continent
• Country → belongsTo → Area
• Country → belongsTo → Country (parent country, for territories)
• Country → hasMany → Country (territories)

Configuration

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

• Database connection: Specify a custom database connection
• 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 [ 'database_connection' => null, 'tables' => [ 'continents' => 'continents', 'areas' => 'areas', 'countries' => 'countries', ], 'models' => [ 'continent' => \App\Models\Continent::class, 'area' => \App\Models\Area::class, 'country' => \App\Models\Country::class, ], 'import' => [ 'csv_url' => 'https://www.istat.it/storage/codici-unita-amministrative/Elenco-codici-e-denominazioni-unita-territoriali-estere.csv', 'temp_filename' => 'istat_foreign_countries.csv', ], ];

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 (Level 5)
• ✅ Pest PHP testing framework
• ✅ Architecture tests

Run Static Analysis

composer analyse

Code Style Formatting

composer format

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

Credits

Data source: ISTAT - Italian National Institute of Statistics

License

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