https://github.com/carloeusebi/laravel-comuni
A Laravel package that provides a simple and elegant way to retrive italian comuni, province and regioni. This package uses third party apis and provides only an easy wrapper to access those apis.
https://github.com/carloeusebi/laravel-comuni
comuni italian italiano laravel province regioni
Last synced: about 2 months ago
JSON representation
A Laravel package that provides a simple and elegant way to retrive italian comuni, province and regioni. This package uses third party apis and provides only an easy wrapper to access those apis.
- Host: GitHub
- URL: https://github.com/carloeusebi/laravel-comuni
- Owner: carloeusebi
- Created: 2025-06-21T10:26:46.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-03-17T16:52:57.000Z (3 months ago)
- Last Synced: 2026-03-18T06:42:08.292Z (3 months ago)
- Topics: comuni, italian, italiano, laravel, province, regioni
- Language: PHP
- Homepage:
- Size: 233 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Laravel Comuni
A Laravel package that provides a simple and elegant way to retrive italian comuni, province and regioni.
This package uses third party apis and provides only an easy wrapper to access those apis.
Currently supported apis:
- [Samurai016/Comuni-ITA](https://github.com/Samurai016/Comuni-ITA)
## Installation
You can install the package via composer:
```bash
composer require carloeusebi/laravel-comuni
```
The package will automatically register its service provider.
## Usage
This package provides a simple facade to access Italian geographical data:
```php
use CarloEusebi\LaravelComuni\Facades\Comuni;
// Get all regions
$regions = Comuni::regioni();
// Get all provinces
$provinces = Comuni::province();
// Get all municipalities
$comuni = Comuni::comuni();
// Get municipalities by region
$comuni = Comuni::comuni(regione: 'Lazio');
// Get municipalities by province
$comuni = Comuni::comuni(provincia: 'Roma');
```
### Filtering and Pagination
You can filter and paginate results using the `params` array:
```php
// Get municipalities with pagination
$comuni = Comuni::comuni(params: ['page' => 1, 'pagesize' => 10]);
// Filter municipalities by name
$comuni = Comuni::comuni(params: ['nome' => 'Roma']);
// Get only municipality names
$comuni = Comuni::comuni(params: ['onlyname' => true]);
// Filter regions by name
$regions = Comuni::regioni(['nome' => 'Lazio']);
```
### Available Parameters
For available parameters please refer to third parties documentations:
- [Samurai016/Comuni-ITA](https://comuni-ita.readme.io/reference/comuni-1)
## Configuration
You can publish the configuration file with:
```bash
php artisan vendor:publish --provider="CarloEusebi\LaravelComuni\ComuniServiceProvider"
```
This will create a `config/comuni.php` file where you can modify the default settings:
You can safely cache the responses for a long period of time. As these services are hosted on free platforms, please
consider keeping responses cached as long as possible.
```php
return [
// currently the only provider is `comuni-ita`
'provider' => 'comuni-ita',
'cache' => [
// the prefix for the cache key
'prefix' => 'comuni-',
// the number of days the responses should be cached for
'ttl' => 60,
// the number of days after which the cache becomes stale
'stale' => 30,
],
];
```
## Response Format
All methods return Laravel Collections. Here's an example of the data structure for each type:
### Comuni
```php
[
'codice' => '058091',
'nome' => 'Roma',
'nomeStraniero' => 'Rome',
'cap' => ['00118', '00121', '00122', ...],
'prefisso' => '06',
'provincia' => [
'codice' => '058',
'nome' => 'Roma',
'sigla' => 'RM',
'regione' => 'Lazio'
],
'email' => 'protocollo.gabinettosindaco@pec.comune.roma.it',
'pec' => 'protocollo.gabinettosindaco@pec.comune.roma.it',
'telefono' => '0667101',
'fax' => '0667103590',
'popolazione' => 2873494,
'coordinate' => [
'lat' => 41.89277,
'lng' => 12.48366
]
]
```
### Province
```php
[
'codice' => '058',
'nome' => 'Roma',
'sigla' => 'RM',
'regione' => 'Lazio'
]
```
### Regioni
Returns a collection of region names as strings:
```php
['Abruzzo', 'Basilicata', 'Calabria', ...]
```
## Faking
This package already has a comprehensive test suite. You don't need to test this package in your app.
But if you would like to test your implementation of this package, you can mock `Comuni` and decide what it should
return, or you can fake it and this package will generate a fake generic response for you.
```php
\CarloEusebi\LaravelComuni\Facades\Comuni::fake();
\CarloEusebi\LaravelComuni\Facades\Comuni::shouldReceive('comuni')->andReturn(collect(['Abano Terme', 'Abbadia Cerreto', 'Abbadia Lariana', 'Abbadia San Salvatore']));
```
## Testing
This package includes a comprehensive test suite. To run tests:
```bash
composer test
```