README

USPS Address

一个用于在PHP中规范化并比较美国邮政服务（USPS）地址的库。

比较地址比较棘手。同一物理地址有许许多多的表示方式。例如，“123 First St”和“123 1st St”是同一个地址。然而，对于计算机来说，这两者却是不同的。

这个库试图规范化地址，以便不同形式的同一物理地址可以进行比较。例如，“17 First Street”和“17 1st st”将被视为相等。

请注意以下几点

1. 规范化地址不应显示给用户。它的格式是为了帮助计算机比较地址是否相等，并且它并不“漂亮”。
2. 规范化地址不应覆盖原始地址。地址的规范化版本可能会随着该库算法的改进而改变，但一旦覆盖了原始地址，它就永远消失了。
3. 规范化地址不应被视为真实的。此库将规范化并比较您提供的任何地址，无论其是否实际存在。如果您不介意使用网络服务，有一些API可以为您提供地址的规范化、验证和认证。

安装

此库需要 PHP 7.4+。

它是跨平台的，我们努力使其在Windows、Linux和OSX上运行得同样好。

应通过 Composer 安装。要这样做，请将以下行添加到您的 composer.json 文件的 require 部分，并运行 composer update

{
   "require": {
       "jstewmc/usps-address": "^0.2"
   }
}

用法

此库定义了一个USPS地址接口 AddressInterface，它支持两行街道地址、城市、州和邮编等

123 Foo St
Apt 456
Baton Rouge, LA 12345

所有组件都是可选的，以支持部分数据。

此库提供了一个接口的实现，Address，以及一个 trait，Addressable，您可以在自己的类中使用它来实现接口。

使用您的实现

当使用您的 AddressInterface 实现（让我们称它为 MyAddress）时，您可以使用此库的 Compare 服务来比较地址

use Jstewmc\UspsAddress\Compare;

// instantiate the compare service (ideally, from your service manager)
$compare = new Compare();

// instantiate your address
$address1 = (new MyAddress())
  ->setStreet1('Thirty-one Spooner Street')
  ->setCity('Quahog')
  ->setState('Rhode Island')
  ->setZip('12345');

// instantiate a same-but-different address
$address2 = (new MyAddress())
  ->setStreet1('31 Spooner St')
  ->setCity('Quahog')
  ->setState('RI')
  ->setZip('12345');

$compare($address1, $address2);  // returns true

如果您想访问更底层的规范化地址，可以使用 Normalize 服务来实现。请注意，此服务将接受任何 AddressInterface 实现，并将返回我们自己的实现，Address

use Jstewmc\UspsAddress\Normalize;

// instantiate the normalize service (ideally, from your service manager)
$normalize = new Normalize();

// create an instance of your implementation
$address = (new MyAddress())
  ->setStreet1('Thirty-one Spooner Street')
  ->setCity('Quahog')
  ->setState('Rhode Island')
  ->setZip('12345');

$norm = $normalize($address);

$norm->getStreet1();  // returns "31 spooner st"
$norm->getCity();     // returns "quahog"
$norm->getState();    // returns "rhode island"
$norm->getZip();      // returns "12345"

$norm instanceof \Jstewmc\UspsAddress\Address;  // returns true

如果您同时使用这两个服务，您可以将您的 Normalize 服务实例注入到您的 Compare 服务实例中。否则，Compare 服务将实例化自己的 Normalize 服务副本

use Jstewmc\UspsAddress\{Compare, Normalize};

$normalize = new Normalize();

$compare = new Compare($normalize);

使用我们的实现

我们的 AddressInterface 实现，Address，提供了两个方便的方法 - equals() 和 normalize() - 如果您不处理大量地址，这些方法是管理服务的合理快捷方式。如果数据集足够大，方法的实例化和丢弃单次使用对象可能会影响内存和性能。

use Jstewmc\UspsAddress\Address;

// create an address using our implementation
$address1 = (new Address())
  ->setStreet1('Thirty-one Spooner Street')
  ->setCity('Quahog')
  ->setState('Rhode Island')
  ->setZip('12345');

// create a same-but-different address
$address2 = (new Address())
  ->setStreet1('31 Spooner St')
  ->setCity('Quahog')
  ->setState('RI')
  ->setZip('12345');

$address1->equals($address2);  // returns true

$norm = $address1->normalize();

$norm->getStreet1();  // returns "31 spooner st"
$norm->getCity();     // returns "quahog"
$norm->getState();    // returns "rhode island"
$norm->getZip();      // returns "12345"

我们的实现还允许您仅使用构造函数来实例化地址

use Jstewmc\UspsAddress\Address;

// Like an address, the arguments, in order, are: street 1, street 2, city, state, and zip
new Address('31 Spooner St', null, 'Quahog', 'RI', '12345');

从 0.1 迁移

此库从 0.1 到 0.2 发生了重大变化

1. 我们将之前 public static 属性移动到私有常量中，以更好地封装它们。
2. 我们将之前 public static 方法移动到服务中，以实现服务友好、易于测试的解决方案。
3. 我们针对接口进行编程，而不是实现，并提供了特质，以便使库更容易与您的代码一起使用。
4. 我们从类名中移除了 Usps 前缀，因为它并没有添加从库名称中已经显而易见的信息。

因此，从 0.1 迁移到 0.2 涉及到许多破坏性变更。尽管这个过程很痛苦，但我们相信这将使库在未来的使用和维护中更加容易。

贡献

欢迎贡献！

# Clone the repository (assuming you have Git installed).
~/path/to $ git clone git@github.com:jstewmc/usps-address.git

# Install dependencies (assuming you are using Composer locally).
~/path/to/usps-address $ php composer.phar install

# Run the tests.
~/path/to/usps-address $ ./vendor/bin/phpunit

# Create and checkout a new branch.
~/path/to/usps-address $ git branch -c YOUR_BRANCH_NAME

# Make your changes...

# Run the tests again.
~/path/to/usps-address $ ./vendor/bin/phpunit

# Lint your changes.
~/path/to/usps-address $ ./vendor/bin/phpcs .

# Push your changes to Github and create a pull request.
~/path/to/usps-address $ git push origin YOUR_BRANCH_NAME

许可证

此库在MIT 许可证下发布。