PHPackages                             andersonef/cep-promise-php - 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. andersonef/cep-promise-php

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

andersonef/cep-promise-php
==========================

Cópia do projeto filipedeschamps/cep-promise, porém em PHP. A idéia não é copiar fielmente a implementação, mas a funcionalidade afim de praticar apenas.

1.0.1(6y ago)11113[1 issues](https://github.com/andersonef/cep-promise-php/issues)[2 PRs](https://github.com/andersonef/cep-promise-php/pulls)MITPHP

Since May 9Pushed 3y ago1 watchersCompare

[ Source](https://github.com/andersonef/cep-promise-php)[ Packagist](https://packagist.org/packages/andersonef/cep-promise-php)[ RSS](/packages/andersonef-cep-promise-php/feed)WikiDiscussions master Synced 5d ago

READMEChangelogDependencies (2)Versions (5)Used By (0)

 [![](https://camo.githubusercontent.com/69c08e5fdac8abf9e0ccb86d258da4a32a5d1a25b6bca937deaf50e0a70ee8cf/687474703a2f2f7069736b656c2d696d6773746f72652d622e61707073706f742e636f6d2f696d672f64353830653936652d626438612d313165362d623135372d3939343963616434643630392e676966)](https://camo.githubusercontent.com/69c08e5fdac8abf9e0ccb86d258da4a32a5d1a25b6bca937deaf50e0a70ee8cf/687474703a2f2f7069736b656c2d696d6773746f72652d622e61707073706f742e636f6d2f696d672f64353830653936652d626438612d313165362d623135372d3939343963616434643630392e676966)

CEP Promise
===========

[](#cep-promise)

Busca por CEP integrado diretamente aos serviços dos Correios, ViaCEP e WideNet. Descrição
---------

[](#descrição)

Essa biblioteca é uma cópia da original feita pelo [Filipe Deschamps (Michel Teló)](https://github.com/filipedeschamps) que achei a premissa bastante interessante e decidi copiá-la em PHP e Python.

O estilo do código é outro, visto que o Filipe usa JS com uma abordagem funcional, já eu nesse projeto optei por utilizar orientação a objetos guiada por testes.

Features
--------

[](#features)

- Sempre atualizado em tempo-real por se conectar diretamente aos serviços dos Correios, ViaCEP e WideNet.
- Possui alta disponibilidade por usar vários serviços como fallback.
- Sem limites de uso (rate limits) conhecidos.
- 100% de code coverage com testes unitários e integração.

Como Utilizar
-------------

[](#como-utilizar)

### Instalação

[](#instalação)

Instale via composer diretamente no bash com o comando:

```
composer require andersonef/cep-promise-php
```

Ou modifique seu arquivo **composer.json** acrescentando a biblioteca nas dependências:

```
    "require": {
        "andersonef/cep-promise-php": "^1.0.0"
    }
```

### Utilização

[](#utilização)

A utilização é bem simples:

```
$promise = (new CepPromise('83322170'))->fetch();

// ASSÍNCRONO: Com a promise em mãos, eu posso tanto:
$promise->then(function($endereco) {
    // sua lógica aqui
});

// SÍNCRONO:
$endereco = $promise->wait();

/** Endereço:
 * {
  "cep": "83322170",
  "street": "Rua Rio Tocantins",
  "neighborhood": "Weissópolis",
  "city": "Pinhais",
  "state": "PR"
}
*/
```

O retorno será sempre um objeto do tipo **Andersonef\\CepPromise\\ResponseAddress**.

### Customizando

[](#customizando)

Você pode criar novos serviços para fallback facilmente com essa biblioteca.

Um serviço é qualquer classe que implemente a interface **Andersonef\\CepPromise\\Interfaces\\ServiceInterface**, logo:

```
class CepFromDatabase implements ServiceInterface
{
    public function fetch($cep): ResponseAddress
    {
        // .. your custom logic here
        $response = new ResponseAddress(
            $cep,
            $rua,
            $bairro,
            $cidade,
            $estado
        );
        return $response;
    }
}
```

Após criar seu service customizado, basta adicioná-lo à sua instância CepPromise, assim:

```
$cepFromDatabaseService = new CepFromDatabase();
$cepPromise = new CepPromise();

$endereco = $cepPromise
    ->clearServices() // OPCIONAL: elimina os services padrão (correios, viacep e widenet)
    ->appendService($cepFromDatabaseService)
    ->fetch('83322170'); // Agora a classe irá usar seu service customizado!
```

Tratando falhas
---------------

[](#tratando-falhas)

Qualquer erro nessa biblioteca irá disparar uma exception do tipo **Andersonef\\CepPromise\\CepPromiseException**.

Deixe suas sugestões
--------------------

[](#deixe-suas-sugestões)

Fique a vontade para deixar sugestões nas issues!

Fonte
-----

[](#fonte)

Esse pacote foi inspirado no original [](https://github.com/filipedeschamps/cep-promise)

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance18

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 87.5% 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

2198d ago

### Community

Maintainers

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

---

Top Contributors

[![andersonef](https://avatars.githubusercontent.com/u/3864077?v=4)](https://github.com/andersonef "andersonef (7 commits)")[![filhodanuvem](https://avatars.githubusercontent.com/u/94096?v=4)](https://github.com/filhodanuvem "filhodanuvem (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/andersonef-cep-promise-php/health.svg)

```
[![Health](https://phpackages.com/badges/andersonef-cep-promise-php/health.svg)](https://phpackages.com/packages/andersonef-cep-promise-php)
```

###  Alternatives

[shlinkio/shlink

A self-hosted and PHP-based URL shortener application with CLI and REST interfaces

4.8k4.3k](/packages/shlinkio-shlink)[ralphjsmit/laravel-helpers

A package containing handy helpers for your Laravel-application.

13704.6k2](/packages/ralphjsmit-laravel-helpers)[dhlparcel/magento2-plugin

DHL Parcel plugin for Magento 2

11180.5k2](/packages/dhlparcel-magento2-plugin)[aedart/athenaeum

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

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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