PHPackages                             paulo-hortelan/lara-cep - 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. paulo-hortelan/lara-cep

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

paulo-hortelan/lara-cep
=======================

Pacote Laravel para consulta de CEPs brasileiros com múltiplos provedores, cache e orquestração assíncrona opcional.

v1.1.0(2mo ago)1543MITPHP ^8.1

Since May 6Compare

[ Source](https://github.com/paulo-hortelan/lara-cep)[ Packagist](https://packagist.org/packages/paulo-hortelan/lara-cep)[ Docs](https://github.com/paulo-hortelan/lara-cep)[ RSS](/packages/paulo-hortelan-lara-cep/feed)WikiDiscussions Synced 3w ago

READMEChangelog (2)Dependencies (16)Versions (4)Used By (0)

Lara CEP
========

[](#lara-cep)

[![Latest Version on Packagist](https://camo.githubusercontent.com/2c7df2eb845d247789cc9e768f6ab95d7b785d8177a775754a52ef8079fe77bc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7061756c6f2d686f7274656c616e2f6c6172612d6365702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/paulo-hortelan/lara-cep)[![Tests](https://camo.githubusercontent.com/5dbe1ad3a6486edc3429f6b60f0d3019b941efb90ba641921d151fb7a7fb0062/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7061756c6f2d686f7274656c616e2f6c6172612d6365702f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/paulo-hortelan/lara-cep/actions?query=workflow%3Arun-tests+branch%3Amain)[![Code Style](https://camo.githubusercontent.com/8512970367cc7d74713ae0513c5a066a7a4f4fb1e58b1f69ba686a451b74aaf7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7061756c6f2d686f7274656c616e2f6c6172612d6365702f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/paulo-hortelan/lara-cep/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/998e0a0ed209d7299fd50b92554c39da4525da3a5ea3a37cc31e172ed4d39505/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7061756c6f2d686f7274656c616e2f6c6172612d6365702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/paulo-hortelan/lara-cep)

`lara-cep` é um pacote Laravel para consultar CEPs brasileiros usando múltiplos provedores, com:

- lista de provedores configurável
- TTL de cache configurável
- modo assíncrono configurável (consulta todos os provedores habilitados em paralelo)

O pacote foi inspirado no comportamento do CEP Promise e adaptado para fluxos de pacote Laravel.

Instalação
----------

[](#instalação)

```
composer require paulo-hortelan/lara-cep
```

Publique a configuração:

```
php artisan vendor:publish --tag=lara-cep-config
```

Uso Básico
----------

[](#uso-básico)

```
use PauloHortelan\LaraCep\Facades\LaraCep;

$address = LaraCep::find('01001-000');

$address->zipCode;  // 01001000
$address->state;    // SP
$address->city;     // Sao Paulo
$address->district; // Centro
$address->street;   // Praca da Se...
$address->provider; // via_cep, open_cep, brasil_api...
```

Você também pode chamar:

```
$address = app('lara-cep')->find('01001000');
```

Configuração
------------

[](#configuração)

`config/lara-cep.php`

```
return [
    'async' => true,

    'cache' => [
        'enabled' => true,
        'ttl' => 3600,
        'store' => null,
        'prefix' => 'lara_cep',
    ],

    'providers' => [
        'via_cep' => [
            'enabled' => true,
            'class' => PauloHortelan\LaraCep\Providers\ViaCepProvider::class,
        ],

        'open_cep' => [
            'enabled' => true,
            'class' => PauloHortelan\LaraCep\Providers\OpenCepProvider::class,
        ],

        'brasil_api' => [
            'enabled' => true,
            'class' => PauloHortelan\LaraCep\Providers\BrasilApiProvider::class,
        ],

        'cep_aberto' => [
            'enabled' => false,
            'class' => PauloHortelan\LaraCep\Providers\CepAbertoProvider::class,
            'token' => env('LARA_CEP_PROVIDER_CEP_ABERTO_TOKEN', ''),
        ],
    ],
];
```

### Comportamento assíncrono

[](#comportamento-assíncrono)

- `async = true`: todos os provedores habilitados são consultados em paralelo; a primeira resposta com sucesso vence.
- `async = false`: os provedores são consultados na ordem configurada até um retornar sucesso.

### Comportamento de cache

[](#comportamento-de-cache)

- a chave de cache usa o prefixo configurado + CEP normalizado
- o TTL é totalmente configurável (`cache.ttl`)
- o cache pode ser desabilitado (`cache.enabled = false`)

Tratamento de Erros
-------------------

[](#tratamento-de-erros)

```
use PauloHortelan\LaraCep\Exceptions\CepLookupException;
use PauloHortelan\LaraCep\Exceptions\InvalidCepException;

try {
    $address = LaraCep::find('99999999');
} catch (InvalidCepException $e) {
    // formato de CEP inválido
} catch (CepLookupException $e) {
    // todos os provedores falharam
    $details = $e->toArray();
}
```

Testes
------

[](#testes)

```
composer test
```

Licença
-------

[](#licença)

MIT. Veja [LICENSE.md](LICENSE.md).

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance85

Actively maintained with recent releases

Popularity20

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

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 ~0 days

Total

2

Last Release

79d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/135706260?v=4)[Paulo Hortelan Ribeiro](/maintainers/paulo-hortelan)[@paulo-hortelan](https://github.com/paulo-hortelan)

---

Tags

laravelzip codecepPaulo Hortelanbrasil

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/paulo-hortelan-lara-cep/health.svg)

```
[![Health](https://phpackages.com/badges/paulo-hortelan-lara-cep/health.svg)](https://phpackages.com/packages/paulo-hortelan-lara-cep)
```

###  Alternatives

[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M136](/packages/laravel-pulse)[harris21/laravel-fuse

Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures.

45955.7k](/packages/harris21-laravel-fuse)[nativephp/mobile

NativePHP for Mobile

1.1k75.1k106](/packages/nativephp-mobile)[spatie/laravel-health

Monitor the health of a Laravel application

87912.0M177](/packages/spatie-laravel-health)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M347](/packages/psalm-plugin-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M133](/packages/roots-acorn)

PHPackages © 2026

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