PHP Classes

Laravel Brazilian CEPs: Search locations and zip codes in Brazil

Recommend this page to a friend!

  Author Author  
Picture of Lucas Nepomuceno
Name: Lucas Nepomuceno <contact>
Classes: 2 packages by
Country: Brazil Brazil
Innovation award
Innovation award
Nominee: 2x

Winner: 1x


  Detailed description   Download Download .zip .tar.gz   Install with Composer Install with Composer  
This package can search locations and zip codes in Brazil.

It provides a Laravel service, controllers, and resources to send HTTP requests to several different APIs of Brazilian companies to get the location details associated with the CEP zip code.

Currently, it can access APIs from:

- ApiCep

- BrasilApi

- CepLa

- OpenCep

- Pagarme

- Postomon

- ViaCep

Details

<h1 align="center">Search addresses easily with Laravel Brazilian CEPs</h1>

<p align="center"> <a href="https://github.com/lsnepomuceno/laravel-brazilian-ceps/releases/latest">

<img src="http://poser.pugx.org/lsnepomuceno/laravel-brazilian-ceps/v" alt="Latest Stable Version">

</a> <a href="https://packagist.org/packages/lsnepomuceno/laravel-brazilian-ceps/stats">

<img src="http://poser.pugx.org/lsnepomuceno/laravel-brazilian-ceps/downloads" alt="Total Downloads">

</a> <a href="https://github.com/lsnepomuceno/laravel-brazilian-ceps/tree/dev">

<img src="http://poser.pugx.org/lsnepomuceno/laravel-brazilian-ceps/v/unstable" alt="Latest Unstable Version">

</a> <a href="https://github.com/lsnepomuceno/laravel-brazilian-ceps/blob/main/LICENSE.md">

<img src="https://poser.pugx.org/lsnepomuceno/laravel-brazilian-ceps/license" alt="License">

</a> <a href="https://github.com/lsnepomuceno/laravel-brazilian-ceps/actions/workflows/main_action.yml">

<img src="https://github.com/lsnepomuceno/laravel-brazilian-ceps/actions/workflows/action_pr_main.yml/badge.svg?branch=main" alt="Tests">

</a> </p>

Minimum requirements

  • PHP: ^8.1
  • Laravel: 9 or newer
  • 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,
  }

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

<hr>

Route API

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

<table> <thead>

<tr>
  <th>Verb</th>
  <th>URI</th>
  <th>Invokable Controller</th>
  <th>Route Name</th>
</tr>

</thead>

<tbody>

<tr>
  <td>GET</td>
  <td>api/consult-cep/{cep}</td>
  <td>LSNepomuceno\LaravelBrazilianCeps\Controllers\ConsultCepController</td>
  <td>consult-cep.api</td>
</tr>

</tbody> </table>

: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']
  

<hr>

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 tests badge

License

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


  Classes of Lucas Nepomuceno  >  Laravel Brazilian CEPs  >  Download Download .zip .tar.gz  >  Support forum Support forum  >  Blog Blog  >  RSS 1.0 feed RSS 2.0 feed Latest changes  
Name: Laravel Brazilian CEPs
Base name: laravel-brazilian-ce
Description: Search locations and zip codes in Brazil
Version: 1.0.0
PHP version: 5
License: Custom (specified in a license file)
 
  Groups   Applications   Files Files  

  Groups  
Group folder image PHP 5 Classes using PHP 5 specific features View top rated classes
Group folder image Searching Search engines, crawling and indexing View top rated classes
Group folder image Web services Web data clipping, SOAP or XML-RPC clients and servers View top rated classes
Group folder image Geography Locations, mapping and demographics View top rated classes


  Applications that use this package  
No pages of applications that use this class were specified.

Add link image If you know an application of this package, send a message to the author to add a link here.

  Files folder image Files  
File Role Description
Files folder image.github (1 file, 2 directories)
Files folder imagesrc (1 file, 12 directories)
Files folder imagetests (1 file, 3 directories)
Accessible without login Plain text file CODE_OF_CONDUCT.md Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file CONTRIBUTING.md Data Auxiliary data
Accessible without login Plain text file LICENSE.md Lic. License text
Accessible without login Plain text file phpunit.xml Data Auxiliary data
Accessible without login Plain text file readme.md Doc. Class source

  Files folder image Files  /  .github  
File Role Description
Files folder imageISSUE_TEMPLATE (2 files)
Files folder imageworkflows (1 file)
  Accessible without login Plain text file dependabot.yml Data Auxiliary data

  Files folder image Files  /  .github  /  ISSUE_TEMPLATE  
File Role Description
  Accessible without login Plain text file bug_report.md Data Auxiliary data
  Accessible without login Plain text file feature_request.md Data Auxiliary data

  Files folder image Files  /  .github  /  workflows  
File Role Description
  Accessible without login Plain text file action_pr_main.yml Data Auxiliary data

  Files folder image Files  /  src  
File Role Description
Files folder imageCepProviders (9 files)
Files folder imageConfig (1 file)
Files folder imageContracts (1 file)
Files folder imageControllers (2 files)
Files folder imageEntities (1 file)
Files folder imageEnums (1 file)
Files folder imageExceptions (1 file)
Files folder imageFacades (1 file)
Files folder imageHelpers (1 file)
Files folder imageResources (1 file)
Files folder imageRoutes (1 file)
Files folder imageServices (1 file)
  Plain text file LaravelBrazilianCepsServiceProvider.php Class Class source

  Files folder image Files  /  src  /  CepProviders  
File Role Description
  Plain text file ApiCep.php Class Class source
  Plain text file BaseCepProvider.php Class Class source
  Plain text file BrasilApiV1.php Class Class source
  Plain text file BrasilApiV2.php Class Class source
  Plain text file CepLa.php Class Class source
  Plain text file OpenCep.php Class Class source
  Plain text file Pagarme.php Class Class source
  Plain text file Postomon.php Class Class source
  Plain text file ViaCep.php Class Class source

  Files folder image Files  /  src  /  Config  
File Role Description
  Accessible without login Plain text file config.php Aux. Auxiliary script

  Files folder image Files  /  src  /  Contracts  
File Role Description
  Plain text file ConsultableCEPProvider.php Class Class source

  Files folder image Files  /  src  /  Controllers  
File Role Description
  Plain text file ConsultCepController.php Class Class source
  Plain text file Controller.php Class Class source

  Files folder image Files  /  src  /  Entities  
File Role Description
  Plain text file CepEntity.php Class Class source

  Files folder image Files  /  src  /  Enums  
File Role Description
  Plain text file States.php Class Class script

  Files folder image Files  /  src  /  Exceptions  
File Role Description
  Plain text file CepNotFoundException.php Class Class source

  Files folder image Files  /  src  /  Facades  
File Role Description
  Plain text file CEP.php Class Class source

  Files folder image Files  /  src  /  Helpers  
File Role Description
  Plain text file MaskHelper.php Class Class source

  Files folder image Files  /  src  /  Resources  
File Role Description
  Plain text file CepResource.php Class Class source

  Files folder image Files  /  src  /  Routes  
File Role Description
  Plain text file api.php Class Class source

  Files folder image Files  /  src  /  Services  
File Role Description
  Plain text file CepService.php Class Class source

  Files folder image Files  /  tests  
File Role Description
Files folder imageFeature (10 files)
Files folder imageHelpers (1 file)
Files folder imageUnit (5 files)
  Plain text file TestCase.php Class Class source

  Files folder image Files  /  tests  /  Feature  
File Role Description
  Plain text file ApiCepProviderTest.php Class Class source
  Plain text file BrasilApiV1ProviderTest.php Class Class source
  Plain text file BrasilApiV2ProviderTest.php Class Class source
  Plain text file CepFacadeTest.php Class Class source
  Plain text file CepLaProviderTest.php Class Class source
  Plain text file ConsultCepApiRouteTest.php Class Class source
  Plain text file OpenCepProviderTest.php Class Class source
  Plain text file PagarmeCepProviderTest.php Class Class source
  Plain text file PostomonCepProviderTest.php Class Class source
  Plain text file ViaCepProviderTest.php Class Class source

  Files folder image Files  /  tests  /  Helpers  
File Role Description
  Plain text file DefaultValues.php Class Class source

  Files folder image Files  /  tests  /  Unit  
File Role Description
  Plain text file CepEntityTest.php Class Class source
  Plain text file CepNotFoundExceptionTest.php Class Class source
  Plain text file ConfigTest.php Class Class source
  Plain text file MaskHelperTest.php Class Class source
  Plain text file StatesEnumTest.php Class Class source

Install with Composer Install with Composer - Download Download all files: laravel-brazilian-ce.tar.gz laravel-brazilian-ce.zip
NOTICE: if you are using a download manager program like 'GetRight', please Login before trying to download this archive.
  Files folder image Files  
File Role Description
Files folder image.github (1 file, 2 directories)
Files folder imagesrc (1 file, 12 directories)
Files folder imagetests (1 file, 3 directories)
Accessible without login Plain text file CODE_OF_CONDUCT.md Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file CONTRIBUTING.md Data Auxiliary data
Accessible without login Plain text file LICENSE.md Lic. License text
Accessible without login Plain text file phpunit.xml Data Auxiliary data
Accessible without login Plain text file readme.md Doc. Class source

  Files folder image Files  /  .github  
File Role Description
Files folder imageISSUE_TEMPLATE (2 files)
Files folder imageworkflows (1 file)
  Accessible without login Plain text file dependabot.yml Data Auxiliary data

  Files folder image Files  /  .github  /  ISSUE_TEMPLATE  
File Role Description
  Accessible without login Plain text file bug_report.md Data Auxiliary data
  Accessible without login Plain text file feature_request.md Data Auxiliary data

  Files folder image Files  /  .github  /  workflows  
File Role Description
  Accessible without login Plain text file action_pr_main.yml Data Auxiliary data

  Files folder image Files  /  src  
File Role Description
Files folder imageCepProviders (9 files)
Files folder imageConfig (1 file)
Files folder imageContracts (1 file)
Files folder imageControllers (2 files)
Files folder imageEntities (1 file)
Files folder imageEnums (1 file)
Files folder imageExceptions (1 file)
Files folder imageFacades (1 file)
Files folder imageHelpers (1 file)
Files folder imageResources (1 file)
Files folder imageRoutes (1 file)
Files folder imageServices (1 file)
  Plain text file LaravelBrazilianCepsServiceProvider.php Class Class source

  Files folder image Files  /  src  /  CepProviders  
File Role Description
  Plain text file ApiCep.php Class Class source
  Plain text file BaseCepProvider.php Class Class source
  Plain text file BrasilApiV1.php Class Class source
  Plain text file BrasilApiV2.php Class Class source
  Plain text file CepLa.php Class Class source
  Plain text file OpenCep.php Class Class source
  Plain text file Pagarme.php Class Class source
  Plain text file Postomon.php Class Class source
  Plain text file ViaCep.php Class Class source

  Files folder image Files  /  src  /  Config  
File Role Description
  Accessible without login Plain text file config.php Aux. Auxiliary script

  Files folder image Files  /  src  /  Contracts  
File Role Description
  Plain text file ConsultableCEPProvider.php Class Class source

  Files folder image Files  /  src  /  Controllers  
File Role Description
  Plain text file ConsultCepController.php Class Class source
  Plain text file Controller.php Class Class source

  Files folder image Files  /  src  /  Entities  
File Role Description
  Plain text file CepEntity.php Class Class source

  Files folder image Files  /  src  /  Enums  
File Role Description
  Plain text file States.php Class Class script

  Files folder image Files  /  src  /  Exceptions  
File Role Description
  Plain text file CepNotFoundException.php Class Class source

  Files folder image Files  /  src  /  Facades  
File Role Description
  Plain text file CEP.php Class Class source

  Files folder image Files  /  src  /  Helpers  
File Role Description
  Plain text file MaskHelper.php Class Class source

  Files folder image Files  /  src  /  Resources  
File Role Description
  Plain text file CepResource.php Class Class source

  Files folder image Files  /  src  /  Routes  
File Role Description
  Plain text file api.php Class Class source

  Files folder image Files  /  src  /  Services  
File Role Description
  Plain text file CepService.php Class Class source

  Files folder image Files  /  tests  
File Role Description
Files folder imageFeature (10 files)
Files folder imageHelpers (1 file)
Files folder imageUnit (5 files)
  Plain text file TestCase.php Class Class source

  Files folder image Files  /  tests  /  Feature  
File Role Description
  Plain text file ApiCepProviderTest.php Class Class source
  Plain text file BrasilApiV1ProviderTest.php Class Class source
  Plain text file BrasilApiV2ProviderTest.php Class Class source
  Plain text file CepFacadeTest.php Class Class source
  Plain text file CepLaProviderTest.php Class Class source
  Plain text file ConsultCepApiRouteTest.php Class Class source
  Plain text file OpenCepProviderTest.php Class Class source
  Plain text file PagarmeCepProviderTest.php Class Class source
  Plain text file PostomonCepProviderTest.php Class Class source
  Plain text file ViaCepProviderTest.php Class Class source

  Files folder image Files  /  tests  /  Helpers  
File Role Description
  Plain text file DefaultValues.php Class Class source

  Files folder image Files  /  tests  /  Unit  
File Role Description
  Plain text file CepEntityTest.php Class Class source
  Plain text file CepNotFoundExceptionTest.php Class Class source
  Plain text file ConfigTest.php Class Class source
  Plain text file MaskHelperTest.php Class Class source
  Plain text file StatesEnumTest.php Class Class source

Install with Composer Install with Composer - Download Download all files: laravel-brazilian-ce.tar.gz laravel-brazilian-ce.zip
NOTICE: if you are using a download manager program like 'GetRight', please Login before trying to download this archive.