README

#Consulta Cep A biblioteca Consulta Cep permite que você faça consultas de endereços através de CEPs.

O uso é extremamente simples e você pode usar múltiplos provedores para obter os dados (como Site Oficial do Correios, República Web, Postmon, ViaCep, etc).

$consultaCep = new \ConsultaCep\ConsultaCep();
$result = $consultaCep->consult('01311300');
$data = $result->getData();

echo $data['street']; //Avenida Paulista - de 1867 ao fim - lado ímpar
echo $data['neighborhood']; //Bela Vista
echo $data['city']; //São Paulo
echo $data['state']; //SP

##Como Usar 1 - Baixe a biblioteca usando o Composer.

composer require upnid/consulta-cep

2 - Crie um arquivo na raiz do seu projeto com o seguinte código:

<?php
require_once __DIR__.'/../vendor/autoload.php';

$consultaCep = new \ConsultaCep\ConsultaCep();
$result = $consultaCep->consult('01311-300');
$data = $result->getData();

print_r($data);

3 - Pronto! Você pode indicar o CEP trocando a sequência de números da quinta linha. A variável $data armazena uma array com os dados referentes do CEP. Veja o resultado:

Array
(
    [street] => Avenida Paulista - de 1867 ao fim - lado ímpar
    [neighborhood] => Bela Vista
    [city] => São Paulo
    [state] => SP
    [zipcode] => 01311300
)

Veja outros exemplos.

##Outros Provedores Os dados do CEP que o Correios oferece vêm em HTML, e por isso a biblioteca precisa manipular esses dados para entregá-los de forma organizada. Isso consome processamento e memória da sua máquina, e geralmente é mais lento do que usar um provedor personalizado.

A biblioteca permite que você use inúmeros provedores. Eles basicamente são como site do Correios, mas as informações vem organizadas e não é necessário manipular HTML (o que deixa o processo mais rápido).

Esses provedores salvam os dados de cada CEP internamente, o que evita que eles mesmos precisem consultar no site do Correios após a primeira tentativa.

Exemplo usando o provedor República Virtual:

<?php
require_once __DIR__.'/../vendor/autoload.php';

$provider = \ConsultaCep\Providers\ProvidersList::REPUBLICA_VIRTUAL;
$consultaCep = new \ConsultaCep\ConsultaCep($provider);

$result = $consultaCep->consult('01311300');
$data = $result->getData();

print_r($data);

Você pode usar outros provedores, como POSTMON, CORREIOS_CONTROL, VIA_CEP, além do próprio CORREIOS e REPUBLICA_VIRTUAL.

##Contribuições Contribuições sempre serão bem-vindas.

Achou algum bug ou deseja ingrar algum provedor? É só enviar um Pull Request.

A integração com novos provedores é bem simples. Em breve eu criarei uma wiki explicando detalhadamente.

###@TODO

Testes.
Criar exceções (cep não existente, cep com formato inválido, provedor falhou).
Fazer sistema de caching nativo.
Criar instruções para o recurso retry.

##Licença GPL2.

upnid / consulta-cep

Maintainers

Details

README