README

这是一个与框架无关的PHP SDK，用于getAddress.io的地址查找API。

要使用此包，您需要一个getAddress.io提供的API密钥，基本包是免费的。注册时，您将获得访问公共地址信息的API密钥和管理账户的行政API密钥。

此包还依赖于PHP 5.6

安装

安装可以通过composer轻松完成

composer require philcross/getaddress-php

基本用法

首先，您需要getAddress.io提供的两个API密钥，然后创建客户端

$client = new Philcross\GetAddress\Client($apiKey, $administrativeApiKey);

客户端有许多有用的方法，可以帮助您查找地址和管理账户。客户端将知道使用哪个API密钥。

查找公共地址

要查找公共地址，您至少需要一个邮编。您还可以指定一个房产编号，但这不是必需的。find方法将返回一个AddressResponse对象。它包含一个Address对象的数组。

$response = $client->find($postcode, $propertyNumber);

$longitude = $response->getLongitude();
$latitude  = $response->getLatitude();

foreach ($response->getAddresses() as $address) {
    // ...
}

您还可以向find()方法提供一个第三个布尔参数。默认情况下，getAddress.io返回的请求按数字排序。如果您不希望按数字排序，可以提供布尔值false

$response = $client->find('TQ2 6TP', null, false);

// Or if you would prefer to use a named constant to make it easier to read

$response = $client->find('TQ2 6TP', null, Philcross\GetAddress\Responses\Address::SORT_NUMERICALLY);

使用地址对象

地址对象有几个有用的方法

// To retrieve individual address elements
$line1 = $address->getLine1();
$line2 = $address->getLine2();
$line3 = $address->getLine3();
$line4 = $address->getLine4();
$locality = $address->getLocality();
$city = $address->getCity();
$county = $address->getCounty();

$line2 = $address->getLine(2);

还有一个getTown()方法，但这只是getCity()的别名

$address->getTown(); // Torquay
$address->getCity(); // Torquay

要返回关联数组形式的地址，您可以使用toArray()方法

$address->toArray();

// Outputs:

[
    'line_1'    => 'Sample Line 1',
    'line_2'    => 'Sample Line 2',
    'line_3'    => 'Sample Line 3',
    'line_4'    => 'Sample Line 4',
    'locality'  => 'Sample Locality',
    'town_city' => 'Sample City',
    'county'    => 'Sample County',
]

此外，您可以通过向toArray()方法提供一个数组来覆盖数组的键

$address->toArray(['house_name', 'street_address']);

// Outputs:

[
    'house_name'     => 'Sample Line 1',
    'street_address' => 'Sample Line 2',
    'line_3'         => 'Sample Line 3',
    'line_4'         => 'Sample Line 4',
    'locality'       => 'Sample Locality',
    'town_city'      => 'Sample City',
    'county'         => 'Sample County',
]

您还可以使用toString()方法将地址转换为逗号分隔的元素列表。

echo $address->toString();

// You can also cast the object to a string:
echo $address;

Sample Line 1,Sample Line 2,,,Sample Locality,Sample City,Sample County

默认情况下，toString()方法不会删除空元素。这对于将地址转换为CSV记录很有用。如果您想格式化地址为漂亮的字符串，可以删除空元素

echo $address->toString(true);

Sample Line 1,Sample Line 2,Sample Locality,Sample City,Sample County

还有一个辅助方法是sameAs()方法，它接受另一个Address对象来比较。这将比较地址数组以查看它们是否相同

$address->sameAs($address2); // Returns a boolean

检查账户使用情况

您可以使用客户端上的usage()方法快速检查账户使用情况。

如果您不提供任何参数，它将返回当天的当前使用情况。usage方法将返回一个Usage对象

$usage = $client->getUsage();

$usage->getCount();
$usage->getLimit1();
$usage->getLimit2();

// Additional methods for retrieving limits:

$usage->getLimit(1);
$usage->getLimits(); // Returns an array

还有一些额外的辅助方法。要检查您剩余多少请求，直到当天用完

$usage->requestsRemaining();

您还可以向方法提供布尔值true，以返回剩余请求的数量，直到getAddress.io减慢响应速度

$usage->requestsRemaining(true);

// Or of you prefer a more natural language

$usage->requestsRemainingUntilSlowed();

您还可以检查是否超过了限制

$usage->hasExceededLimit();

最后一个，您可以检查是否已请求足够多次，以使getAddress.io减慢响应速度，但不足以停止发送响应。

$usage->isRestricted();

如果您想从以前的日期检索使用情况，可以向usage方法提供一个DateTime对象（或Carbon实例）

$datetime = new DateTime('2017-08-24');

// or...

$datetime = Carbon\Carbon::now();

$client->usage($datetime);

或者，您可以为方法提供日期、月份和年份作为参数。

$client->usage(24, 08, 2017); // $day, $month, $year

私有地址

getAddress.io 允许您提供私有地址。这些地址由您提供，只能通过使用您的 API 令牌访问。

添加新的私有地址

您可以添加新的私有地址。

$address = Philcross\GetAddress\Responses\PrivateAddress::create(
    'line 1',
    'line 2',
    'line 3',
    'line 4',
    'locality',
    'city',
    'county'
);

$response = $client->addPrivateAddress('TQ2 6TP', $address);

创建新的私有地址时，将返回一个 PrivateAddressResponse 对象，该对象包含 getAddress 提供的消息以及您创建的新的 PrivateAddress 对象。

$response->getMessage(); // Returns a string
$response->getAddresses(); // Returns a collection of PrivateAddress objects

PrivateAddress 对象扩展了 Address 对象，因此您仍然可以使用 sameAs() 等方法。此外，PrivateAddress 对象还包含一个 getAddressId() 方法，用于返回您的私有地址记录的 ID。

删除私有地址

如果您有私有地址的 ID 和邮政编码，则可以删除它。

$client->deletePrivateAddress('TQ26TP', 1);

同样，这将返回一个包含消息的 PrivateAddressResponse 对象。

列出私有地址

您可以根据指定的邮政编码列出所有私有地址。

$response = $this->getPrivateAddress('TQ2 6TP');

$response->getAddresses(); // Returns an array

或者，如果您知道财产的 ID，您也可以提供该 ID。

$response = $this->getPrivateAddress('TQ2 6TP', 1);

$response->getAddresses();

安全

getAddress 允许您将域名和 IP 地址列入白名单。

将域名或 IP 地址添加到白名单

$client->addDomainToWhitelist('google.com');
$client->addIpToWhitelist('8.8.8.8');

这两种方法都返回一个 WhitelistResponse 对象，该对象具有 getMessage() 和 getItems() 方法。

$response = $client->addDomainToWhitelist('google.com');

$response->getMessage();
$response->getItems(); // Returns an array

getItems() 方法将始终返回一个包含 Domain 对象或 Ip 对象的数组，但不会同时包含两者。

Domain 和 Ip 对象都包含一个 getId() 方法，用于返回该对象的唯一 ID。《Domain》对象包含一个 getDomain() 方法，而《Ip》对象包含一个 getIp() 方法。

删除现有的白名单项

$response = $client->deleteDomainFromWhitelist($id);
$response = $client->deleteIpFromWhitelist($id);

这两种方法都将返回一个 WhitelistResponse 对象。

列出白名单域名或 IP 地址

$response = $client->getWhitelistedDomains();
$response = $client->getWhitelistedIpAddresses();

每个方法还有一个与方法名称相关联的单数版本，如果您知道白名单项的 ID。

$response = $client->getWhitelistedDomain($id);
$response = $client->getWhitelistedIpAddress($id);

Webhooks

getAddress 允许您指定在达到第一个限制时使用的 Webhooks 的 URL。

添加新的 URL 作为 Webhooks

$response = $client->addWebhook('yoursite.com/webhooks/first-limit-reached');

这将返回一个包含 getMessage() 方法和 getHooks() 方法的 WebhookResponse 对象，其中 getHooks() 方法返回一个包含 Webhook 对象的数组。

每个 Webhook 对象都包含一个 getWebhookId() 方法和 getWebhookUrl() 方法。

删除现有的钩子

要删除现有的 webhook，您需要提供 ID。

$response = $client->deleteWebhook($id);

列出所有 webhooks

您可以使用此方法列出所有 webhooks。它将返回一个如上所示的 WebhookResponse 对象。

$response = $client->getWebhooks();

或者，您可以使用方法的单数版本通过其 ID 获取单个 webhook。

$response = $client->getWebhook($id);

处理错误

如果 getAddress.io 返回错误，则将抛出针对返回的错误特定的异常。

对于任何其他 4xx 或 5xx 错误，将抛出 Philcross\GetAddress\Exceptions\UnknownException 异常。

测试

此软件包附带一组 php 单元测试。要运行它们

./vendor/bin/phpunit