abnlookup

hyraiq/abnlookup

Ein PHP-SDK zur Validierung australischer Geschäftsnummern (ABNs) und deren Verifizierung mit der Australian Business Register Web Services API. Der Unterschied zwischen Validierung und Verifizierung lässt sich wie folgt umreißen:

• Bei der Validierung wird die offizielle Prüfsummenberechnung verwendet, um zu überprüfen, ob eine bestimmte Nummer eine gültige ABN ist. Dabei wird die ABR nicht kontaktiert, um sicherzustellen, dass die angegebene ABN einem Unternehmen zugeordnet wird
• Zur Überprüfung kontaktieren Sie die ABR über deren API, um bei der ABN registrierte Informationen abzurufen. Hier erfahren Sie, ob die ABN tatsächlich einem Unternehmen gehört.

Um die API nutzen zu können (nur zur Verifizierung erforderlich), müssen Sie ein Konto registrieren, um eine GUID zu erhalten, die als API-Schlüssel verwendet wird. Sobald Sie sich registriert haben, können Sie mithilfe der offiziellen Demo mit der API spielen (beachten Sie, dass dieses SDK die JSON-Dienste anstelle von XML verwendet).

Typensicherheit

Das SDK nutzt den Symfony Serializer und den Symfony Validator, um von der ABR-API zurückgegebene Daten zu deserialisieren und zu validieren, um gültige AbnResponse- und NamesResponse-Modelle bereitzustellen. Das heißt, wenn Sie eine Antwort vom SDK erhalten, ist diese garantiert gültig.

Ungültige Antworten aus dem ABR fallen in drei Kategorien, die mit Ausnahmen behandelt werden:

• AbrConnectionException : Es konnte keine Verbindung zum ABR hergestellt werden, oder der ABR hat eine unerwartete Antwort zurückgegeben
• InvalidAbnException : Die ABN ist ungültig (d. h. die Validierung ist fehlgeschlagen)
• AbnNotFoundException : Die ABN ist gültig, sie ist jedoch keinem Unternehmen zugeordnet (d. h. die Überprüfung ist fehlgeschlagen).

Verwendung

Installation

$ composer require hyraiq/abnlookup

Konfiguration mit Symfony

In services.yaml müssen Sie Ihre ABR-GUID an den AbnClient übergeben und den AbnClient bei der AbnClientInterface registrieren:

 HyraAbnLookupAbnClientInterface : ' @HyraAbnLookupAbnClient '
HyraAbnLookupAbnClient :
    arguments :
        $abnLookupGuid : " %env(ABN_LOOKUP_GUID)% "

Anschließend können Sie das AbnClientInterface direkt in Ihre Controller/Dienste einbinden.

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

Konfiguration außerhalb von Symfony

Wenn Sie Symfony nicht verwenden, müssen Sie den ABN-Client selbst instanziieren, der in Ihrem Service-Container registriert oder einfach direkt verwendet werden kann. Wir haben einige Helfer in der Dependencies -Klasse bereitgestellt, um den Symfony Serializer und Validator mit minimalen Optionen zu erstellen.

 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 );

Suche nach einer ABN

Sobald Sie Ihren AbnClient konfiguriert haben, können Sie nach einer einzelnen ABN suchen. Beachten Sie, dass dadurch die ABN vor dem Aufruf der API validiert wird, um unnötige API-Anfragen zu verhindern.

 $ 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

Suche nach Namen

Sie können die ABR auch nach Namen durchsuchen, um eine Liste der registrierten Unternehmen zu erhalten, die dem Suchbegriff entsprechen:

 $ 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 );
}

Testen

In automatisierten Tests können Sie den AbnClient durch den StubAbnClient ersetzen, um Antworten vom ABR zu simulieren. Es gibt auch den AbnFaker , den Sie bei Tests verwenden können, um sowohl gültige als auch ungültige ABNs zu erhalten.

 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 

Mitwirken

Alle Beiträge sind willkommen! Um Tests und CI-Prozesse lokal ausführen zu können, muss Docker installiert sein. Diese werden auch für Ihre Pull-Anfrage ausgeführt, wobei alle Fehler als GitHub-Anmerkungen in der Dateiansicht hinzugefügt werden.

 # 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)

Damit Ihre PR akzeptiert wird, muss sie durch Tests abgedeckt und akzeptiert werden von:

• PHP-CS-Fixer
• Psalm
• phpstan