paulo-hortelan/lara-cep

Pacote Laravel para consulta de CEPs brasileiros com múltiplos provedores, cache e orquestração assíncrona opcional.

v1.1.0 2026-05-06 20:17 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.8
• guzzlehttp/promises: ^2.2
• illuminate/cache: ^10.0|^11.0|^12.0
• illuminate/contracts: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• spatie/laravel-package-tools: ^1.14.0

Requires (Dev)

• larastan/larastan: ^2.0.1
• laravel/pint: ^1.0
• nunomaduro/collision: ^7.8
• orchestra/testbench: ^8.29
• pestphp/pest: ^2.20
• pestphp/pest-plugin-arch: ^2.0
• pestphp/pest-plugin-laravel: ^2.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0

MIT

• paulo-hortelan

• laravel
• cep
• brasil
• zip-code
• paulo-hortelan

README

lara-cep é um pacote Laravel para consultar CEPs brasileiros usando múltiplos provedores, com:

• lista de provedores configurável
• TTL de cache configurável
• modo assíncrono configurável (consulta todos os provedores habilitados em paralelo)

O pacote foi inspirado no comportamento do CEP Promise e adaptado para fluxos de pacote Laravel.

Instalação

composer require paulo-hortelan/lara-cep

Publique a configuração:

php artisan vendor:publish --tag=lara-cep-config

Uso Básico

use PauloHortelan\LaraCep\Facades\LaraCep;

$address = LaraCep::find('01001-000');

$address->zipCode;  // 01001000
$address->state;    // SP
$address->city;     // Sao Paulo
$address->district; // Centro
$address->street;   // Praca da Se...
$address->provider; // via_cep, open_cep, brasil_api...

Você também pode chamar:

$address = app('lara-cep')->find('01001000');

Configuração

config/lara-cep.php

return [
    'async' => true,

    'cache' => [
        'enabled' => true,
        'ttl' => 3600,
        'store' => null,
        'prefix' => 'lara_cep',
    ],

    'providers' => [
        'via_cep' => [
            'enabled' => true,
            'class' => PauloHortelan\LaraCep\Providers\ViaCepProvider::class,
        ],

        'open_cep' => [
            'enabled' => true,
            'class' => PauloHortelan\LaraCep\Providers\OpenCepProvider::class,
        ],

        'brasil_api' => [
            'enabled' => true,
            'class' => PauloHortelan\LaraCep\Providers\BrasilApiProvider::class,
        ],

        'cep_aberto' => [
            'enabled' => false,
            'class' => PauloHortelan\LaraCep\Providers\CepAbertoProvider::class,
            'token' => env('LARA_CEP_PROVIDER_CEP_ABERTO_TOKEN', ''),
        ],
    ],
];

Comportamento assíncrono

• async = true: todos os provedores habilitados são consultados em paralelo; a primeira resposta com sucesso vence.
• async = false: os provedores são consultados na ordem configurada até um retornar sucesso.

Comportamento de cache

• a chave de cache usa o prefixo configurado + CEP normalizado
• o TTL é totalmente configurável (cache.ttl)
• o cache pode ser desabilitado (cache.enabled = false)

Tratamento de Erros

use PauloHortelan\LaraCep\Exceptions\CepLookupException;
use PauloHortelan\LaraCep\Exceptions\InvalidCepException;

try {
    $address = LaraCep::find('99999999');
} catch (InvalidCepException $e) {
    // formato de CEP inválido
} catch (CepLookupException $e) {
    // todos os provedores falharam
    $details = $e->toArray();
}

Testes

composer test

Licença

MIT. Veja LICENSE.md.