README

这是针对ケンオール 📮 郵便番号・住所検索API的非官方PHP客户端。该包由个人开发，不是由Open Collector, Inc.提供的。

该包处于开发初期阶段，目前以现状和不可靠的形式提供。已经实现了用于常规用途的基本功能，但错误处理等尚未实现。欢迎通过Pull Request添加功能和改进。

要使用此包进行邮政编码搜索，需要从ケンオール ホーム获取API密钥。

安装

使用Composer。

composer require zonuexe/kenall

此包使用php-http/discovery来利用已安装的PSR-HTTP包。

如果在使用时出现以下错误，则可能是因为包不足。

PHP Fatal error:  Uncaught Http\Discovery\Exception\DiscoveryFailedException: Could not find resource using any discovery strategy. Find more information at http://docs.php-http.org/en/latest/discovery.html#common-errors
 - Puli Factory is not available
 - No valid candidate found using strategy "Http\Discovery\Strategy\CommonClassesStrategy". We tested the following candidates: Nyholm\Psr7\Factory\HttplugFactory, Http\Message\MessageFactory\GuzzleMessageFactory, Http\Message\MessageFactory\DiactorosMessageFactory, Http\Message\MessageFactory\SlimMessageFactory.
 - No valid candidate found using strategy "Http\Discovery\Strategy\CommonPsr17ClassesStrategy". We tested the following candidates: .

请使用Composer从以下虚拟包中选择任意组合进行安装。

• psr/http-factory-implementation
• psr/http-client-implementation

如果您正在使用Guzzle，则可以使用以下命令更新到最新版本：

composer require guzzlehttp/guzzle guzzlehttp/psr7

API

function find(string $postal_code): AddressResolverResponse

这是一个为那些不想费心考虑的邮编搜索者提供的函数。

在调用此函数之前，需要设置环境变量 'KENALL_AUTHORIZATION_TOKEN'。另外，内部会缓存 create_client() 的结果。

参数 string $postal_code 必须是7位数字的字符串。

function create_client(string $api_key): KenallClient

这是一个为想要以面向对象的方式操作API客户端的人提供的函数。

内部使用 php-http/discovery 来自动检测PSR-18 Http Client 和 PSR-17 Http Factory 的实现类。

class KenallClient

这是一个执行向kenall发送API请求的客户端类。

• findPostalCode(string $postal_code): AddressResolverResponse
  • 对应kenall的 GET /postalcode/:郵便番号 API
  • 参数 string $postal_code 必须是7位数字的字符串。

class AddressResolverResponse

这是一个对应kenall的 GET /postalcode/:郵便番号 API返回值的对象。

echo $response->version, PHP_EOL;
// => "2021-01-29"

此对象实现了 ArrayAccess 和迭代器，支持使用数组或 foreach 方法获取数据。可以使用这些方法获取 Address。

class Address (邮政区划记录)

这是一个类似于一般意义上的“地址”的类。属性遵循ケンオール的文档。

使用提示

初学者

请将可从ケンオール获取的API密钥设置为环境变量 KENALL_AUTHORIZATION_TOKEN。

setenv('KENALL_AUTHORIZATION_TOKEN', YOUR_API_KEY);

$postal_code = '1000001';
$area = zonuexe\Kenall\find('1000001')[0];
// => 東京都千代田区千代田

中级者

在这种情况下，不需要将令牌设置为环境变量。

$client = zonuexe\Kenall\create_client(getenv('KENALL_AUTHORIZATION_TOKEN'));

$postal_code = '1000001';
foreach ($client->findPostalCode($postal_code) as $area) {
    printf("%s%s%s\n", $area->prefecture, $area->city, $area->town);
}
// => 東京都千代田区千代田

高级者

如果直接将上述方法集成到代码中，在单元测试等情况下可能会对kenall API进行请求，存在风险。可以通过注入PSR-18的HTTP客户端类来替换测试时的HTTP客户端，以避免在实现代码中直接使用HTTP客户端。

$http_client = new Your\Http\MockCloent()
$client = zonuexe\Kenall\create_client($api_key, $http_client);

或者，根据PHP-HTTP Discovery的文档来设置MockClient，可以在不修改实现代码的情况下避免使用HTTP客户端。

版权

版权所有 2021 USAMI Kenta

本软件依据Apache License 2.0（“许可证”）许可；除非遵守许可证规定或书面同意，否则不得使用此文件。您可以在以下位置获取许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可证下分发的软件按“现状”提供，不提供任何明示或暗示的保证或条件。有关许可证的具体语言规定、权限和限制，请参阅许可证。