README

一个用于验证澳大利亚商业编号（ABN）并使用澳大利亚商业注册网络服务API进行验证的PHP SDK。验证和验证之间的区别如下所述

• 验证使用官方的校验和计算来检查给定的编号是否为有效的ABN。这不会联系ABR以确保给定的ABN分配给了企业
• 验证通过API联系ABR以检索与ABN注册的信息。这将告诉您ABN是否确实属于企业。

为了使用API（仅适用于验证），您需要注册一个账户以接收一个GUID，该GUID用作API密钥。一旦注册，您就可以使用官方演示（注意，此SDK使用JSON服务而不是XML）来使用API。

类型安全

SDK利用Symfony序列化器和Symfony验证器来反序列化和验证从ABR API返回的数据，以提供有效的AbnResponse和NamesResponse模型。这意味着如果您从SDK收到响应，则可以保证它是有效的。

ABR的无效响应分为三类，并用异常处理

• AbrConnectionException：无法连接到ABR或ABR返回了意外的响应
• InvalidAbnException：ABN无效（即验证失败）
• AbnNotFoundException：ABN有效，但未分配给企业（即验证失败）

使用方法

安装

$ composer require hyraiq/abnlookup

使用Symfony进行配置

在services.yaml中，您需要将您的ABR GUID传递给AbnClient并将AbnClient与AbnClientInterface注册

Hyra\AbnLookup\AbnClientInterface: '@Hyra\AbnLookup\AbnClient'
Hyra\AbnLookup\AbnClient:
    arguments:
        $abnLookupGuid: "%env(ABN_LOOKUP_GUID)%"

然后您可以直接将AbnClientInterface注入到您的控制器/服务中。

class VerifyAbnController extends AbtractController
{
    public function __construct(
        private AbnClientInterface $abnClient,
    ) {
    }
    
    // ...  
}

Symfony之外进行配置

如果您不使用Symfony，您需要自己实例化ABN客户端，该客户端可以注册到服务容器中或直接使用。我们在Dependencies类中提供了一些辅助函数，以使用最少的选项创建Symfony序列化器和验证器。

use Hyra\AbnLookup\Dependencies;
use Hyra\AbnLookup\AbnClient;

$abrGuid = '<insert your ABR GUID here>'

// Whichever http client you choose
$httpClient = new HttpClient();

$denormalizer = Dependencies::serializer();
$validator = Dependencies::validator();

$abnClient = new AbnClient($denormalizer, $validator, $httpClient, $abrGuid);

查找ABN

一旦您配置了AbnClient，您就可以查找单个ABN。请注意，这将验证ABN然后再调用API，以防止不必要的API请求。

$abn = '12620650553';

try {
    $abnResponse = $abnClient->lookupAbn($abn);
} catch (AbrConnectionException $e) {
    die($e->getMessage())
} catch (InvalidAbnException) {
    die('Invalid ABN');
} catch (AbnNotFoundException) {
    die('ABN not found');
}

echo $abnResponse->abn; // 12620650553
echo $abnResponse->entityName; // Blenktech PTY LTD
echo $abnResponse->status; // Active

按名称搜索

您还可以通过名称搜索ABR，以接收与搜索词匹配的已注册企业的列表

$namesResponse = $abnClient->lookupName('Hyra iQ');

echo \sprintf('Received %d results', \count($namesResponse->names));
foreach ($namesResponse->names as $name) {
    echo \sprintf('%s: %s', $name->abn, $name->name);
}

测试

在自动化测试中，您可以将AbnClient替换为StubAbnClient以模拟ABR的响应。还有AbnFaker，您可以在测试期间使用它来获取有效的和无效的ABN。

use Hyra\AbnLookup\Stubs\AbnFaker;
use Hyra\AbnLookup\Stubs\StubAbnClient;

$stubClient = new StubAbnClient();

$stubClient->lookupAbn(AbnFaker::invalidAbn()); // InvalidAbnException - Note, the stub still uses the validator

$stubClient->lookupAbn(AbnFaker::validAbn()); // LogicException - You need to tell the stub how to respond to specific queries

$abn = AbnFaker::validAbn();
$stubClient->addNotFoundAbns($abn);
$stubClient->lookupAbn($abn); // AbnNotFoundException

$abn = AbnFaker::validAbn();
$mockResponse = new AbnResponse();
$response->abn = $abn;
$response->abnStatus = 'active';
$response->abnStatusEffectiveFrom = new \DateTimeImmutable('2 years ago');
$response->entityTypeCode = 'PRV';
$response->entityTypeName = 'Australian Private Company';

$stubClient->addMockResponse($mockResponse);
$abnResponse = $stubClient->lookupAbn($abn); // $abnResponse === $mockResponse

贡献

欢迎所有贡献！为了在本地运行测试和持续集成（CI）流程，您需要安装Docker。这些流程还将对您的拉取请求（PR）进行运行，任何失败都会在文件视图中以GitHub注解的形式添加。

# First build the required docker container
$ docker compose build

# Then you can install composer dependencies
$ docker compose run php ./composer.phar install

# Now you can run tests and other tools
$ docker compose run php make (fix|psalm|phpstan|phpunit)

为了您的PR能够被接受，它需要通过测试，并被以下工具接受：

• php-cs-fixer
• psalm
• phpstan