README

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!