gocardless pro php

مكتبة عملاء GoCardless Pro PHP

عميل PHP للتفاعل مع GoCardless Pro API.

• دليل "البدء" مع نماذج نسخ ولصق أكواد PHP
• مرجع واجهة برمجة التطبيقات
• حزمة الملحن
• سجل التغيير

تثبيت

الطريقة الموصى بها لتثبيت gocardless-pro هي استخدام Composer.

 # Install Composer
curl -sS https://getcomposer.org/installer | php

بعد ذلك، قم بتشغيل أمر Composer لتثبيت أحدث إصدار ثابت من gocardless-pro .

php composer.phar require gocardless/gocardless-pro

بعد التثبيت، تحتاج إلى طلب أداة التحميل التلقائي للملحن:

 require ' vendor/autoload.php ' ;

تهيئة العميل

قم بإنشاء مثيل GoCardlessProClient ، مع توفير رمز الوصول الخاص بك والبيئة التي تريد استخدامها. ننصح بشدة بتخزين رمز الوصول الخاص بك كمتغير بيئة، بدلاً من تخزينه مباشرة في التعليمات البرمجية الخاصة بك. يمكنك بسهولة تحميل متغيرات البيئة من ملف .env باستخدام شيء مثل phpdotenv، مع إبقائه خارج التحكم في الإصدار!

 $ access_token = getenv ( ' GC_ACCESS_TOKEN ' );
$ client = new  GoCardlessPro  Client ([
  ' access_token ' => $ access_token ,
  ' environment '  =>  GoCardlessPro  Environment :: SANDBOX
]);

يمكنك إنشاء رمز access_token من علامة التبويب "المطورين" في لوحة تحكم GoCardless.

يمكن أن تكون البيئة إما GoCardlessProEnvironment::SANDBOX أو GoCardlessProEnvironment::LIVE ، اعتمادًا على ما إذا كنت تريد استخدام وضع الحماية أو واجهة برمجة التطبيقات المباشرة.

للحصول على الوثائق الكاملة، راجع مستندات API الخاصة بنا.

الحصول على الطلبات

يمكنك تقديم طلب للحصول على قائمة بالموارد باستخدام طريقة list .

 $ client -> customers ()-> list ();

ملاحظة: سيستخدم ملف README هذا العملاء طوال الوقت ولكن كل الموارد الموجودة في واجهة برمجة التطبيقات متاحة في هذه المكتبة.

إذا كنت بحاجة إلى تمرير أي خيارات، فإن الوسيطة الأخيرة (أو الوحيدة، في حالة عدم وجود معلمات URL) list() هي مصفوفة من معلمات URL:

 $ customers = $ client -> customers ()-> list ([ ' params ' => [ ' limit ' => 400 ]]);

يؤدي استدعاء list() إلى إرجاع مثيل ListResponse . يمكنك استخدام سمة records الخاصة به لتكرار النتائج.

 echo count ( $ customers -> records );
foreach ( $ customers -> records as $ resource ) {
  echo $ resource -> given_name ;
}

في حالة الحاجة إلى معلمة URL، سيحتوي توقيع الطريقة على الوسائط المطلوبة:

 $ customer = $ client -> customers ()-> get ( $ customer_id );
echo $ customer -> given_name ;

كما هو الحال مع القائمة، يمكن أن تكون الوسيطة الأخيرة عبارة عن مصفوفة خيارات، مع توفير أي معلمات URL:

 $ client -> customers ()-> get ( $ customer_id , [ ' params ' => [ ' some_flag ' => true ]]);

يحتوي كل من المورد الفردي ومثيلات ListResponse على سمة api_response ، والتي تتيح لك الوصول إلى الخصائص التالية للطلب:

• status
• headers
• body

 $ api_response = $ client -> customers ()-> get ( $ customer_id )-> api_response ;
echo $ api_response -> status_code ;

طلبات النشر/الوضع

بالنسبة لطلبات POST وPUT، يتعين عليك توفير نص لطلبك عن طريق تمريره كوسيطة أولى.

 $ client -> customers ()-> create ([
  ' params ' => [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
]);

كما هو الحال مع طلبات GET، إذا كانت هناك أي معلمات مطلوبة، فهي تأتي أولاً:

 $ client -> customers ()-> update ( $ customer_id , [
  ' params ' => [ ' family_name ' => ' Smith ' ]
]);

تتضمن واجهة برمجة تطبيقات GoCardless مفاتيح العجز. ستقوم المكتبة بإدخال هذه العناصر تلقائيًا في طلبك عندما تقوم بإنشاء مورد، مما يمنع تكراره في حالة حدوث خطأ ما في واجهة برمجة التطبيقات (على سبيل المثال، مشكلات في الشبكة أو انتهاء المهلة).

يمكنك أيضًا تحديد مفتاح الصلاحيات الخاص بك - يمكنك، على سبيل المثال، استخدام معرفات السجلات في قاعدة بياناتك، مما يحمي نفسك ليس فقط من مشكلات الشبكة أو واجهة برمجة التطبيقات، ولكن أيضًا من الأخطاء من جانبك والتي قد تؤدي إلى الإنشاء المزدوج:

 $ client -> customers ()-> create ([
  ' params ' =>  [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
  ' headers ' => [ ' Idempotency-Key ' => ' ABC123 ' ]
]);

إذا واجهت المكتبة تعارضًا في مفتاح عدم القدرة (أي أنك تحاول إنشاء مورد باستخدام مفتاح عدم القدرة الذي استخدمته بالفعل)، فسيتم تحميل المورد الموجود بالفعل وإرجاعه تلقائيًا.

التعامل مع الفشل

عندما تُرجع واجهة برمجة التطبيقات (API) خطأً، ستُرجع المكتبة فئة فرعية مقابلة من ApiException ، وهي واحدة من:

• InvalidApiUsageException
• InvalidStateException
• ValidationFailedException

يتم تناول هذه الأنواع من الأخطاء في وثائق API.

إذا كان الخطأ عبارة عن خطأ في طبقة نقل HTTP (على سبيل المثال، المهلات أو المشكلات داخل البنية التحتية لـ GoCardless)، فستتم إعادة محاولة الطلبات تلقائيًا بواسطة المكتبة حتى 3 مرات، مع تأخير قدره 500 مللي ثانية بين المحاولات، قبل ظهور ApiConnectionException .

إذا لم تتمكن المكتبة من تحليل الاستجابة من GoCardless، فسوف تقوم بطرح MalformedResponseException .

 try {
  $ client -> customer ()-> create ([
    ' params ' => [ ' invalid_name ' => ' Pete ' ]
  ]);
} catch (  GoCardlessPro  Core  Exception  ApiException $ e ) {
  // Api request failed / record couldn't be created.
} catch (  GoCardlessPro  Core  Exception  MalformedResponseException $ e ) {
  // Unexpected non-JSON response.
} catch (  GoCardlessPro  Core  Exception  ApiConnectionException $ e ) {
  // Network error.
}

يمكن الوصول إلى خصائص الاستثناء بالطرق التالية:

• $e->getType();
• $e->getCode();
• $e->getErrors();
• $e->getDocumentationUrl();
• $e->getMessage();
• $e->getRequestId();
• $e->getApiResponse();

التعامل مع خطافات الويب

يدعم GoCardless خطافات الويب، مما يسمح لك بتلقي إشعارات في الوقت الفعلي عند حدوث أشياء في حسابك، حتى تتمكن من اتخاذ إجراءات تلقائية ردًا على ذلك، على سبيل المثال:

• عندما يقوم العميل بإلغاء تفويضه مع البنك، قم بتعليق عضويته في النادي
• عند فشل الدفع بسبب نقص الأموال، قم بوضع علامة على فاتورتهم على أنها غير مدفوعة
• عندما يؤدي اشتراك العميل إلى إنشاء دفعة جديدة، قم بتسجيلها في قائمة "الدفعات السابقة" الخاصة به

يسمح لك العميل بالتحقق من أن خطاف الويب الذي تتلقاه هو بالفعل من GoCardless، وتحليله إلى كائنات GoCardlessProResourcesEvent التي يسهل التعامل معها:

 <?php
// When you create a webhook endpoint, you can specify a secret. When GoCardless sends
// you a webhook, it will sign the body using that secret. Since only you and GoCardless
// know the secret, you can check the signature and ensure that the webhook is truly
// from GoCardless.
//
// We recommend storing your webhook endpoint secret in an environment variable
// for security, but you could include it as a string directly in your code
$ webhook_endpoint_secret = getenv ( ' GOCARDLESS_WEBHOOK_ENDPOINT_SECRET ' );

$ request_body = file_get_contents ( ' php://input ' );

$ headers = getallheaders ();
$ signature_header = $ headers [ ' Webhook-Signature ' ];

try {
     $ events = GoCardlessPro  Webhook :: parse ( $ request_body , $ signature_header , $ webhook_endpoint_secret );

     foreach ( $ events as $ event ) {
         // You can access each event in the webhook.
         echo $ event -> id ;
     }

     header ( ' HTTP/1.1 200 OK ' );
} catch ( GoCardlessPro  Core  Exception  InvalidSignatureException ) {
     // The webhook doesn't appear to be genuinely from GoCardless, as the signature
     // included in the `Webhook-Signature` header doesn't match the one computed with
     // your webhook endpoint secret and the body.
     header ( ' HTTP/1.1 498 Invalid Token ' );
}

لمزيد من التفاصيل حول العمل باستخدام خطافات الويب، راجع دليل "البدء".

دعم PHP >= 8.1

تدعم مكتبة العميل هذه PHP فقط >= 8.1 تعتبر الإصدارات السابقة من PHP الآن منتهية الصلاحية وقد تتعرض لثغرات أمنية.

المساهمة

تم إنشاء هذا العميل تلقائيًا من Crank، وهي سلسلة أدوات نأمل أن نفتحها قريبًا. ينبغي الآن الإبلاغ عن المشكلات في هذا المستودع.

من فضلك لا تقم بتعديل كود المصدر بنفسك، سيتم تجاوز التغييرات التي قمت بها!