lsnepomuceno / laravel-brazilian-ceps
A package for querying zip codes for Brazilian addresses.
Installs: 662
Dependents: 0
Suggesters: 3
Security: 0
Stars: 31
Watchers: 3
Forks: 3
Open Issues: 1
Type:package
Requires
- php: ^8.1 || ^8.2 || ^8.3
- ext-fileinfo: *
- ext-json: *
- ext-mbstring: *
- guzzlehttp/guzzle: ^7
- illuminate/http: ^9 || ^10 || ^11
- illuminate/support: ^9 || ^10 || ^11
Requires (Dev)
- nunomaduro/collision: ^6 || ^7 || ^8
- orchestra/testbench: ^7 || ^8 || ^9
Suggests
- lsnepomuceno/laravel-a1-pdf-sign: Sign PDF files with valid x509 certificates.
README
Minimum requirements
- PHP: ^8.1, ^8.2 or ^8.3
- Laravel: 9, 10 or 11
- 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.