abnlookup

hyraiq/abnlookup

Un SDK PHP pour valider les numéros d'entreprise australiens (ABN) et les vérifier avec l'API des services Web de l'Australian Business Register. La différence entre validation et vérification peut être décrite comme suit :

• La validation utilise le calcul de la somme de contrôle officielle pour vérifier qu'un numéro donné est un ABN valide. Cela ne contacte pas l'ABR pour garantir que l'ABN donné est attribué à une entreprise.
• La vérification contacte l'ABR via son API pour récupérer les informations enregistrées sur l'ABN. Il vous dira si l’ABN appartient réellement à une entreprise.

Pour utiliser l'API (uniquement nécessaire à la vérification), vous devrez créer un compte pour recevoir un GUID qui est utilisé comme clé API. Une fois inscrit, vous pouvez jouer avec l'API en utilisant la démo officielle (notez que ce SDK utilise les services JSON au lieu de XML).

Type de sécurité

Le SDK utilise Symfony Serializer et Symfony Validator pour désérialiser et valider les données renvoyées par l'API ABR afin de fournir des modèles AbnResponse et NamesResponse valides. Cela signifie que si vous recevez une réponse du SDK, sa validité est garantie.

Les réponses invalides de l'ABR se répartissent en trois catégories, qui sont traitées avec des exceptions :

• AbrConnectionException : impossible de se connecter à l'ABR ou l'ABR a renvoyé une réponse inattendue
• InvalidAbnException : l'ABN n'est pas valide (c'est-à-dire que la validation a échoué)
• AbnNotFoundException : L'ABN est valide, mais il n'est pas attribué à une entreprise (c'est-à-dire que la vérification a échoué)

Usage

Installation

$ composer require hyraiq/abnlookup

Configuration avec Symfony

Dans services.yaml , vous devez transmettre votre GUID ABR à AbnClient et enregistrer AbnClient avec AbnClientInterface :

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

Vous pouvez ensuite injecter AbnClientInterface directement dans vos contrôleurs/services.

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

Configuration en dehors de Symfony

Si vous n'utilisez pas Symfony, vous devrez instancier vous-même le client ABN, qui peut être enregistré dans votre conteneur de services ou simplement utilisé directement. Nous avons fourni quelques assistants dans la classe Dependencies afin de créer le Serializer et le Validator Symfony avec un minimum d'options.

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

Rechercher un ABN

Une fois que vous avez configuré votre AbnClient vous pouvez rechercher un ABN individuel. Notez que cela validera l'ABN avant d'appeler l'API afin d'éviter les requêtes API inutiles.

 $ 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

Recherche par nom

Vous pouvez également effectuer une recherche dans l'ABR par nom pour recevoir une liste des entreprises enregistrées qui correspondent au terme de recherche :

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

Essai

Dans les tests automatisés, vous pouvez remplacer AbnClient par StubAbnClient afin de simuler les réponses de l'ABR. Il existe également AbnFaker que vous pouvez utiliser lors des tests pour obtenir des ABN valides et invalides.

 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 

Contribuer

Toutes les contributions sont les bienvenues ! Vous aurez besoin de Docker installé pour exécuter des tests et des processus CI localement. Celles-ci seront également exécutées sur votre demande d'extraction avec tous les échecs ajoutés sous forme d'annotations GitHub dans la vue Fichiers.

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

Pour que votre PR soit accepté, il devra être couvert par des tests et être accepté par :

• php-cs-fixateur
• psaume
• phpstan