README

让我们将巴西变成一个API？

简介

此SDK旨在构建灵活，以便所有用户都可以使用BrasilAPI的所有功能和版本。

您可以通过访问此链接来查看BrasilAPI的官方文档。

要求

PHP版本 8.1 或更高；
Guzzle Http 版本 7.4 或更高。

安装

要安装SDK，您必须使用以下命令Composer

composer require andreoneres/brasilapi-php

使用

库的最简单用法如下

<?php

require __DIR__ . '/vendor/autoload.php';

use BrasilApi\Client;

$brasilApi = new Client();

$address = $brasilApi->cep()->get('01001000');

端点

以下您可以查看库中所有可用的端点，默认情况下

银行

在API中搜索所有可用的银行。

$brasilApi->banks()->getList();

通过其代码搜索特定银行。

$brasilApi->banks()->get(1);

CEP

搜索特定CEP。

$brasilApi->cep()->get('01001000');

CEP V2

搜索特定CEP。

$brasilApi->cepV2()->get('01001000');

CNPJ

搜索特定CNPJ。

$brasilApi->cnpj()->get('00000000000191');

经纪公司

通过CNPJ搜索特定经纪公司。

$brasilApi->realtors()->get('76621457000185');

搜索CVM列出的所有经纪公司。

$brasilApi->realtors()->getList();

CPTEC

通过名称搜索城市。

$brasilApi->cptec()->cities('São Paulo');

搜索所有可用的城市。

$brasilApi->cptec()->cities();

搜索巴西各州首府的气象信息。

$brasilApi->cptec()->weatherInCapitals();

通过ICAO代码搜索特定机场的气象信息。

$brasilApi->cptec()->weatherInAirport('SBGR');

通过代码搜索特定城市的气象信息。

$brasilApi->cptec()->weatherInCity(999);

在X天内搜索特定城市的气象信息。

注意：第一个参数是城市的代码，第二个参数是天数。请记住，只能搜索1到6天之间的信息。

$brasilApi->cptec()->weatherInCityInXDays(999, 6);

搜索特定城市的海洋预报。

$brasilApi->cptec()->oceanForecastInCity(999);

在X天内搜索特定城市的海洋预报。

注意：第一个参数是城市的代码，第二个参数是天数。请记住，只能搜索1到6天之间的信息。

$brasilApi->cptec()->oceanForecastInCityInXDays(999, 6);

DDD

搜索具有特定DDD的州和城市。

$brasilApi->ddd()->get(77);

假日

搜索特定年份的所有国家假日。

$brasilApi->holidays()->fromYear(2022);

FIPE

搜索特定车辆类型的所有车辆品牌。

$brasilApi->fipe()->brandsByTypeVehicle('caminhoes');

通过FIPE代码搜索特定车辆的价格。

$brasilApi->fipe()->price('001004-9');

搜索所有现有参考表。

$brasilApi->fipe()->referenceTables();

IBGE

通过简称搜索特定州的全部城市。

$brasilApi->ibge()->stateCities('BA');

搜索所有巴西州的详细信息。

$brasilApi->ibge()->states();

通过简称搜索特定州的详细信息。

$brasilApi->ibge()->state('BA');

ISBN

通过ISBN代码搜索特定图书的详细信息。

$brasilApi->isbn()->book('9788545702870');

NCM

搜索所有NCMs的详细信息。

$brasilApi->ncm()->getList();

搜索特定NCM的详细信息。

$brasilApi->ncm()->get('01012100');

从代码或描述搜索特定NCM的详细信息。

$brasilApi->ncm()->search('01012100');

Pix

搜索当天或前一天所有PIX参与者的详细信息。

$brasilApi->pix()->participants();

注册 BR

搜索特定域的详细信息。

$brasilApi->registerBr()->domain('google.com');

费率

搜索巴西的利率和一些官方指数。

$brasilApi->taxes()->getList();

通过名称/简称搜索特定利率的详细信息。

$brasilApi->taxes()->get('Selic');

创建端点

要添加新端点或覆盖现有端点，您需要遵循以下步骤：

创建一个继承自 BrasilApi\Endpoints\Abstracts\Endpoint 类的类；
在这个类中，您可以实现所有需要的方法，并使用 $this->client->request() 方法向API发送请求。请注意，API的基础URL已嵌入到'Client'中，因此您只需在方法URI中添加路由的补充部分。

示例

URL: https://brasilapi.com.br/api/cep/v2/01001000
BASE_URI: https://brasilapi.com.br/api
URI: /cep/v2/01001000

要将它集成到SDK中，您需要拥有一个 BrasilApi\Client 实例，并使用 addEndpoint 方法，将端点名称和步骤1中创建的类作为参数传递。

示例

<?php

require __DIR__ . '/vendor/autoload.php';

use BrasilApi\Client;
use BrasilApi\Endpoints\Abstracts\Endpoint;

class Hope extends Endpoint
{
    public function getList(): array
    {
        return $this->client->request("/hopes/list");
    }
}

$brasilApi = new Client();

$brasilApi->addEndpoint("hope", Hope::class);

要使用此新端点，您必须按以下方式调用它

$address = $brasilApi->hope()->getList();

注意：端点方法的调用必须使用与在 addEndpoint 方法中定义的相同名称，因为这将用于通过方法魔术 __call 动态查找端点。

注意2：除了创建之外，您还可以覆盖现有端点并更新其方法。如果某个端点发布了新版本，您希望立即使用它，这可能会很有用。这样，您可以覆盖现有端点并更改其URI。

处理异常

如果API返回错误，库将抛出 BrasilApi\Exceptions\BrasilApiException 类型的异常。要捕获此异常，您必须使用 try/catch 块以您希望的方式处理错误。

示例

try {
    $address = $brasilApi->cep()->get('01001000');
} catch (BrasilApiException $e) {
    echo $e->getMessage(); // Retorna a mensagem de erro da API
    echo $e->getCode(); // Retorna o código HTTP da API
    echo $e->getErrors(); // Retorna os erros retornados pela API
    echo $e->getRawResponse(); // Retorna a resposta bruta da API
}

测试

在此项目中，使用 Pest 进行自动化测试实现。要执行它们，如果您尚未安装开发依赖项，请安装它们，并执行以下命令

composer test

贡献

要为此项目做出贡献，您必须遵循以下步骤

对项目进行fork；
为您的更改创建一个分支：git checkout -b feat-fix-refactor/my-changes；
提交您的更改：git commit -m 'feat-fix-refactor: My changes'；
将您的分支推送到远程：git push origin feat-fix-refactor/my-changes；
打开一个pull request。
等待您的pull request被审核。
如果您的pull request被接受，它将被合并到 main 分支。

注意：不要忘记为您的代码创建测试。

许可

请参阅 LICENSE.md。

andreoneres / brasilapi-php

维护者

详细信息