PHP Classes

Laravel Brazilian CEPs: Search locations and zip codes in Brazil

Recommend this page to a friend!
  Info   View files Documentation   View files View files (49)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog (1)    
Ratings Unique User Downloads Download Rankings
Not yet rated by the usersTotal: 27 All time: 11,117 This week: 455Up
Version License PHP version Categories
laravel-brazilian-ce 1.0.0Custom (specified...5PHP 5, Searching, Web services, Geogr...
Description 

Author

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

Innovation Award
PHP Programming Innovation award nominee
December 2022
Number 3
Many e-commerce sites that sell physical products need to be able to check if the customer addresses are correct.

Usually, those sites use an external API to check if the zip code of a customer's address is correct for a given city location.

This package provides a solution for e-commerce sites with customers in Brazil using the Laravel framework.

It provides a way to check Brazilian CEP zip codes using at least one of many supported APIs. This way, it provides a redundant solution that may still work if one of the zip code API fails, as it can use another of the supported APIs that works.

Manuel Lemos
Picture of Lucas Nepomuceno
  Performance   Level  
Name: Lucas Nepomuceno <contact>
Classes: 2 packages by
Country: Brazil Brazil
Age: 29
All time rank: 4297349 in Brazil Brazil
Week rank: 71 Up4 in Brazil Brazil Up
Innovation award
Innovation award
Nominee: 2x

Winner: 1x

Documentation

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


  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

 Version Control Unique User Downloads Download Rankings  
 100%
Total:27
This week:0
All time:11,117
This week:455Up