gocardless pro php
v6.0.0
Ein PHP-Client für die Interaktion mit der GoCardless Pro-API.
Die empfohlene Methode zur Installation gocardless-pro ist die Verwendung von Composer.
# Install Composer
curl -sS https://getcomposer.org/installer | php Führen Sie als Nächstes den Composer-Befehl aus, um die neueste stabile Version von gocardless-pro zu installieren.
php composer.phar require gocardless/gocardless-proNach der Installation benötigen Sie den Autoloader von Composer:
require ' vendor/autoload.php ' ; Erstellen Sie eine GoCardlessProClient Instanz und geben Sie Ihr Zugriffstoken und die Umgebung an, die Sie verwenden möchten. Wir empfehlen dringend, Ihr Zugriffstoken als Umgebungsvariable zu speichern und nicht direkt in Ihrem Code. Sie können die Umgebungsvariablen ganz einfach aus einer .env Datei laden, indem Sie etwas wie phpdotenv verwenden, aber halten Sie es außerhalb der Versionskontrolle!
$ access_token = getenv ( ' GC_ACCESS_TOKEN ' );
$ client = new GoCardlessPro Client ([
' access_token ' => $ access_token ,
' environment ' => GoCardlessPro Environment :: SANDBOX
]); Sie können ein access_token über die Registerkarte „Entwickler“ in Ihrem GoCardless-Dashboard erstellen.
Die Umgebung kann entweder GoCardlessProEnvironment::SANDBOX oder GoCardlessProEnvironment::LIVE sein, je nachdem, ob Sie die Sandbox oder die Live-API verwenden möchten.
Die vollständige Dokumentation finden Sie in unseren API-Dokumenten.
Mit der list können Sie eine Anfrage stellen, um eine Liste der Ressourcen zu erhalten.
$ client -> customers ()-> list ();Hinweis: In dieser README-Datei werden durchgehend Kunden verwendet, aber jede der Ressourcen in der API ist in dieser Bibliothek verfügbar.
Wenn Sie Optionen übergeben müssen, ist das letzte (oder einzige, wenn keine URL-Parameter vorhanden sind) Argument für list() ein Array von URL-Parametern:
$ customers = $ client -> customers ()-> list ([ ' params ' => [ ' limit ' => 400 ]]); Ein Aufruf von list() gibt eine Instanz von ListResponse zurück. Sie können das Attribut records verwenden, um die Ergebnisse zu durchlaufen.
echo count ( $ customers -> records );
foreach ( $ customers -> records as $ resource ) {
echo $ resource -> given_name ;
}Falls ein URL-Parameter benötigt wird, enthält die Methodensignatur die erforderlichen Argumente:
$ customer = $ client -> customers ()-> get ( $ customer_id );
echo $ customer -> given_name ;Wie bei der Liste kann das letzte Argument ein Optionsarray mit beliebigen angegebenen URL-Parametern sein:
$ client -> customers ()-> get ( $ customer_id , [ ' params ' => [ ' some_flag ' => true ]]); Sowohl einzelne Ressourcen- als auch ListResponse-Instanzen verfügen über ein api_response Attribut, mit dem Sie auf die folgenden Eigenschaften der Anfrage zugreifen können:
statusheadersbody $ api_response = $ client -> customers ()-> get ( $ customer_id )-> api_response ;
echo $ api_response -> status_code ;Für POST- und PUT-Anfragen müssen Sie einen Textkörper für Ihre Anfrage bereitstellen, indem Sie ihn als erstes Argument übergeben.
$ client -> customers ()-> create ([
' params ' => [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
]);Wenn Parameter erforderlich sind, stehen diese wie bei GET-Anfragen an erster Stelle:
$ client -> customers ()-> update ( $ customer_id , [
' params ' => [ ' family_name ' => ' Smith ' ]
]);Die GoCardless-API enthält Idempotenzschlüssel. Die Bibliothek fügt diese automatisch in Ihre Anfrage ein, wenn Sie eine Ressource erstellen, und verhindert so, dass sie dupliziert wird, wenn mit der API ein Fehler auftritt (z. B. Netzwerkprobleme oder ein Timeout).
Sie können auch Ihren eigenen Idempotenzschlüssel angeben – Sie könnten beispielsweise IDs von Datensätzen in Ihrer Datenbank verwenden und sich so nicht nur vor Netzwerk- oder API-Problemen, sondern auch vor Fehlern auf Ihrer Seite schützen, die zu einer Doppelerstellung führen könnten:
$ client -> customers ()-> create ([
' params ' => [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
' headers ' => [ ' Idempotency-Key ' => ' ABC123 ' ]
]);Wenn die Bibliothek auf einen Idempotenzschlüsselkonflikt stößt (d. h. Sie versuchen, eine Ressource mit einem bereits verwendeten Idempotenzschlüssel zu erstellen), wird die bereits vorhandene Ressource automatisch geladen und zurückgegeben.
Wenn die API einen Fehler zurückgibt, gibt die Bibliothek eine entsprechende Unterklasse von ApiException zurück, eine der folgenden:
InvalidApiUsageExceptionInvalidStateExceptionValidationFailedExceptionDiese Fehlertypen werden in der API-Dokumentation behandelt.
Wenn es sich bei dem Fehler um einen HTTP-Transportschichtfehler handelt (z. B. Zeitüberschreitungen oder Probleme innerhalb der Infrastruktur von GoCardless), werden Anfragen von der Bibliothek automatisch bis zu dreimal wiederholt, mit einer Verzögerung von 500 ms zwischen den Versuchen, bevor eine ApiConnectionException ausgelöst wird.
Wenn die Bibliothek die Antwort von GoCardless nicht analysieren kann, wird eine MalformedResponseException ausgelöst.
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.
}Auf Eigenschaften der Ausnahme kann mit den folgenden Methoden zugegriffen werden:
$e->getType();$e->getCode();$e->getErrors();$e->getDocumentationUrl();$e->getMessage();$e->getRequestId();$e->getApiResponse();GoCardless unterstützt Webhooks, sodass Sie Echtzeitbenachrichtigungen erhalten, wenn in Ihrem Konto etwas passiert, sodass Sie als Reaktion darauf automatische Maßnahmen ergreifen können, zum Beispiel:
Mit dem Client können Sie überprüfen, ob ein Webhook, den Sie erhalten, tatsächlich von GoCardless stammt, und ihn in GoCardlessProResourcesEvent -Objekte analysieren, mit denen Sie einfach arbeiten können:
// 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 ' );
}Weitere Informationen zum Arbeiten mit Webhooks finden Sie in unserem Leitfaden „Erste Schritte“.
Diese Client-Bibliothek unterstützt nur PHP >= 8.1. Frühere Versionen von PHP gelten nun als veraltet und können Sicherheitslücken aufweisen.
Dieser Client wird automatisch von Crank generiert, einer Toolchain, die wir hoffentlich bald als Open Source veröffentlichen werden. Probleme sollten vorerst in diesem Repository gemeldet werden.
Bitte ändern Sie den Quellcode nicht selbst, Ihre Änderungen werden überschrieben!
