README

一个PHP SDK，用于验证新西兰商业编号（NZBNs）并使用新西兰公司办公室公共数据API进行验证。

验证和验证之间的区别可以概括如下

验证使用正则表达式检查给定的编号是否为有效的NZBN。这不会联系API以确保给定的ABN已分配给企业
验证通过公司办公室的API联系以检索针对ABN注册的信息。它将告诉您ABN实际上是否属于企业。

为了使用API（仅用于验证），您需要注册一个账户以接收API密钥。

类型安全

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

API的无效响应分为三类，使用异常处理

ConnectionException.php：无法连接到API，或API返回了意外的响应
NumberInvalidException.php：ABN无效（即验证失败）
NumberNotFoundException.php：ABN有效，但它未分配给企业（即验证失败）

使用方法

安装

$ composer require hyraiq/nz-companies-office-lookup

使用Symfony进行配置

在 services.yaml 中，您需要将您的ABR API密钥传递给 ApiClient 并将 ApiClient 注册到 ApiClientInterface

Hyra\NzCompaniesHouseLookup\ApiClientInterface: '@Hyra\NzCompaniesHouseLookup\ApiClient'
Hyra\NzCompaniesHouseLookup\ApiClient:
    arguments:
        $apiKey: "%env(NZ_COMPANIES_OFFICE_API_KEY)%"

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

class VerifyController extends AbtractController
{
    public function __construct(
        private ApiClientInterface $apiClient,
    ) {
    }
    
    // ...  
}

您还需要将自定义地址反序列化器添加到 services.yaml

Hyra\NzCompaniesOfficeLookup\Model\AddressDenormalizer: ~

在Symfony之外进行配置

如果您不使用Symfony，您需要自己实例化API客户端，它可以在服务容器中注册或直接使用。我们在 Dependencies 类中提供了一些辅助器，以使用最少选项创建Symfony Serializer和Validator。

use Hyra\NzCompaniesHouseLookup\Dependencies;
use Hyra\NzCompaniesHouseLookup\ApiClient;

$apiKey = '<insert your API key here>'

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

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

$apiClient = new ApiClient($denormalizer, $validator, $httpClient, $apiKey);

查找商业编号

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

$number = '9429032389470';

try {
    $response = $apiClient->lookupNumber($number);
} catch (ConnectionException $e) {
    die($e->getMessage())
} catch (NumberInvalidException) {
    die('Invalid business number');
} catch (NumberNotFoundException) {
    die('Business number not found');
}

echo $response->companyNumber; // 9429032389470
echo $response->entityName; // BURGER FUEL LIMITED
echo $response->status; // Registered

测试

在自动化测试中，您可以将 ApiClient 替换为 StubApiClient 以模拟API的响应。还有 BusinessNumberFaker，您可以在测试期间使用它来获取有效和无效的NZBN。

use Hyra\NzCompaniesOfficeLookup\Stubs\BusinessNumberFaker;
use Hyra\NzCompaniesOfficeLookup\Stubs\StubApiClient;
use Hyra\NzCompaniesOfficeLookup\Stubs\MockBusinessRegistryResponse;

$stubClient = new StubApiClient();

$stubClient->lookupNumber(BusinessNumberFaker::invalidBusinessNumber()); // NumberInvalidException - Note, the stub still uses the validator

$stubClient->lookupNumber(BusinessNumberFaker::validBusinessNumber()); // LogicException - You need to tell the stub how to respond to specific queries

$businessNumber = BusinessNumberFaker::validBusinessNumber();
$stubClient->addNotFoundBusinessNumbers($businessNumber);
$stubClient->lookupNumber($businessNumber); // NumberNotFoundException

$businessNumber = BusinessNumberFaker::validBusinessNumber();
$mockResponse = MockBusinessRegistryResponse::valid();
$mockResponse->businessNumber = $businessNumber;

$stubClient->addMockResponse($mockResponse);
$response = $stubClient->lookupNumber($businessNumber); // $response === $mockResponse

贡献

所有贡献都受欢迎！您需要docker以本地运行测试和CI流程。这些也将与您的pull request一起运行，任何失败都将添加为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被接受，它需要通过测试并被

hyraiq / nz-companies-office-lookup

维护者

详细信息