CEP Promise PHP

Um pacote agnóstico para PHP 7.4 e 8.0+ que efetua a busca de CEPs em diversos serviços utilizando Promises/A+. Inspirado no pacote CEP Promise para Node.js e web browsers.

Features

• Realiza requests de forma concorrente, retornando sempre a resposta mais rápida;
• Possui alta disponibilidade por utilizar diversos provedores de serviço diferentes;
• Base de CEPs sempre atualizada, já que conecta-se com diversos serviços, dentre eles os Correios;
• Sem limites de requisições (rate limits) conhecidas;
• Feito utilizando a implementação para PHP de promises do pacote guzzle/promises;

Instalação

A maneira recomendada de instalar o pacote é via Composer. Com a ferramenta instalada, execute o comando abaixo:

composer require claudsonm/cep-promise-php

Após instalar, você precisará requerer o autoloader do Composer por meio da instrução:

require 'vendor/autoload.php';

Exemplos de Uso

Exemplo 1

Busca utilizando valores inteiros e resposta em forma de objeto.

<?php

use Claudsonm\CepPromise\CepPromise;

require 'vendor/autoload.php';

$address = CepPromise::fetch(49040610);

/* 
Claudsonm\CepPromise\Address Object
(
    [city] => Aracaju
    [district] => Inácio Barbosa
    [state] => SE
    [street] => Rua Universo
    [zipCode] => 49040610
)
*/

Exemplo 2

Busca utilizando uma string numérica e resposta em forma de array.

<?php

use Claudsonm\CepPromise\CepPromise;

require 'vendor/autoload.php';

$address = CepPromise::fetch('78710857')->toArray();

/*
 Array
(
    [city] => Rondonópolis
    [district] => Vila Marinópolis
    [state] => MT
    [street] => Rua Pirajuí
    [zipCode] => 78710857
)
*/

Exemplo 3

Busca utilizando uma string com formatação.

<?php

use Claudsonm\CepPromise\CepPromise;

require 'vendor/autoload.php';

$address = CepPromise::fetch('59067-540');
echo $address->zipCode;
echo $address->street;
echo $address->district;
echo $address->city;
echo $address->state;

/*
'59067540'
'Rua Figueira'
'Pitimbu'
'Natal'
'RN'
*/

Exemplo 4

Captura e tratamento de erros.

<?php

use Claudsonm\CepPromise\CepPromise;
use Claudsonm\CepPromise\Exceptions\CepPromiseException;

require 'vendor/autoload.php';

try {
    $response = CepPromise::fetch('99999999');
} catch (CepPromiseException $e) {
    $response = $e->toArray();
}

/*
Array
(
    [message] => Todos os serviços de CEP retornaram erro.
    [code] => 2
    [errors] => Array
        (
            [0] => Array
                (
                    [provider] => via_cep
                    [message] => CEP não encontrado na base do ViaCEP.
                )

            [1] => Array
                (
                    [provider] => cep_aberto
                    [message] => Erro ao se conectar com o serviço CEP Aberto.
                )

            [2] => Array
                (
                    [provider] => correios
                    [message] => CEP INVÁLIDO
                )

        )

)
*/

Contribuidores

Um muito obrigado a todos os serumaninhos que contribuiram com este repositório:

Claudson Martins 📆 🚧 💻 📖 💡 💼 ✅

Este projeto segue a especificação do all-contributors. Contribuições de qualquer natureza são bem vindas!