README

Biblioteca em PHP para consulta de CEPs brasileiros usando a API pública do ViaCEP.

Requisitos

PHP >= 7.2
Composer
Extensão/config allow_url_fopen habilitada (para file_get_contents)
Acesso à internet (requisições ao ViaCEP)

Instalação

Packagist:
- composer require alexandremrrocha/digital-cep
Local/clone do repositório:
1. Clone este repositório
2. Rode composer install
3. Inclua o autoloader do Composer no seu projeto (require_once 'vendor/autoload.php';)

Uso básico

Exemplo mínimo (veja também exemplo.php):

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

use Alexandre\DigitalCep\Search;

$busca = new Search();

// Aceita CEP com ou sem hífen; prefira 8 dígitos
$resultado = $busca->getAddressFromZipcode('01001000');

if (isset($resultado->erro) && $resultado->erro === true) {
    echo 'CEP não encontrado.';
} else {
    echo $resultado->logradouro . ', ' . $resultado->bairro . ' - '
        . $resultado->localidade . '/' . $resultado->uf;
}

Resposta típica do ViaCEP:

{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "ibge": "3550308",
  "gia": "1004",
  "ddd": "11",
  "siafi": "7107"
}

Detalhes de implementação

Endpoint utilizado: https://viacep.com.br/ws/{CEP}/json
Método principal: Alexandre\DigitalCep\Search::getAddressFromZipcode(string $zipCode): object
Retorno: objeto (resultante do json_decode) com os campos do ViaCEP; verifique a propriedade erro para CEPs inválidos

Testes

Instale as dependências de desenvolvimento: composer install
Execute: vendor/bin/phpunit

Observação: os testes realizam chamadas reais ao ViaCEP (necessário acesso à internet).

Licença

Este projeto está licenciado sob a licença MIT. Consulte LICENSE para mais detalhes.

Créditos

Dados de CEP: ViaCEP

alexandremrrocha / digital-cep

Maintainers

Details