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 3w 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 52% 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

2245d 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

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.3k543.5M2.6k](/packages/aws-aws-sdk-php)[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k656.1k38](/packages/neuron-core-neuron-ai)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3741.3M46](/packages/tencentcloud-tencentcloud-sdk-php)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k40](/packages/civicrm-civicrm-core)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[oat-sa/tao-core

TAO core extension

66143.7k120](/packages/oat-sa-tao-core)

PHPackages © 2026

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