search

mlocati / comuni-italiani

A PHP library to work with Italian Regions, Provinces, and Municipalities
MIT License
1 stars 0 forks source link
comuni istat italian italiani italy municipalities province provinces regioni regions

readme

Tests Coverage

Comuni Italiani

This PHP library contains the whole list of Italian Regions (regioni), Provinces (province/UTS), and Municipalities (comuni).

The data comes from the official Situas service of the Istituto nazionale di statistica (Istat), that publishes its data with the CC-BY-4.0 license .

Installation

You can install this package with Composer:

composer require mlocati/comuni-italiani

Data Structure

This library provides the following Italian Administrative divisions:

Where:

Data Available

This library provides the following data:

Retrieving All Territories

You can have a list of all the Geographical Subdivisions, Regions, Provinces/UTS, and Municipalities using the Factory class.

For example:

use MLocati\ComuniItaliani\Factory;

$factory = new Factory();

$allGeographicalSubdivisions = $factory->getGeographicalSubdivisions();
$allRegions = $factory->getRegions();
$allProvinces = $factory->getProvinces();
$allMunicipalities = $factory->getMunicipalities();

Finding Territories by ID

If you want to retrieve a territory given its ID, you can use the Finder class:

use MLocati\ComuniItaliani\Finder;

$finder = new Finder();

$geographicalSubdivision = $finder->getGeographicalSubdivisionByID(1);
$region = $finder->getRegionByID('01');
$province = $finder->getProvinceByID('201');
$municipality = $finder->getMunicipalityByID('001272');

Finding Provinces by Vehicle Code

You can use the getProvinceByVehicleCode method of the Finder class:

use MLocati\ComuniItaliani\Finder;

$finder = new Finder();

echo $finder->getProvinceByVehicleCode('CO')->getName();
// prints Como

Finding Territories by Name

You can use the Finder class to find Geographical Subdivisions, Regions, Provinces/UTS, and Municipalities by name.

The text to be searched will be split into words, and you'll get the territories whose names contain all the words.

For example, searching for roma lombard will return the Romano di Lombardia (BG) municipality.

Examples:

use MLocati\ComuniItaliani\Finder;

$finder = new Finder();

$geographicalSubdivisions = $finder->findGeographicalSubdivisionsByName('Nord');
$regions = $finder->findRegionsByName('Campa');
$provinces = $finder->findProvincesByName('Bozen');
$municipalities = $finder->findMunicipalitiesByName('Roma lombard');

By default, Finder will look for the beginning of words. So, ampania won't match Campania.

If you want to allow searching in the middle of the words, specify true as the second parameter:

use MLocati\ComuniItaliani\Finder;

$finder = new Finder();

$geographicalSubdivisions = $finder->findGeographicalSubdivisionsByName('ord', true);
$regions = $finder->findRegionsByName('ampania', true);
$provinces = $finder->findProvincesByName('ozen', true);
$municipalities = $finder->findMunicipalitiesByName('oma ombard', true);

You can also restrict the search to specific territories:

use MLocati\ComuniItaliani\Finder;

$finder = new Finder();

$province = $finder->getProvinceByVehicleCode('BG');
$municipalities = $finder->findMunicipalitiesByName('romano', false, $province);
// The same applies to findRegionsByName and findProvincesByName

Testing Hierarchy

Given two territories, you can check if they are the same by using the isSame() method:

if ($territory1->isSame($territory2)) {
    echo 'Same territory';
}

You can also check if a territory is contained in another territory:

if ($territory1->isContainedIn($territory2)) {
    echo "{$territory1} is contained in {$territory2}";
}
if ($territory1->isSameOrContainedIn($territory2)) {
    echo "{$territory1} is contained in {$territory2} (or they are the same)";
}

For Geographical Subdivisions, Regions, and Provinces/UTS (which are containers of other territories) you can also use the contains() and isSameOrContains() methods.

// $region is an instance of Region here
if ($region->contains($territory)) {
    echo "{$region} contains {$terrtory}";
}

if ($region->isSameOrContains($territory)) {
    echo "{$region} is same (or contains) {$terrtory}";
}