Laravel Brazilian CEPs is a fantastic package to Search addresses quickly in Laravel. These are the minimum requirements to use this package.

• PHP: ^8.1
• Laravel: 9 or newer
• PHP Extensions: fileinfo, mbstring, json

Installation

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

The package will default 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 change the value of the enable_api_consult_cep_route configuration variable to false, as in the 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']

For more details and source code, please visit Github.