abnlookup

hyraiq/abnlookup

PHP SDK เพื่อตรวจสอบหมายเลขธุรกิจของออสเตรเลีย (ABN) และตรวจสอบด้วย Australian Business Register Web Services API ความแตกต่างระหว่างการตรวจสอบและการตรวจสอบสามารถสรุปได้ดังนี้:

• การตรวจสอบความถูกต้องจะใช้การคำนวณผลรวมตรวจสอบอย่างเป็นทางการเพื่อตรวจสอบว่าหมายเลขที่กำหนดเป็น ABN ที่ถูกต้อง สิ่งนี้ ไม่ได้ ติดต่อกับ ABR เพื่อให้แน่ใจว่า ABN ที่กำหนดนั้นได้รับการกำหนดให้กับธุรกิจ
• การยืนยันติดต่อ ABR ผ่านทาง API เพื่อดึงข้อมูลที่ลงทะเบียนกับ ABN มันจะบอกคุณว่า ABN เป็นของธุรกิจจริงหรือไม่

ในการใช้ API (จำเป็นสำหรับการตรวจสอบเท่านั้น) คุณจะต้องลงทะเบียนบัญชีเพื่อรับ GUID ซึ่งใช้เป็นคีย์ API เมื่อคุณลงทะเบียนแล้ว คุณสามารถเล่นกับ API โดยใช้การสาธิตอย่างเป็นทางการได้ (โปรดทราบว่า SDK นี้ใช้บริการ JSON แทน XML)

ประเภทความปลอดภัย

SDK ใช้ Symfony Serializer และ Symfony Validator เพื่อดีซีเรียลไลซ์และตรวจสอบข้อมูลที่ส่งคืนจาก ABR API เพื่อจัดเตรียมโมเดล AbnResponse และ NamesResponse ที่ถูกต้อง ซึ่งหมายความว่าหากคุณได้รับการตอบกลับจาก SDK ก็รับประกันได้ว่าจะมีความถูกต้อง

คำตอบที่ไม่ถูกต้องจาก ABR แบ่งออกเป็นสามประเภท ซึ่งได้รับการจัดการโดยมีข้อยกเว้น:

• AbrConnectionException : ไม่สามารถเชื่อมต่อกับ ABR หรือ ABR ส่งคืนการตอบสนองที่ไม่คาดคิด
• InvalidAbnException : ABN ไม่ถูกต้อง (เช่น การตรวจสอบล้มเหลว)
• AbnNotFoundException : ABN ถูกต้อง แต่ไม่ได้ถูกกำหนดให้กับธุรกิจ (เช่น การตรวจสอบล้มเหลว)

การใช้งาน

การติดตั้ง

$ composer require hyraiq/abnlookup

การกำหนดค่าด้วย Symfony

ใน services.yaml คุณต้องส่ง ABR GUID ให้กับ 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 Serializer และ Validator โดยมีตัวเลือกน้อยที่สุด

 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