PHPackages kamoca/laravel-cep-package - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. kamoca/laravel-cep-package ActiveLibrary[Utility & Helpers](/categories/utility) kamoca/laravel-cep-package ========================== Pacote para a consulta de CEPs utilizando 1.0.0(2mo ago)00MITPHPPHP ^8.0 Since May 13Pushed 2mo agoCompare [ Source](https://github.com/KauanCalheiro/laravel-cep-package)[ Packagist](https://packagist.org/packages/kamoca/laravel-cep-package)[ Docs](https://github.com/KauanCalheiro/laravel-cep-package)[ RSS](/packages/kamoca-laravel-cep-package/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (6)Versions (2)Used By (0) kamoca/cep ========== [](#kamocacep) Pacote Laravel para consulta paralela de CEPs com fallback automático entre provedores. Requisitos ---------- [](#requisitos) - PHP 8.0+ - Laravel 12 ou 13 Instalação ---------- [](#instalação) ``` composer require kamoca/cep ``` O pacote é registrado automaticamente via Laravel Package Discovery. Configuração ------------ [](#configuração) Publique o arquivo de configuração: ``` php artisan vendor:publish --tag=cep-config ``` Isso cria `config/cep.php`. As opções disponíveis: ``` return [ 'timeout_ms' => env('CEP_TIMEOUT_MS', 15000), 'cache' => [ 'enabled' => env('CEP_CACHE_ENABLED', true), 'ttl' => env('CEP_CACHE_TTL', 3600), // segundos 'key' => env('CEP_CACHE_KEY', 'cep.lookup.%s'), ], 'cep_class' => \Kamoca\Cep\Transformers\CepTransformer::class, 'providers' => [ 'via_cep' => [ 'enabled' => env('FALLBACK_CEP_API_VIA_CEP_ENABLED', true), 'class' => \Kamoca\Cep\Providers\ViaCepProvider::class, ], 'brasil_api' => [ 'enabled' => env('FALLBACK_CEP_API_BRASIL_API_ENABLED', true), 'class' => \Kamoca\Cep\Providers\BrasilApiProvider::class, ], ], ]; ``` Ou via `.env`: ``` CEP_TIMEOUT_MS=15000 CEP_CACHE_ENABLED=true CEP_CACHE_TTL=3600 ``` Uso --- [](#uso) ### Via injeção de dependência [](#via-injeção-de-dependência) ``` use Kamoca\Cep\CepResolver; class EnderecoController extends Controller { public function __construct(private CepResolver $cep) {} public function show(string $cep) { $resultado = $this->cep->resolve($cep)->toArray(); return response()->json($resultado); } } ``` ### Via Facade [](#via-facade) ``` use Kamoca\Cep\Facade\Cep; $resultado = Cep::resolve('95914-100')->toArray(); ``` ### Formato da resposta [](#formato-da-resposta) ``` { "cep": "95914100", "street": "Rua Bento Gonçalves", "neighborhood": "Universitário", "city": "Lajeado", "state": "RS", "provider": "via_cep", "response_time_ms": 312, "response_time_s": 0.312, "cached": false } ``` CampoDescrição`provider`Provedor que respondeu primeiro (`via_cep` ou `brasil_api`)`response_time_ms`Tempo de resposta em milissegundos`response_time_s`Tempo de resposta em segundos`cached``true` quando veio do cache, `false` quando foi busca real### Tratamento de erros [](#tratamento-de-erros) CEP inválido ou não encontrado lança `CepResolutionException`: ``` use Kamoca\Cep\Exceptions\CepResolutionException; try { $resultado = Cep::resolve('00000000')->toArray(); } catch (CepResolutionException $e) { // CEP não encontrado ou todos os provedores falharam return response()->json(['error' => 'CEP não encontrado'], 404); } ``` Personalização -------------- [](#personalização) ### Classe de CEP customizada [](#classe-de-cep-customizada) Para adicionar campos ou lógica própria ao objeto de retorno, implemente `CepContract`: ``` use Kamoca\Cep\Contracts\CepContract; use Kamoca\Cep\Normalizers\CepNormalize; class MeuCep implements CepContract { public function __construct( public readonly string $cep, public readonly string $cidade, public readonly string $estado, ) {} public static function fromNormalizer(CepNormalize $payload): static { return new static( cep: $payload->cep, cidade: $payload->city, estado: $payload->state, ); } public function toArray(): array { return [ 'cep' => $this->cep, 'cidade' => $this->cidade, 'estado' => $this->estado, ]; } public function jsonSerialize(): array { return $this->toArray(); } } ``` Registre em `config/cep.php`: ``` 'cep_class' => App\Cep\MeuCep::class, ``` ### Provedor customizado [](#provedor-customizado) Para adicionar uma nova fonte de CEP, estenda `BaseCepProvider`: ``` use GuzzleHttp\Psr7\Request; use Kamoca\Cep\Normalizers\CepNormalize; use Kamoca\Cep\Providers\BaseCepProvider; class MinhaApiProvider extends BaseCepProvider { public function buildRequest(string $cep): Request { return new Request('GET', "https://minha-api.com/cep/{$cep}"); } protected function normalize(array $payload): CepNormalize { return new CepNormalize( cep: $payload['codigo'] ?? '', street: $payload['logradouro'] ?? '', neighborhood: $payload['bairro'] ?? '', city: $payload['municipio'] ?? '', state: $payload['uf'] ?? '', provider: $this->getName(), ); } } ``` Registre em `config/cep.php`: ``` 'providers' => [ 'minha_api' => [ 'enabled' => true, 'class' => App\Cep\MinhaApiProvider::class, ], // provedores padrão continuam funcionando em paralelo 'via_cep' => ['enabled' => true, 'class' => \Kamoca\Cep\Providers\ViaCepProvider::class], 'brasil_api' => ['enabled' => true, 'class' => \Kamoca\Cep\Providers\BrasilApiProvider::class], ], ``` Todos os provedores habilitados são consultados em paralelo — o primeiro a responder com sucesso é usado. ### Health Score 34 — LowBetter than 75% of packages Maintenance86 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 72d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/110562396?v=4)[Kauan Calheiro](/maintainers/KauanCalheiro)[@KauanCalheiro](https://github.com/KauanCalheiro) --- Top Contributors [![KauanCalheiro](https://avatars.githubusercontent.com/u/110562396?v=4)](https://github.com/KauanCalheiro "KauanCalheiro (16 commits)") --- Tags laravelzip codecepzipcodeviacepBrasilApi ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/kamoca-laravel-cep-package/health.svg) ``` [![Health](https://phpackages.com/badges/kamoca-laravel-cep-package/health.svg)](https://phpackages.com/packages/kamoca-laravel-cep-package) ``` ### Alternatives [nativephp/mobile NativePHP for Mobile 1.1k75.1k106](/packages/nativephp-mobile)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export)[venturedrake/laravel-crm A free open source CRM built as a package for laravel projects 44611.3k](/packages/venturedrake-laravel-crm)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 255.2k](/packages/aedart-athenaeum)[eslazarev/wildberries-sdk Wildberries OpenAPI clients (generated). 293.1k](/packages/eslazarev-wildberries-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)