saade / cep-php

v2.0.0 2026-10-13 16:58 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.15.2|^8.0.1
• spatie/laravel-package-tools: ^1.14.0

Requires (Dev)

• orchestra/testbench: ^11.3
• pestphp/pest: ^5.3

MIT

• Saade

• laravel
• cep
• correios
• viacep
• saade
• cep-php
• brasil api

Published on Packagist.org on 2026-10-13 17:05 UTC

README

Installation

You can install the package via composer:

composer require saade/cep-php

Usage

use Saade\Cep\Cep;

$cep = Cep::get('28895-190');

$cep->cep; // 28895190
$cep->state; // RJ
$cep->city; // Rio das Ostras
$cep->neighborhood; // Costazul
$cep->street; // Rua Nelson Pecegueiro do Amaral
$cep->provider; // open-cep / correios / viacep / widenet / correios-alt / brasil-api

Cep::get() returns null when no provider can resolve the CEP.

How it works

1. OpenCEP is queried first.
2. If it can't resolve the CEP, Correios, ViaCEP, WideNet, Correios (alt) and BrasilAPI are queried concurrently and the first one to answer wins.

You may also race the providers of your choice:

use Saade\Cep\Cep;
use Saade\Cep\Providers\BrasilApiProvider;
use Saade\Cep\Providers\ViaCepProvider;

$cep = Cep::race('28895-190', [ViaCepProvider::class, BrasilApiProvider::class]);

Or query a single one, which throws when the CEP can't be resolved:

use Saade\Cep\Providers\ViaCepProvider;

$cep = ViaCepProvider::get('28895-190');

Testing

composer test

composer test:live runs the suite that hits the real providers.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Saade
• All Contributors

License

The MIT License (MIT). Please see License File for more information.