Stripe PHP Library: Official SDK for Payments
/stripe-php
The Stripe PHP library is Stripe's official Composer package for calling the Stripe API from PHP applications, with typed resource classes that build themselves from the API's own responses. It handles retries, timeouts, and TLS configuration for you. Reach for it if you're already on Composer and want official support; skip it if you need a non-cURL HTTP stack, since the library leans on cURL by default.
What is the Stripe PHP Library?
The Stripe PHP library is the official PHP SDK that Stripe publishes for its payment API, distributed as the stripe/stripe-php Composer package. It ships pre-built resource classes for objects like customers and charges that initialize themselves dynamically from whatever the API returns. Both a modern client/service pattern and the older pre-7.33.0 static pattern are supported side by side.
Installation and Requirements
PHP 7.2.0 or later is required, though Stripe's own language version support policy flags PHP 7.2 and 7.3 as next in line to lose support, so upgrading your runtime sooner rather than later is worth doing. The primary install path is Composer: run `composer require stripe/stripe-php`, then load the library through Composer's autoloader with `require_once 'vendor/autoload.php';`. If you don't want Composer, download the latest release from GitHub and include `init.php` directly instead. Three PHP extensions have to be present for the bindings to work: curl (though you can swap in your own non-cURL client), json, and mbstring; Composer resolves these automatically, but a manual install needs to verify them by hand. Anyone stuck on PHP 5.4 or 5.5 (both past end of life) can fall back to stripe-php v6.43.1, and PHP 5.3 users (also past end of life) can use v5.9.2 instead, though neither legacy build gets newer API features.
Getting Started with Stripe PHP
A minimal integration instantiates a StripeClient with a secret key and calls a resource method on it, for example creating a customer with a description, email, and payment_method and then echoing the returned object. Newer code should use this client/service pattern; the library also still supports the static, legacy calling convention used before version 7.33.0 for teams that haven't migrated yet, with a migration guide linked from the project wiki. Once you're past the first call, `getLastResponse()` on any returned object exposes the raw response, including headers like Request-Id, which is useful when you're debugging a support ticket with Stripe directly.
Key Features and Advanced Configuration
- ✓Configurable CurlClient timeouts: setTimeout() and setConnectTimeout() override the library's DEFAULT_TIMEOUT and DEFAULT_CONNECT_TIMEOUT constants.
- ✓Custom cURL options, including CURLOPT_PROXY, passed straight into the CurlClient constructor for routing requests through a proxy.
- ✓Automatic retries via setMaxNetworkRetries(), with idempotency keys attached to retried requests so a timed-out charge isn't accidentally created twice.
- ✓Per-request API key and Stripe account overrides, aimed at apps like Stripe Connect platforms that need to switch credentials mid-process.
- ✓A PSR-3 compatible logger hook through setLogger(), so request and response messages can be routed somewhere other than PHP's default error_log.
- ✓rawRequest() on StripeClient, available since version 16 of the SDK, for hitting undocumented or private-beta endpoints the typed classes don't cover yet.
- ✓Public and private preview package builds tagged with -beta.X and -alpha.X suffixes, installable by pinning a specific version in composer.json.
- ✓setCABundlePath() to swap in your own CA certificate bundle instead of the one the library ships with.
Strengths
- ✓Typed resource classes initialize themselves from whatever the API returns, so the same client code keeps working as Stripe's API evolves.
- ✓Idempotency keys are attached to retried requests automatically once setMaxNetworkRetries() is set, cutting the risk of double-charging a customer after a timeout.
- ✓Both Composer and manual install paths are documented, plus a clear fallback for anyone stuck on end-of-life PHP versions.
- ✓MIT license, so there's no copyleft complication for embedding it in a commercial PHP product.
- ✓rawRequest() gives you an escape hatch to undocumented or preview endpoints without forking the library or waiting on a new release.
Version Support and Known Issues
- △The README currently says external contributions from first-time contributors are on hiatus, so new contributors are directed to open an issue rather than send a pull request.
- △PHP 7.2 and 7.3 are next in line to lose support per Stripe's language version policy, and the README notes each future major release keeps trimming older PHP versions from what's supported, so pinning to an old runtime has an expiration date.
- △The default HTTP transport is cURL; a non-cURL client is technically supported but not demonstrated in the README, so you're mostly on your own for wiring one up.
- △Telemetry about request latency and feature usage is sent to Stripe by default; it's a one-line setEnableTelemetry(false) to turn off, but easy to miss that it's on in the first place.
- △Public and private preview package versions (-beta.X, -alpha.X) can carry breaking changes between two preview releases without a major version bump, so pin an exact version if you use them.
- △Anyone still on PHP 5.3, 5.4, or 5.5 is stuck on years-old stripe-php releases (v5.9.2, v6.43.1) that won't pick up newer API features.
Who is This Library For?
Stripe PHP library fits PHP teams that already run Composer-based projects and need to accept payments, manage subscriptions, or use Stripe Connect without hand-rolling their own HTTP client against Stripe's API. It's a reasonable fit for teams that value first-party support and typed resource objects over building a thinner wrapper themselves. It's a poor fit if you're stuck pre-PHP-7.2, need a runtime without cURL, or wanted a payment abstraction that isn't tied to one provider's API shape.
Considering Other Payment Integration Options
Frequently Asked Questions
Stripe PHP library requires PHP 7.2.0 or later. Per Stripe's language version support policy, PHP 7.2 and 7.3 are next in line to lose support, and each future major release trims additional older PHP versions, so staying current avoids losing access to updates.
The standard path is Composer: run composer require stripe/stripe-php, then load it via require_once 'vendor/autoload.php'. Without Composer, download the latest release from GitHub and include init.php directly instead.
Stripe PHP library needs the curl, json, and mbstring extensions to work correctly, though a non-cURL HTTP client can replace curl if preferred. Composer installs handle these automatically; manual installs need to confirm the extensions are present.
Create a Stripe\HttpClient\CurlClient instance, call setTimeout() and setConnectTimeout() to override the defaults, or pass a CURLOPT_* array (for a proxy, for example) to the constructor, then register it with Stripe\ApiRequestor::setHttpClient().
Stripe PHP library sends telemetry about request latency and feature usage to Stripe by default. It can be turned off with a single call to Stripe::setEnableTelemetry(false).
Stripe PHP library is open source, released under the MIT license, and hosted publicly on GitHub under stripe/stripe-php.
The problem it solves
Calling the Stripe API directly from PHP means hand-building cURL requests, parsing JSON responses yourself, and re-implementing retry and idempotency logic, and older Linux distributions such as CentOS and RHEL make it worse because they can default to TLS 1.0/1.1 even when TLS 1.2 is installed, which Stripe's API now rejects. The stripe-php library wraps that HTTP layer with resource classes that parse themselves, a configurable CurlClient with automatic retries, and idempotency keys added automatically on retried requests, so PHP developers aren't rebuilding the same low-level plumbing app by app.
Best use cases
- •Charging cards and creating customers from a PHP backend using typed resource classes instead of hand-parsed API responses.
- •Running a Stripe Connect platform that needs to switch between multiple connected accounts and API keys per request.
- •Integrating Stripe into a WordPress or Laravel plugin, using setAppInfo() to identify the plugin to Stripe as the README recommends for plugin developers.
- •Trying an in-development Stripe feature early by pinning a -beta.X or -alpha.X preview package version.
- •Calling an undocumented or private-beta Stripe endpoint through rawRequest() without waiting for the typed SDK classes to catch up.
Related repositories
Want a second opinion on stripe-php?
Ask an AI that can read this page — one click and you get its take on stripe-php.