PHPackages                             carloeusebi/laravel-comuni - 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. [API Development](/categories/api)
4. /
5. carloeusebi/laravel-comuni

ActiveLibrary[API Development](/categories/api)

carloeusebi/laravel-comuni
==========================

A package to retrieve italians comuni, province and regions using various apis.

v0.7(2mo ago)11.2k↓31.8%MITPHPPHP ^8.4CI failing

Since Jun 21Pushed 2mo agoCompare

[ Source](https://github.com/carloeusebi/laravel-comuni)[ Packagist](https://packagist.org/packages/carloeusebi/laravel-comuni)[ RSS](/packages/carloeusebi-laravel-comuni/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (20)Versions (8)Used By (0)

[ ![Tests](https://github.com/carloeusebi/laravel-comuni/actions/workflows/tests.yml/badge.svg)](https://github.com/carloeusebi/laravel-comuni/actions)[ ![Total Downloads](https://camo.githubusercontent.com/7ac778edb31dc3933bca965ef02288623f334b677148eb8b0f145353cf1c60b0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6361726c6f6575736562692f6c61726176656c2d636f6d756e69)](https://packagist.org/packages/carloeusebi/laravel-comuni)[ ![Latest Version](https://camo.githubusercontent.com/195706e8e0d3a959a90ef7e6120ad5d3efc288133494752841dc42bad98a672e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6361726c6f6575736562692f6c61726176656c2d636f6d756e69)](https://packagist.org/packages/carloeusebi/laravel-comuni)[ ![License](https://camo.githubusercontent.com/d02f2624f1511352bf145dfbd63fccdb341d4791ae9b620e7f9028923f8a802b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6361726c6f6575736562692f6c61726176656c2d636f6d756e69)](https://packagist.org/packages/carloeusebi/laravel-comuni)Laravel Comuni
==============

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

[](#installation)

You can install the package via composer:

```
composer require carloeusebi/laravel-comuni
```

The package will automatically register its service provider.

Usage
-----

[](#usage)

This package provides a simple facade to access Italian geographical data:

```
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

[](#filtering-and-pagination)

You can filter and paginate results using the `params` array:

```
// 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

[](#available-parameters)

For available parameters please refer to third parties documentations:

- [Samurai016/Comuni-ITA](https://comuni-ita.readme.io/reference/comuni-1)

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

[](#configuration)

You can publish the configuration file with:

```
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.

```
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
---------------

[](#response-format)

All methods return Laravel Collections. Here's an example of the data structure for each type:

### Comuni

[](#comuni)

```
[
    '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

[](#province)

```
[
    'codice' => '058',
    'nome' => 'Roma',
    'sigla' => 'RM',
    'regione' => 'Lazio'
]
```

### Regioni

[](#regioni)

Returns a collection of region names as strings:

```
['Abruzzo', 'Basilicata', 'Calabria', ...]
```

Faking
------

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

```
\CarloEusebi\LaravelComuni\Facades\Comuni::fake();

\CarloEusebi\LaravelComuni\Facades\Comuni::shouldReceive('comuni')->andReturn(collect(['Abano Terme', 'Abbadia Cerreto', 'Abbadia Lariana', 'Abbadia San Salvatore']));
```

Testing
-------

[](#testing)

This package includes a comprehensive test suite. To run tests:

```
composer test
```

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance87

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~45 days

Recently: every ~67 days

Total

7

Last Release

62d ago

PHP version history (2 changes)v0.1PHP ^8.2

v0.4PHP ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/da3a472cd0da99e6219a56a1b08c8a35d1ab6f7b853d5882e44b3dacfc6f2d04?d=identicon)[carloeusebi](/maintainers/carloeusebi)

---

Top Contributors

[![carloeusebi](https://avatars.githubusercontent.com/u/129429172?v=4)](https://github.com/carloeusebi "carloeusebi (14 commits)")

---

Tags

comuniitalianitalianolaravelprovinceregioni

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/carloeusebi-laravel-comuni/health.svg)

```
[![Health](https://phpackages.com/badges/carloeusebi-laravel-comuni/health.svg)](https://phpackages.com/packages/carloeusebi-laravel-comuni)
```

###  Alternatives

[spatie/laravel-query-builder

Easily build Eloquent queries from API requests

4.4k26.9M220](/packages/spatie-laravel-query-builder)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[esign/laravel-conversions-api

A laravel wrapper package around the Facebook Conversions API

69145.4k](/packages/esign-laravel-conversions-api)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[surface/laravel-webfinger

A Laravel package to create an ActivityPub webfinger.

113.8k](/packages/surface-laravel-webfinger)

PHPackages © 2026

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