abnlookup

hyraiq/abnlookup

PHP SDK للتحقق من صحة أرقام الأعمال الأسترالية (ABNs) والتحقق منها باستخدام واجهة برمجة تطبيقات خدمات ويب سجل الأعمال الأسترالية. ويمكن توضيح الفرق بين التحقق والتحقق على النحو التالي:

• يستخدم التحقق من الصحة حساب المجموع الاختباري الرسمي للتحقق من أن الرقم المحدد هو ABN صالح. ولا يؤدي ذلك إلى الاتصال بـ ABR للتأكد من تعيين رقم ABN المحدد لشركة ما
• للتحقق، اتصل بـ ABR من خلال واجهة برمجة التطبيقات (API) الخاصة بهم لاسترداد المعلومات المسجلة ضد ABN. سيخبرك ما إذا كان ABN ينتمي بالفعل إلى شركة ما.

من أجل استخدام واجهة برمجة التطبيقات (الضرورية فقط للتحقق)، ستحتاج إلى تسجيل حساب لتلقي المعرف الفريد العمومي (GUID) الذي يتم استخدامه كمفتاح واجهة برمجة التطبيقات. بمجرد التسجيل، يمكنك اللعب باستخدام واجهة برمجة التطبيقات (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)

لكي يتم قبول العلاقات العامة الخاصة بك، يجب أن تكون مشمولة بالاختبارات وأن يتم قبولها من قبل:

• PHP-CS-المثبت
• مزمور
• com.phpstan