Stripe PHP

Stripe-PHP-Bindungen

Die Stripe-PHP-Bibliothek bietet bequemen Zugriff auf die Stripe-API aus Anwendungen, die in der PHP-Sprache geschrieben sind. Es enthält einen vordefinierten Satz von Klassen für API-Ressourcen, die sich dynamisch anhand von API-Antworten initialisieren, wodurch es mit einer Vielzahl von Versionen der Stripe-API kompatibel ist.

Anforderungen

PHP 5.6.0 und höher.

Komponist

Sie können die Bindungen über Composer installieren. Führen Sie den folgenden Befehl aus:

composer require stripe/stripe-php

Um die Bindungen zu verwenden, verwenden Sie das automatische Laden von Composer:

 require_once ' vendor/autoload.php ' ;

Manuelle Installation

Wenn Sie Composer nicht verwenden möchten, können Sie die neueste Version herunterladen. Um die Bindungen zu verwenden, fügen Sie dann die Datei init.php ein.

 require_once ' /path/to/stripe-php/init.php ' ;

Abhängigkeiten

Die Bindungen erfordern die folgenden Erweiterungen, um ordnungsgemäß zu funktionieren:

• curl , obwohl Sie bei Bedarf auch Ihren eigenen Nicht-cURL-Client verwenden können
• json
• mbstring (Multibyte-String)

Wenn Sie Composer verwenden, sollten diese Abhängigkeiten automatisch behandelt werden. Wenn Sie die Installation manuell durchführen, sollten Sie sicherstellen, dass diese Erweiterungen verfügbar sind.

Erste Schritte

Die einfache Verwendung sieht folgendermaßen aus:

 $ stripe = new  Stripe  StripeClient ( ' sk_test_BQokikJOvBiI2HlWgH4olfQ2 ' );
$ customer = $ stripe -> customers -> create ([
    ' description ' => ' example customer ' ,
    ' email ' => ' [email protected] ' ,
    ' payment_method ' => ' pm_card_visa ' ,
]);
echo $ customer ;

Client-/Dienstmuster im Vergleich zu Legacy-Mustern

Sie können weiterhin die älteren Integrationsmuster verwenden, die vor Version 7.33.0 verwendet wurden. Sehen Sie sich den Migrationsleitfaden für die abwärtskompatiblen Client-/Dienstmusteränderungen an.

Dokumentation

Siehe die PHP-API-Dokumente.

Sehen Sie sich Videodemonstrationen zur Nutzung der Bibliothek an.

Unterstützung älterer Versionen

PHP 5.4 und 5.5

Wenn Sie PHP 5.4 oder 5.5 verwenden, sollten Sie ein Upgrade Ihrer Umgebung in Betracht ziehen, da diese Versionen seit September 2015 bzw. Juli 2016 nicht mehr gültig sind. Andernfalls können Sie Stripe weiterhin verwenden, indem Sie Stripe-php v6.43.1 (zip, tar.gz) von unserer Release-Seite herunterladen. Diese Version wird funktionieren, unterstützt jedoch möglicherweise nicht die neuesten Funktionen, die wir seit der Veröffentlichung der Version hinzugefügt haben, und ein Upgrade von PHP ist die beste Vorgehensweise.

PHP 5.3

Wenn Sie PHP 5.3 verwenden, sollten Sie Ihre Umgebung aktualisieren, da diese Version seit August 2014 nicht mehr verfügbar ist. Andernfalls können Sie v5.9.2 (zip, tar.gz) von unserer Release-Seite herunterladen. Diese Version funktioniert weiterhin mit neuen Versionen der Stripe-API für alle gängigen Verwendungszwecke.

Zeitüberschreitungen bei benutzerdefinierten Anfragen

Hinweis: Wir empfehlen nicht, das Timeout für nicht schreibgeschützte Aufrufe (z. B. Gebührenerstellung) zu verringern, da die Anfrage auf Stripe-Seite auch bei lokalem Timeout noch abgeschlossen werden kann. Wenn Sie die Zeitüberschreitungen bei diesen Aufrufen verringern, achten Sie darauf, Idempotenz-Tokens zu verwenden, um zu vermeiden, dass dieselbe Transaktion aufgrund der Zeitüberschreitungs-Wiederholungslogik zweimal ausgeführt wird.

Um die Anforderungszeitüberschreitungen (Verbindung oder Gesamtzeit in Sekunden) zu ändern, müssen Sie den API-Client anweisen, einen anderen CurlClient als seinen Standard zu verwenden. Sie legen die Zeitüberschreitungen in diesem CurlClient fest.

 // set up your tweaked Curl client
$ curl = new  Stripe  HttpClient  CurlClient ();
$ curl -> setTimeout ( 10 ); // default is StripeHttpClientCurlClient::DEFAULT_TIMEOUT
$ curl -> setConnectTimeout ( 5 ); // default is StripeHttpClientCurlClient::DEFAULT_CONNECT_TIMEOUT

echo $ curl -> getTimeout (); // 10
echo $ curl -> getConnectTimeout (); // 5

// tell Stripe to use the tweaked client
 Stripe  ApiRequestor :: setHttpClient ( $ curl );

// use the Stripe API client as you normally would 

Benutzerdefinierte cURL-Optionen (z. B. Proxys)

Müssen Sie einen Proxy für Ihre Anfragen einrichten? Übergeben Sie das erforderliche CURLOPT_* Array an den CurlClient-Konstruktor und verwenden Sie dabei dieselbe Syntax wie curl_stopt_array() . Dadurch werden die Standard-cURL-Optionen für jede vom SDK gestellte HTTP-Anfrage festgelegt, obwohl viele weitere gängige Optionen (z. B. Zeitüberschreitungen; siehe oben zum Festlegen dieser Optionen) vom Client überschrieben werden, selbst wenn sie hier festgelegt werden.

 // set up your tweaked Curl client
$ curl = new  Stripe  HttpClient  CurlClient ([ CURLOPT_PROXY => ' proxy.local:80 ' ]);
// tell Stripe to use the tweaked client
 Stripe  ApiRequestor :: setHttpClient ( $ curl );

Alternativ kann ein Callable an den CurlClient-Konstruktor übergeben werden, der das obige Array basierend auf Anforderungseingaben zurückgibt. Ein Beispiel für dieses Verhalten finden Sie unter testDefaultOptions() in tests/CurlClientTest.php . Beachten Sie, dass das Callable zu Beginn jeder API-Anfrage aufgerufen wird, bevor die Anfrage gesendet wird.

Konfigurieren eines Loggers

Die Bibliothek führt nur eine minimale Protokollierung durch, kann jedoch mit einem PSR-3 kompatiblen Logger konfiguriert werden, sodass Nachrichten dort anstelle von error_log landen:

 Stripe  Stripe :: setLogger ( $ logger );

Auf Antwortdaten zugreifen

Sie können über getLastResponse() auf die Daten der letzten API-Antwort für jedes Objekt zugreifen.

 $ customer = $ stripe -> customers -> create ([
    ' description ' => ' example customer ' ,
]);
echo $ customer -> getLastResponse ()-> headers [ ' Request-Id ' ];

Probleme mit der SSL-/TLS-Kompatibilität

Die API von Stripe erfordert jetzt, dass alle Verbindungen TLS 1.2 verwenden. Einige Systeme (insbesondere einige ältere CentOS- und RHEL-Versionen) können TLS 1.2 verwenden, verwenden jedoch standardmäßig TLS 1.0 oder 1.1. In diesem Fall erhalten Sie einen invalid_request_error mit der folgenden Fehlermeldung: „Stripe unterstützt keine mit TLS 1.0 erstellten API-Anfragen mehr. Bitte initiieren Sie HTTPS-Verbindungen mit TLS 1.2 oder höher. Weitere Informationen hierzu finden Sie unter https://stripe .com/blog/upgrading-tls.“.

Die empfohlene Vorgehensweise besteht darin, Ihre cURL- und OpenSSL-Pakete zu aktualisieren, sodass TLS 1.2 standardmäßig verwendet wird. Wenn dies jedoch nicht möglich ist, können Sie das Problem möglicherweise lösen, indem Sie die Option CURLOPT_SSLVERSION entweder auf CURL_SSLVERSION_TLSv1 oder CURL_SSLVERSION_TLSv1_2 setzen:

 $ curl = new  Stripe  HttpClient  CurlClient ([ CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1 ]);
 Stripe  ApiRequestor :: setHttpClient ( $ curl );

Konfiguration auf Anfrage

Für Apps, die während der Lebensdauer eines Prozesses mehrere Schlüssel verwenden müssen, wie z. B. eine, die Stripe Connect verwendet, ist es auch möglich, einen Schlüssel und/oder ein Konto pro Anfrage festzulegen:

 $ customers = $ stripe -> customers -> all ([],[
    ' api_key ' => ' sk_test_... ' ,
    ' stripe_account ' => ' acct_... '
]);

$ stripe -> customers -> retrieve ( ' cus_123456789 ' , [], [
    ' api_key ' => ' sk_test_... ' ,
    ' stripe_account ' => ' acct_... '
]);

Konfigurieren von CA-Bundles

Standardmäßig verwendet die Bibliothek ihr eigenes internes Paket bekannter CA-Zertifikate, es ist jedoch möglich, Ihr eigenes zu konfigurieren:

 Stripe  Stripe :: setCABundlePath ( " path/to/ca/bundle " );

Automatische Wiederholungsversuche konfigurieren

Die Bibliothek kann so konfiguriert werden, dass Anfragen, die aufgrund eines zeitweiligen Netzwerkproblems fehlschlagen, automatisch wiederholt werden:

 Stripe  Stripe :: setMaxNetworkRetries ( 2 );

Den Anfragen werden Idempotenzschlüssel hinzugefügt, um sicherzustellen, dass Wiederholungsversuche sicher sind.

Telemetrie

Standardmäßig sendet die Bibliothek Telemetriedaten zur Anforderungslatenz und Funktionsnutzung an Stripe. Diese Zahlen helfen Stripe, die Gesamtlatenz seiner API für alle Benutzer zu verbessern und beliebte Funktionen zu verbessern.

Sie können dieses Verhalten bei Bedarf deaktivieren:

 Stripe  Stripe :: setEnableTelemetry ( false );

Beta-SDKs

Stripe verfügt über Funktionen in der Beta-Phase, auf die über die Beta-Version dieses Pakets zugegriffen werden kann. Wir würden uns freuen, wenn Sie diese ausprobieren und Ihr Feedback mit uns teilen, bevor diese Funktionen die stabile Phase erreichen. Verwenden Sie den composer require mit einer genauen Versionsangabe, um die Betaversion des Stripe-PHP-Pakets zu installieren.

composer require stripe/stripe-php:v9.2.0-beta.1

Hinweis: Zwischen den Betaversionen kann es zu wichtigen Änderungen kommen. Daher empfehlen wir, die Paketversion an eine bestimmte Betaversion in Ihrer Composer.json-Datei anzuheften. Auf diese Weise können Sie jedes Mal dieselbe Version installieren, ohne Änderungen vorzunehmen, es sei denn, Sie suchen absichtlich nach der neuesten Beta-Version.

Wir empfehlen dringend, im Auge zu behalten, wann die Beta-Funktion, an der Sie interessiert sind, von der Beta-Version zur stabilen Version wechselt, damit Sie von der Verwendung einer Beta-Version des SDK zur stabilen Version wechseln können.

Wenn Ihre Beta-Funktion das Senden eines Stripe-Version Headers erfordert, legen Sie die apiVersion Eigenschaft des config mithilfe der Funktion addBetaVersion fest:

 Stripe :: addBetaVersion ( " feature_beta " , " v3 " );

Individuelle Anfragen

Wenn Sie eine Anfrage an eine undokumentierte API senden möchten (z. B. wenn Sie sich in einer privaten Betaversion befinden) oder wenn Sie lieber die Methodendefinitionen in der Bibliothek umgehen und Ihre Anfragedetails direkt angeben möchten, können Sie die rawRequest -Methode verwenden StripeClient.

"2022-11_15", ]); // $response->body is a string, you can call $stripe->deserialize to get a StripeStripeObject. $obj = $stripe->deserialize($response->body); // For GET requests, the params argument must be null, and you should write the query string explicitly. $get_response = $stripe->rawRequest('get', '/v1/beta_endpoint?caveat=emptor', null, [ "stripe_version" => "2022-11_15", ]);">

 $ stripe = new  Stripe  StripeClient ( ' sk_test_xyz ' );
$ response = $ stripe -> rawRequest ( ' post ' , ' /v1/beta_endpoint ' , [
  " caveat " : " emptor "
], [
  " stripe_version " => " 2022-11_15 " ,
]);
// $response->body is a string, you can call $stripe->deserialize to get a StripeStripeObject.
$ obj = $ stripe -> deserialize ( $ response -> body );

// For GET requests, the params argument must be null, and you should write the query string explicitly.
$ get_response = $ stripe -> rawRequest ( ' get ' , ' /v1/beta_endpoint?caveat=emptor ' , null , [
  " stripe_version " => " 2022-11_15 " ,
]);

Unterstützung

Neue Funktionen und Fehlerbehebungen werden in der neuesten Hauptversion der Stripe PHP-Bibliothek veröffentlicht. Wenn Sie eine ältere Hauptversion verwenden, empfehlen wir Ihnen, auf die neueste Version zu aktualisieren, um die neuen Funktionen und Fehlerbehebungen, einschließlich derer für Sicherheitslücken, nutzen zu können. Ältere Hauptversionen des Pakets stehen weiterhin zur Nutzung zur Verfügung, erhalten jedoch keine Updates.

Entwicklung

Holen Sie sich Composer. Zum Beispiel unter Mac OS:

brew install composer

Abhängigkeiten installieren:

composer install

Die Testsuite hängt von Stripe-Mock ab. Stellen Sie daher sicher, dass Sie sie von einem Hintergrundterminal abrufen und ausführen (die README-Datei von Stripe-Mock enthält auch Anweisungen für die Installation über Homebrew und andere Methoden):

go install github.com/stripe/stripe-mock@latest
stripe-mock

Installieren Sie die Abhängigkeiten wie oben erwähnt (wodurch PHPUnit aufgelöst wird), dann können Sie die Testsuite ausführen:

./vendor/bin/phpunit

Oder um eine einzelne Testdatei auszuführen:

./vendor/bin/phpunit tests/Stripe/UtilTest.php

Aktualisieren Sie die gebündelten CA-Zertifikate aus der Mozilla cURL-Version:

./update_certs.php

Die Bibliothek verwendet PHP CS Fixer zur Codeformatierung. Code muss formatiert werden, bevor PRs übermittelt werden, andernfalls schlägt CI fehl. Führen Sie den Formatierer aus mit:

./vendor/bin/php-cs-fixer fix -v . 

Plugin-Entwickler aufgepasst

Schreiben Sie ein Plugin, das Stripe integriert und unsere Bibliothek einbettet? Dann verwenden Sie bitte die Funktion setAppInfo um Ihr Plugin zu identifizieren. Zum Beispiel:

 Stripe  Stripe :: setAppInfo ( " MyAwesomePlugin " , " 1.2.34 " , " https://myawesomeplugin.info " );

Die Methode sollte einmal aufgerufen werden, bevor eine Anfrage an die API gesendet wird. Der zweite und dritte Parameter sind optional.

SSL/TLS-Konfigurationsoption

Den vollständigen Kontext finden Sie oben im Absatz „SSL-/TLS-Kompatibilitätsprobleme“. Wenn Sie sicherstellen möchten, dass Ihr Plugin auf allen Systemen verwendet werden kann, sollten Sie eine Konfigurationsoption hinzufügen, mit der Ihre Benutzer zwischen verschiedenen Werten für CURLOPT_SSLVERSION wählen können: none (Standard), CURL_SSLVERSION_TLSv1 und CURL_SSLVERSION_TLSv1_2 .