README

Minimum requirements

• PHP: ^8.1, ^8.2, ^8.3 ^8.4
• Laravel: 9, 10, 11 or 12
• PHP Extensions: fileinfo, mbstring, json

Install

Require this package in your composer.json and update composer. This will download the package and the dependencies libraries also.

composer require lsnepomuceno/laravel-brazilian-ceps

Export the settings file using the command below

php artisan vendor:publish --tag=brazilian-ceps

Usage

Using CepService:

<?php use LSNepomuceno\LaravelBrazilianCeps\Services\CepService; class ExampleController() { // PHP 8: Constructor property promotion public function __construct(protected CepService $cepService) { } public function dummyFunction(string|int $cep){ $address = $this->cepService->get($cep); dd($address); } }

The returned value will have the structure below, see CepEntity:

 LSNepomuceno\LaravelBrazilianCeps\Entities\CepEntity { city: string, cep: string, street: string, state: string, uf: string, neighborhood: string, number: string | int | null, complement: string | null, }

❗ By default, if the CEP is not found, the returned value will be null. If you need exception handling, the option can be enabled in the configuration file.

// config/brazilian-ceps.php <?php 'throw_not_found_exception' => true 

❗ After setting the value of the "throw_not_found_exception" variable to true, remember to update your code:

<?php use LSNepomuceno\LaravelBrazilianCeps\Services\CepService; use LSNepomuceno\LaravelBrazilianCeps\Exceptions\CepNotFoundException; class ExampleController() { // PHP 8: Constructor property promotion public function __construct(protected CepService $cepService) { } public function dummyFunction(string|int $cep){ try { $address = $this->cepService->get($cep); dd($address); } catch(CepNotFoundException $e) { // TODO necessary } } }

Route API

By default, the package will provide an API route for looking up addresses, as specified below.

❗ In some cases it may be necessary to deactivate this route, in which case just change the value of the "enable_api_consult_cep_route" configuration variable to false, as example below:

// config/brazilian-ceps.php <?php 'enable_api_consult_cep_route' => false 

❗ You can also change the message if the CEP is not found:

// config/brazilian-ceps.php <?php 'not_found_message' => 'Type here the message you want.' 

❗ The initial middleware of the route is "guest", if it is necessary to modify it, just adjust the configuration file:

// config/brazilian-ceps.php <?php 'api_route_middleware' => ['guest'] 

Cache Results

By default, the results cache are cached and have a lifetime of 30 days, if you need to disable or change the lifetime, just update the configuration variables, as described below.

// config/brazilian-ceps.php <?php 'cache_results' => true, 'cache_lifetime_in_days' => 30 

Tests

To ensure the delivery of data, several public providers are used, with this, the need to standardize and apply tests for better code quality was seen. About 70+ tests are included in the package.

Tests can be verified through the badge

License

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