abnlookup

hyraiq/abnlookup

PHP SDK для проверки австралийских бизнес-номеров (ABN) и их проверки с помощью API веб-служб австралийского бизнес-регистра. Разницу между валидацией и верификацией можно обозначить следующим образом:

• При проверке используется официальный расчет контрольной суммы, чтобы убедиться, что данное число является действительным ABN. При этом ABR не связывается с целью убедиться, что данный ABN присвоен предприятию.
• Для проверки свяжитесь с ABR через их API, чтобы получить информацию, зарегистрированную в ABN. Он скажет вам, действительно ли ABN принадлежит компании.

Чтобы использовать API (необходим только для проверки), вам необходимо зарегистрировать учетную запись, чтобы получить GUID, который используется в качестве ключа API. После регистрации вы сможете поиграть с API, используя официальную демо-версию (обратите внимание, что этот SDK использует сервисы JSON вместо XML).

Тип безопасности

SDK использует сериализатор Symfony и валидатор Symfony для десериализации и проверки данных, возвращаемых из API ABR, чтобы предоставить действительные модели AbnResponse и NamesResponse. Это означает, что если вы получите ответ от SDK, он гарантированно будет действительным.

Недействительные ответы от ABR делятся на три категории, которые обрабатываются с исключениями:

• AbrConnectionException : невозможно подключиться к ABR, или ABR вернул неожиданный ответ.
• InvalidAbnException : ABN недействителен (т. е. проверка не удалась).
• AbnNotFoundException : ABN действителен, однако он не присвоен компании (т. е. проверка не удалась).

Использование

Установка

$ composer require hyraiq/abnlookup

Конфигурация с Symfony

В services.yaml вам необходимо передать GUID ABR в AbnClient и зарегистрировать AbnClient с помощью AbnClientInterface :

 HyraAbnLookupAbnClientInterface : ' @HyraAbnLookupAbnClient '
HyraAbnLookupAbnClient :
    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. Они также будут выполняться по вашему запросу на вытягивание, а любые сбои будут добавлены в виде аннотаций 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-фиксатор
• псалом
• phpstan