PHPackages                             plin-code/laravel-istat-foreign-countries - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. plin-code/laravel-istat-foreign-countries

ActiveLibrary[Utility & Helpers](/categories/utility)

plin-code/laravel-istat-foreign-countries
=========================================

Laravel package for importing and managing foreign countries data from ISTAT

v1.1.4(1mo ago)12.3k2MITPHPPHP ^8.3CI passing

Since Nov 10Pushed 1mo agoCompare

[ Source](https://github.com/plin-code/laravel-istat-foreign-countries)[ Packagist](https://packagist.org/packages/plin-code/laravel-istat-foreign-countries)[ Docs](https://github.com/plin-code/laravel-istat-foreign-countries)[ GitHub Sponsors](https://github.com/PlinCode)[ RSS](/packages/plin-code-laravel-istat-foreign-countries/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (6)Dependencies (28)Versions (10)Used By (0)

Laravel ISTAT Foreign Countries
===============================

[](#laravel-istat-foreign-countries)

[![Latest Version on Packagist](https://camo.githubusercontent.com/d59c5053317553ddf3a3f7796728c16493d63103e3dc0e5d07aae7e96191181a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f706c696e2d636f64652f6c61726176656c2d69737461742d666f726569676e2d636f756e74726965732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/plin-code/laravel-istat-foreign-countries)[![GitHub Tests Action Status](https://camo.githubusercontent.com/43e5a0caabcf11e163cb3198f32151440a2b1720412ec726a23c7b16d59b229d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f706c696e2d636f64652f6c61726176656c2d69737461742d666f726569676e2d636f756e74726965732f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473)](https://github.com/plin-code/laravel-istat-foreign-countries/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/d1645d69781e45c93bd4139393d4763da3b9a4c2ec970a3a1cae5663277d4295/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f706c696e2d636f64652f6c61726176656c2d69737461742d666f726569676e2d636f756e74726965732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65)](https://github.com/plin-code/laravel-istat-foreign-countries/actions?query=workflow%3A%22Check+%26+fix+styling%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/9155c262fc904ab1066a6a61592ee4b319ffaceeb2b68683478a97245c84f74b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f706c696e2d636f64652f6c61726176656c2d69737461742d666f726569676e2d636f756e74726965732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/plin-code/laravel-istat-foreign-countries)

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

Features
--------

[](#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
------------

[](#requirements)

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

Installation
------------

[](#installation)

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

Quick Start
-----------

[](#quick-start)

1. **Install the package:**

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

2. **Publish the configuration:**

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

3. **Run migrations:**

```
php artisan migrate
```

4. **Import the data:**

```
php artisan foreign-countries:import
```

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

Configuration
-------------

[](#configuration)

Publish the configuration file:

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

Usage
-----

[](#usage)

### Data Import

[](#data-import)

To import all foreign countries data from ISTAT:

```
php artisan foreign-countries:import
```

### Models

[](#models)

The package provides three Eloquent models:

#### Continent

[](#continent)

```
use PlinCode\IstatForeignCountries\Models\ForeignCountries\Continent;

$continent = Continent::where('name', 'Europa')->first();
$areas = $continent->areas;
$countries = $continent->countries;
```

#### Area

[](#area)

```
use PlinCode\IstatForeignCountries\Models\ForeignCountries\Area;

$area = Area::where('name', 'Unione europea')->first();
$countries = $area->countries;
$continent = $area->continent;
```

#### Country

[](#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

[](#facade-usage)

```
use PlinCode\IstatForeignCountries\Facades\IstatForeignCountries;

// Import data programmatically
$count = IstatForeignCountries::import();
```

### Available Codes

[](#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
------------------

[](#database-structure)

### Continents

[](#continents)

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

### Areas

[](#areas)

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

### Countries

[](#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
-------------

[](#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
-------------

[](#configuration-1)

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

[](#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
-------

[](#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

[](#run-static-analysis)

```
composer analyse
```

### Code Style Formatting

[](#code-style-formatting)

```
composer format
```

Contributing
------------

[](#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
-------

[](#credits)

Data source: [ISTAT - Italian National Institute of Statistics](https://www.istat.it/)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

49

—

FairBetter than 94% of packages

Maintenance93

Actively maintained with recent releases

Popularity23

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 62.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~37 days

Recently: every ~47 days

Total

6

Last Release

36d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7653cedfb706bdbaceab17cb57fa55d5e2744faeb722cfc1e2af8c3fd88f13ef?d=identicon)[danielebarbaro](/maintainers/danielebarbaro)

---

Top Contributors

[![danielebarbaro](https://avatars.githubusercontent.com/u/4376886?v=4)](https://github.com/danielebarbaro "danielebarbaro (22 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (7 commits)")[![Gybra](https://avatars.githubusercontent.com/u/1799993?v=4)](https://github.com/Gybra "Gybra (5 commits)")[![dpapperini](https://avatars.githubusercontent.com/u/77624959?v=4)](https://github.com/dpapperini "dpapperini (1 commits)")

---

Tags

countrygeographyhacktoberfestistatlaravellaravelgeographyistatPlinCodeplin-codelaravel-istat-foreign-countriesforeign-countries

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/plin-code-laravel-istat-foreign-countries/health.svg)

```
[![Health](https://phpackages.com/badges/plin-code-laravel-istat-foreign-countries/health.svg)](https://phpackages.com/packages/plin-code-laravel-istat-foreign-countries)
```

###  Alternatives

[spatie/laravel-health

Monitor the health of a Laravel application

87411.3M152](/packages/spatie-laravel-health)[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.3M42](/packages/spatie-laravel-pdf)[maestroerror/laragent

Power of AI Agents in your Laravel project

639142.5k](/packages/maestroerror-laragent)[nativephp/mobile

NativePHP for Mobile

1.0k55.0k85](/packages/nativephp-mobile)[plin-code/laravel-istat-geography

Laravel package for importing and managing Italian geography data from ISTAT

106.3k](/packages/plin-code-laravel-istat-geography)[codewithdennis/filament-select-tree

The multi-level select field enables you to make single selections from a predefined list of options that are organized into multiple levels or depths.

328482.0k25](/packages/codewithdennis-filament-select-tree)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)