README

最低要求

• PHP: ^8.1, ^8.2 或 ^8.3
• Laravel: 9, 10 或 11
• PHP 扩展：fileinfo, mbstring, json

安装

在 composer.json 中要求此包并更新 composer。这将下载包及其依赖库。

composer require lsnepomuceno/laravel-brazilian-ceps

使用以下命令导出设置文件

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

用法

使用 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);
    }
}

返回值将具有以下结构，请参阅 CepEntity

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

❗ 默认情况下，如果找不到 CEP，则返回值将为 null。如果需要异常处理，可以在配置文件中启用此选项。

// config/brazilian-ceps.php

<?php
  
  'throw_not_found_exception' => true
  

❗ 将 "throw_not_found_exception" 变量的值设置为 true 后，请记得更新您的代码

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

API 路由

默认情况下，该包将提供一个用于查找地址的 API 路由，如下所示。

❗ 在某些情况下，可能需要禁用此路由，在这种情况下，只需将 "enable_api_consult_cep_route" 配置变量的值更改为 false，如下所示

// config/brazilian-ceps.php

<?php
  
  'enable_api_consult_cep_route' => false
  

❗ 您还可以更改找不到 CEP 时的消息

// config/brazilian-ceps.php

<?php
  
  'not_found_message' => 'Type here the message you want.'
  

❗ 路由的初始中间件是 "guest"，如果需要修改它，只需调整配置文件

// config/brazilian-ceps.php

<?php
  
  'api_route_middleware' => ['guest']
  

缓存结果

默认情况下，结果缓存已缓存，有效期为 30 天。如果您需要禁用或更改有效期，只需更新配置变量，如下所述。

// config/brazilian-ceps.php

<?php
  
  'cache_results' => true,
  
  'cache_lifetime_in_days' => 30
  

测试

为了确保数据传输，使用了多个公共提供者，因此，为了提高代码质量，有必要标准化并应用测试。该包中包含约 70+ 个测试。

测试可以通过以下徽章验证

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅 许可证文件。