README

本软件包提供了用于在PHP应用程序中消费的https://www.postcodeapi.nu/服务的客户端。喜欢这个库吗？请考虑通过在上为我买一杯咖啡来支持我。

入门指南

要安装库，您需要composer，并且应使用php版本 >= 7.0

composer require tfarla/php-postcodeapinu

该库使用名为httpplug的HTTP抽象层，它允许您使用您最喜欢的HTTP客户端与该库一起使用。不想使用guzzle？没问题。看看其他可用的适配器。该库不会强迫您这样做。Httpplug需要一些配置才能工作，所以请阅读http://docs.php-http.org/en/latest/httplug/users.html上的说明。

执行以下命令安装php-http/curl-client

composer require php-http/curl-client

<?php

use TFarla\PostcodeApiNu\Client;

$curl = new Http\Client\Curl\Client();

$token = 'superSecretToken';

$client = new Client($curl, $token);

但我推荐使用guzzle适配器，因为它提供了更细致的控制。执行以下命令安装php-http/guzzle6-adapter适配器

composer require php-http/guzzle6-adapter

<?php

use TFarla\PostcodeApiNu\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

$config = ['timeout' => 2];
$adapter = GuzzleAdapter::createWithConfig($config);
$token = 'superSecretToken';

$client = new Client($adapter, $token);

使用方法

现在您已安装http适配器和php-postcodeapinu库。您可以通过客户端使用它们的API。

获取地址

<?php
use TFarla\PostcodeApiNu\Client;

$client = new Client($adapter, $token);

$addresses = $client->getAddress('0268200000075156');

$address = null;
if ($addresses->isEmpty() === false) {
    $address = $addresses[0];
}

获取地址列表

<?php

use TFarla\PostcodeApiNu\Client;
use TFarla\PostcodeApiNu\Address;

$client = new Client($adapter, $token);

$addresses = $client->getAddresses();
/** @var Address $address */
foreach ($addresses as $address) {
    // Do something with the address
    $address->getPostcode();
}

搜索地址

<?php

use TFarla\PostcodeApiNu\Client;
use TFarla\PostcodeApiNu\Address;

$client = new Client($adapter, $token);

$postcode = '1234AJ';
$houseNumber = '138E10';

$addresses = $client->getAddresses($postcode, $houseNumber);
/** @var Address $address */
foreach ($addresses as $address) {
    // Do something with the address
    $address->getPostcode();
}

获取单个邮编

<?php

use TFarla\PostcodeApiNu\Client;

$client = new Client($adapter, $token);

$postcodes = $client->getPostcode('1234AJ');
if ($postcodes->isEmpty() === false) {
    $postcode = $postcodes[0];
}

获取所有邮编

<?php

use TFarla\PostcodeApiNu\Client;
use TFarla\PostcodeApiNu\Postcode;

$client = new Client($adapter, $token);

$area = null;
$from = null;

// the area and from parameters are optional and only present for demonstration in this example
$postcodes = $client->getPostcodes($area, $from);
/** @var Postcode $postcode */
foreach ($postcodes as $postcode) {
    $postcode->getCity();
}

地址和邮编类

地址和邮编类都是不可变的数据结构。

异常处理

本软件包使用异常来表示出现错误。异常层次结构如下所述

\TFarla\PostcodeApiNu\
├── Exception.php
├──── BadRequestException.php
├──── NotFoundException.php
├──── RateLimitReachedException.php
└──── UnauthorisedException.php

所有异常都具有getResponse方法，允许开发人员检索原始响应。除此之外，它们是正常的异常。

速率限制

API使用速率限制，并在响应中通信我们的剩余请求以及限制。由于我们需要考虑速率限制，因此它在客户端的每个响应中都存在。

<?php

use TFarla\PostcodeApiNu\Client;

$client = new Client($adapter, $token);

$postcodes = $client->getPostcode('1234AJ');
if ($postcodes->isEmpty() === false) {
    $postcode = $postcodes[0];
}

$rateLimit = $postcodes->getRateLimit();

$rateLimit->getRemaining();
$rateLimit->getLimit();

类图

地址方法

+ getPostcode(): string
+ getPurpose(): string
+ getSurface(): string
+ getMunicipality(): LabeledValue
+ getCity(): LabeledValue
+ getProvince(): LabeledValue
+ getLetter(): string
+ getCenterPoint(): Point
+ getExteriorPoints(): Point[]
+ getHouseNumber(): int
+ getHouseNumberAddition(): string
+ getYear(): int
+ getType(): string
+ getStreet(): string

邮编方法

+ getPostcode(): string
+ getCity(): LabeledValue
+ getMuniciple(): LabeledValue
+ getProvince(): LabeledValue
+ getPoint(): Point
+ getStreets(): string[]

开发

感谢您阅读这份readme文档并考虑开发这个库！为了确保一定程度的职业性和稳定性，这个库是使用测试驱动开发范式开发的。尽管测试已经精心制作，但认为测试中覆盖的行数是质量和稳定性的良好指标是幼稚的。我们不希望让您担心这个库中的错误。因此，我们还使用了一个名为phpstan的工具进行静态分析，以防止与类型相关的错误。为了使这个包可维护，我们还使用了一个名为phpmd的杂乱检测器。

运行测试

composer run tests

运行静态分析

composer run phpstan

运行杂乱检测器

composer run phpmd

安全漏洞

如果您发现任何安全漏洞，请在此存储库的问题中报告它们。