Minimum requirements

• PHP: 8.1, 8.2, 8.3 or 8.4
• Laravel: 9, 10, 11, 12 or 13
• 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 am2tec/laravel-brazilian-ceps

Laravel package discovery will register the service provider automatically.

Export the settings file using the command below:

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

Usage

Using CepService:

<?php

use Am2Tec\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:

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

:exclamation: 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
  

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

<?php

use Am2Tec\LaravelBrazilianCeps\Services\CepService;
use Am2Tec\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.

:exclamation: 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
  

:exclamation: 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.'
  

:exclamation: 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.