abnlookup

hyraiq/abnlookup

SDK PHP untuk memvalidasi Nomor Bisnis Australia (ABN) dan memverifikasinya dengan API Layanan Web Daftar Bisnis Australia. Perbedaan antara validasi dan verifikasi dapat diuraikan sebagai berikut:

• Validasi menggunakan perhitungan checksum resmi untuk memeriksa apakah nomor yang diberikan adalah ABN yang valid. Ini tidak menghubungi ABR untuk memastikan bahwa ABN yang diberikan ditugaskan ke suatu bisnis
• Verifikasi menghubungi ABR melalui API mereka untuk mengambil informasi yang didaftarkan pada ABN. Ini akan memberi tahu Anda apakah ABN benar-benar milik suatu bisnis.

Untuk menggunakan API (hanya diperlukan untuk verifikasi), Anda harus mendaftarkan akun untuk menerima GUID yang digunakan sebagai kunci API. Setelah mendaftar, Anda dapat bermain dengan API menggunakan demo resmi (perhatikan bahwa SDK ini menggunakan layanan JSON, bukan XML).

Ketik keamanan

SDK ini menggunakan Symfony Serializer dan Symfony Validator untuk membatalkan serialisasi dan memvalidasi data yang dikembalikan dari ABR API guna menyediakan model AbnResponse dan NamesResponse yang valid. Artinya, jika Anda menerima respons dari SDK, maka dijamin valid.

Respons tidak valid dari ABR terbagi dalam tiga kategori, yang ditangani dengan pengecualian:

• AbrConnectionException : Tidak dapat terhubung ke ABR, atau ABR memberikan respons yang tidak diharapkan
• InvalidAbnException : ABN tidak valid (yaitu validasi gagal)
• AbnNotFoundException : ABN valid, namun tidak ditugaskan ke bisnis (mis. verifikasi gagal)

Penggunaan

Instalasi

$ composer require hyraiq/abnlookup

Konfigurasi dengan Symfony

Di services.yaml , Anda harus meneruskan GUID ABR Anda ke AbnClient dan mendaftarkan AbnClient dengan AbnClientInterface :

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

Anda kemudian dapat memasukkan AbnClientInterface langsung ke pengontrol/layanan Anda.

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

Konfigurasi di luar Symfony

Jika Anda tidak menggunakan Symfony, Anda harus membuat instance sendiri klien ABN, yang dapat didaftarkan di wadah layanan Anda atau langsung digunakan. Kami telah menyediakan beberapa pembantu di kelas Dependencies untuk membuat Symfony Serializer dan Validator dengan opsi minimal.

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

Mencari ABN

Setelah Anda mengonfigurasi AbnClient Anda dapat mencari ABN individual. Catatan, ini akan memvalidasi ABN sebelum memanggil API untuk mencegah permintaan API yang tidak perlu.

 $ 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

Mencari berdasarkan nama

Anda juga dapat mencari ABR berdasarkan nama, untuk menerima daftar bisnis terdaftar yang cocok dengan istilah pencarian:

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

Pengujian

Dalam pengujian otomatis, Anda dapat mengganti AbnClient dengan StubAbnClient untuk meniru respons dari ABR. Ada juga AbnFaker yang dapat Anda gunakan selama pengujian untuk mendapatkan ABN yang valid dan tidak valid.

 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 

Berkontribusi

Semua kontribusi dipersilakan! Anda perlu memasang buruh pelabuhan untuk menjalankan pengujian dan proses CI secara lokal. Ini juga akan dijalankan terhadap permintaan penarikan Anda dengan kegagalan apa pun yang ditambahkan sebagai anotasi GitHub di tampilan File.

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

Agar PR Anda dapat diterima, PR Anda harus melalui tes dan diterima oleh:

• pemecah masalah php-cs
• mazmur
• phpstan