gocardless pro php
v6.0.0
Un client PHP pour interagir avec l'API GoCardless Pro.
La méthode recommandée pour installer gocardless-pro consiste à utiliser Composer.
# Install Composer
curl -sS https://getcomposer.org/installer | php Ensuite, exécutez la commande Composer pour installer la dernière version stable de gocardless-pro .
php composer.phar require gocardless/gocardless-proAprès l'installation, vous devez avoir besoin du chargeur automatique de Composer :
require ' vendor/autoload.php ' ; Créez une instance GoCardlessProClient , en fournissant votre jeton d'accès et l'environnement que vous souhaitez utiliser. Nous vous conseillons fortement de stocker votre jeton d'accès en tant que variable d'environnement, plutôt que directement dans votre code. Vous pouvez facilement charger les variables d'environnement à partir d'un fichier .env en utilisant quelque chose comme phpdotenv, mais gardez-le hors du contrôle de version !
$ access_token = getenv ( ' GC_ACCESS_TOKEN ' );
$ client = new GoCardlessPro Client ([
' access_token ' => $ access_token ,
' environment ' => GoCardlessPro Environment :: SANDBOX
]); Vous pouvez créer un access_token à partir de l'onglet « Développeurs » de votre tableau de bord GoCardless.
L'environnement peut être GoCardlessProEnvironment::SANDBOX ou GoCardlessProEnvironment::LIVE , selon que vous souhaitez utiliser le bac à sable ou l'API en direct.
Pour une documentation complète, consultez nos documents API.
Vous pouvez faire une demande pour obtenir une liste de ressources en utilisant la méthode list .
$ client -> customers ()-> list ();Remarque : Ce README sera utilisé par les clients tout au long, mais chacune des ressources de l'API est disponible dans cette bibliothèque.
Si vous devez transmettre des options, le dernier (ou le seul, en l'absence de paramètres d'URL) argument à list() est un tableau de paramètres d'URL :
$ customers = $ client -> customers ()-> list ([ ' params ' => [ ' limit ' => 400 ]]); Un appel à list() renvoie une instance de ListResponse . Vous pouvez utiliser son attribut records pour parcourir les résultats.
echo count ( $ customers -> records );
foreach ( $ customers -> records as $ resource ) {
echo $ resource -> given_name ;
}Dans le cas où un paramètre URL est nécessaire, la signature de la méthode contiendra les arguments requis :
$ customer = $ client -> customers ()-> get ( $ customer_id );
echo $ customer -> given_name ;Comme pour la liste, le dernier argument peut être un tableau d'options, avec n'importe quel paramètre d'URL donné :
$ client -> customers ()-> get ( $ customer_id , [ ' params ' => [ ' some_flag ' => true ]]); Les instances de ressource individuelle et ListResponse ont un attribut api_response , qui vous permet d'accéder aux propriétés suivantes de la requête :
statusheadersbody $ api_response = $ client -> customers ()-> get ( $ customer_id )-> api_response ;
echo $ api_response -> status_code ;Pour les requêtes POST et PUT, vous devez fournir un corps pour votre requête en le transmettant comme premier argument.
$ client -> customers ()-> create ([
' params ' => [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
]);Comme pour les requêtes GET, si des paramètres sont requis, ceux-ci viennent en premier :
$ client -> customers ()-> update ( $ customer_id , [
' params ' => [ ' family_name ' => ' Smith ' ]
]);L'API GoCardless inclut des clés d'idempotence. La bibliothèque les injectera automatiquement dans votre requête lorsque vous créerez une ressource, empêchant ainsi sa duplication en cas de problème avec l'API (par exemple, des problèmes de réseau ou un délai d'attente).
Vous pouvez également spécifier votre propre clé d'idempotence - vous pouvez, par exemple, utiliser les identifiants des enregistrements de votre base de données, vous protégeant non seulement des problèmes de réseau ou d'API, mais également des erreurs de votre part qui pourraient conduire à une double création :
$ client -> customers ()-> create ([
' params ' => [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
' headers ' => [ ' Idempotency-Key ' => ' ABC123 ' ]
]);Si la bibliothèque rencontre un conflit de clé d'idempotence (c'est-à-dire que vous essayez de créer une ressource avec une clé d'idempotence que vous avez déjà utilisée), elle chargera et renverra automatiquement la ressource déjà existante.
Lorsque l'API renvoie une erreur, la bibliothèque renvoie une sous-classe correspondante de ApiException , l'une des suivantes :
InvalidApiUsageExceptionInvalidStateExceptionValidationFailedExceptionCes types d'erreurs sont traités dans la documentation de l'API.
Si l'erreur est une erreur de couche de transport HTTP (par exemple, délais d'attente ou problèmes au sein de l'infrastructure de GoCardless), les requêtes seront automatiquement réessayées par la bibliothèque jusqu'à 3 fois, avec un délai de 500 ms entre les tentatives, avant qu'une ApiConnectionException ne soit déclenchée.
Si la bibliothèque ne peut pas analyser la réponse de GoCardless, elle lancera une 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.
}Les propriétés de l'exception sont accessibles avec les méthodes suivantes :
$e->getType();$e->getCode();$e->getErrors();$e->getDocumentationUrl();$e->getMessage();$e->getRequestId();$e->getApiResponse();GoCardless prend en charge les webhooks, vous permettant de recevoir des notifications en temps réel lorsque des événements se produisent dans votre compte, afin que vous puissiez prendre des mesures automatiques en réponse, par exemple :
Le client vous permet de valider qu'un webhook que vous recevez provient bien de GoCardless et de l'analyser dans des objets GoCardlessProResourcesEvent faciles à utiliser :
// 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 ' );
}Pour plus de détails sur l'utilisation des webhooks, consultez notre guide « Démarrer ».
Cette bibliothèque client ne prend en charge que PHP >= 8.1. Les versions antérieures de PHP sont désormais considérées comme en fin de vie et peuvent être exposées à des failles de sécurité.
Ce client est généré automatiquement à partir de Crank, une chaîne d'outils que nous espérons bientôt open source. Les problèmes devraient pour l'instant être signalés sur ce référentiel.
Veuillez ne pas modifier le code source vous-même, vos modifications seront annulées !
