PHPackages                             paulosanda/laravel-multiple-cep-api - 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. paulosanda/laravel-multiple-cep-api

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

paulosanda/laravel-multiple-cep-api
===================================

A SOLID CEP search package for Laravel with multiple providers and automatic fallback

1.0.2(6mo ago)21MITPHPPHP ^8.1

Since Dec 24Pushed 6mo agoCompare

[ Source](https://github.com/paulosanda/multi-api-cep-search)[ Packagist](https://packagist.org/packages/paulosanda/laravel-multiple-cep-api)[ RSS](/packages/paulosanda-laravel-multiple-cep-api/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (4)Versions (3)Used By (0)

Laravel Multiple CEP API
========================

[](#laravel-multiple-cep-api)

[![PHP Version](https://camo.githubusercontent.com/83dd395020c37276225039739320f6c8e7e99963ab21ee3d09282cb48dad2a60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c7565)](https://php.net)[![Laravel Version](https://camo.githubusercontent.com/add0a2daaf51dd84233459fc84033647bab96087f8cefa4e7b8e3a56e1f52451/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d313025324225323025374325323031312532422d726564)](https://laravel.com)[![License: MIT](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](https://opensource.org/licenses/MIT)

Um pacote SOLID para busca de CEP no Laravel com múltiplos provedores e fallback automático.

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

[](#-instalação)

```bash composer require paulosanda/laravel-multiple-cep-api ```

O pacote usa Package Discovery do Laravel. Não precisa registrar manualmente.

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

[](#-uso-básico)

```php use PauloSanda\\MultipleCepApi\\CepService;

$cepService = app(CepService::class); $endereco = $cepService->search('01001000');

// Ou via Facade (se configurada no composer.json): // $endereco = \\Cep::search('01001-000');

if ($endereco) { echo $endereco\['logradouro'\]; // Rua echo $endereco\['bairro'\]; // Bairro
echo $endereco\['cidade'\]; // Cidade echo $endereco\['estado'\]; // Estado echo $endereco\['provider'\]; // Provedor que encontrou } ```

⚙️ Configuração (Opcional)
--------------------------

[](#️-configuração-opcional)

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

Edite `config/cep.php`:

```php return \[ 'providers' => \[ \\PauloSanda\\MultipleCepApi\\Providers\\ViaCepProvider::class, \\PauloSanda\\MultipleCepApi\\Providers\\BrasilApiProvider::class, \\PauloSanda\\MultipleCepApi\\Providers\\OpenCepProvider::class, // Adicione provedores customizados aqui \], 'timeout' => 3, 'retry\_attempts' => 3, \]; ```

🔌 Provedores Padrão
-------------------

[](#-provedores-padrão)

ProvedorPrioridadeFallbackFormato**ViaCEP**100SimQualquer**BrasilAPI**90SimApenas números**OpenCEP**80NãoApenas números🛠️ Criando Provedores Customizados
----------------------------------

[](#️-criando-provedores-customizados)

1. Implemente a interface:

```php use PauloSanda\\MultipleCepApi\\Contracts\\CepProviderInterface; use PauloSanda\\MultipleCepApi\\Utils\\CepFormatter;

class MeuProvedorCustomizado implements CepProviderInterface { public function search(string $cep): ?array { // Sua implementação }

```
public function hasFallback(): bool
{
    return true;
}

public function getName(): string
{
    return 'MeuProvedor';
}

public function getPriority(): int
{
    return 95;
}

public function getRequireCepFormat(): ?string
{
    return CepFormatter::JUST_NUMBERS;
}

```

} ```

2. Adicione ao config:

```php 'providers' => \[ \\PauloSanda\\MultipleCepApi\\Providers\\ViaCepProvider::class, \\App\\Providers\\MeuProvedorCustomizado::class, \\PauloSanda\\MultipleCepApi\\Providers\\BrasilApiProvider::class, \], ```

⚠️ Importante
-------------

[](#️-importante)

Este pacote usa **Facades do Laravel** (`Http`, `Log`):

- Funciona apenas dentro de aplicações Laravel
- Testes via CLI puro não funcionam sem Laravel

📁 Estrutura
-----------

[](#-estrutura)

``` src/ ├── CepService.php # Serviço principal ├── CepServiceProvider.php # ServiceProvider ├── Contracts/ │ └── CepProviderInterface.php ├── Providers/ │ ├── ViaCepProvider.php │ ├── BrasilApiProvider.php
│ └── OpenCepProvider.php ├── Utils/ │ └── CepFormatter.php └── Facades/ └── Cep.php ```

🔧 Princípios SOLID
------------------

[](#-princípios-solid)

1. **Single Responsibility**: Cada classe tem uma responsabilidade
2. **Open/Closed**: Aberto para novos provedores
3. **Liskov Substitution**: Provedores substituíveis
4. **Interface Segregation**: Interface específica
5. **Dependency Inversion**: Depende de abstrações

🤝 Contribuindo
--------------

[](#-contribuindo)

1. Fork o projeto
2. Crie uma branch (`git checkout -b feature/MinhaFeature`)
3. Commit (`git commit -m 'Adiciona MinhaFeature'`)
4. Push (`git push origin feature/MinhaFeature`)
5. Abra um Pull Request

📄 Licença
---------

[](#-licença)

MIT - veja [LICENSE](LICENSE) para detalhes.

👨‍💻 Autor
---------

[](#‍-autor)

**Paulo Sanda** - [GitHub](https://github.com/paulosanda)

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance67

Regular maintenance activity

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

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

Total

2

Last Release

191d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/56307568?v=4)[Paulo Sanda](/maintainers/paulosanda)[@paulosanda](https://github.com/paulosanda)

---

Top Contributors

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

---

Tags

laraveladdresscepbrazilviacepBrasilApiopencep

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/paulosanda-laravel-multiple-cep-api/health.svg)

```
[![Health](https://phpackages.com/badges/paulosanda-laravel-multiple-cep-api/health.svg)](https://phpackages.com/packages/paulosanda-laravel-multiple-cep-api)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M3.1k](/packages/craftcms-cms)[nativephp/mobile

NativePHP for Mobile

1.1k75.1k91](/packages/nativephp-mobile)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[venturedrake/laravel-crm

A free open source CRM built as a package for laravel projects

43311.2k](/packages/venturedrake-laravel-crm)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5021.9k](/packages/simplestats-io-laravel-client)

PHPackages © 2026

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