Stripe Bundle Laravel Package

Getting Started

Reality check before you write a line of code: quartet/stripe-bundle is a Symfony2 bundle, not a Laravel package. There is no service provider, no config publishing, no facade, and no Illuminate-friendly hook. As a Laravel developer, your realistic "first use case" is reading it as a reference for structuring a thin Stripe wrapper, not installing it. Attempting composer require in a Laravel 9/10/11 project will fail dependency resolution or drag in Symfony 2.x components that conflict with the framework — do not force it.

If you are auditing a legacy Symfony 2.x app that already depends on it, the day-one checklist is:

1. Find the service ID in Resources/config/services.xml — typically quartet_stripe.client. Do not trust a README; the XML is the source of truth.
2. Read the config tree in DependencyInjection/Configuration.php — that's where secret_key, publishable_key, and any client options are defined.
3. Check the pinned stripe/stripe-php version in the bundle's composer.json. This tells you instantly whether the integration is pre- or post-PaymentIntents (post-2019 = usable; pre-2019 = SCA-broken for EU/UK traffic).
4. Confirm the Stripe API version pinned in the account dashboard matches what the bundled SDK expects.

First meaningful use (legacy Symfony only):

$client = $this->get('quartet_stripe.client');
$charge = $client->charges->create([
    'amount'      => 2000,
    'currency'    => 'usd',
    'source'      => $tokenFromStripeJs,
    'description' => 'Order #123',
]);

For a Laravel project, jump straight to stripe/stripe-php behind a first-party service class — or laravel/cashier if you need subscription semantics. This bundle is reference material, not a dependency.

Implementation Patterns

Treat the source as a template, not a library. The bundle's actual value to a Laravel dev is the shape of its service wiring: it demonstrates how to register the raw \Stripe\StripeClient as a container singleton with config-injected keys. That pattern ports cleanly to a Laravel service provider:

// app/Providers/StripeServiceProvider.php
public function register(): void
{
    $this->app->singleton(StripeClient::class, fn () =>
        new StripeClient(config('services.stripe.secret'))
    );
}

Wrap it, never inject it raw. Whether you inherited a Symfony app or you're porting the pattern to Laravel, the day-to-day discipline is the same: inject the Stripe client into a PaymentService you own, and only that service touches \Stripe\* classes. One seam for mocking, one seam for API-version upgrades, one seam for swapping in PaymentIntents later.

Webhook handling — pin the SDK and verify every event. Register a dedicated controller/route, read php://input, and verify the signature header. On the old SDK versions this bundle shipped with, the helper is \Stripe\Webhook::constructEvent($payload, $sigHeader, $secret). Signature-verification behavior has changed across major SDK versions; this is the single most common cause of silently dropped events on legacy integrations. If you migrate to Laravel, use \Stripe\Webhook::constructEvent from the current SDK and register the route in routes/api.php with VerifyCsrfToken excluded.

Token flow with Stripe.js. The bundle does not render forms. Frontend creates a token (or, on modern Stripe, a PaymentMethod); backend receives it and passes it as source. In Laravel, inject the publishable key into the Blade view via config, never hardcoded.

Idempotency keys on every create call. If you're porting the bundle's charge-creation pattern, add idempotency from day one — the original likely didn't:

$client->charges->create($params, ['idempotency_key' => $orderUuid]);

This is the difference between "customer got charged twice" and "we retried safely."

Event ordering on migration. If you are the unlucky person decommissioning this bundle, migrate webhook handling first (highest risk of silent failure), then charge/payment creation, then refunds and subscriptions. Run parity tests against Stripe test mode before cutting over.

Gotchas and Tips

• It will not install in Laravel. Symfony 2.3–2.8 component constraints will conflict with any modern illuminate/* package on PHP 8.x. Do not spend a day forcing it with --ignore-platform-reqs — you'll end up with a broken autoloader and no closer to a payment flow. The correct Laravel move is replacement, not adoption.

• The service ID is a guess until you read services.xml. Bundle conventions vary (quartet_stripe.client, quartet.stripe.client, stripe); one wrong character costs an hour of ServiceNotFoundException debugging. Read the XML.

• Configuration.php beats any README. On an unmaintained bundle, the code is the only source of truth for config keys. Expect things like secret_key, publishable_key, test_mode — but verify.

• Pre-SCA SDK = broken for EU/UK cards. If the bundled stripe/stripe-php predates PaymentIntent support, card charges from SCA-enforced regions will fail with authentication_required. This is not a bug you fix in the bundle — it's a rewrite around PaymentIntents.

• Webhook signature failures fail silently. Old SDKs may reject modern Stripe signature formats (v1= scheme changes, timestamp tolerance). Nothing shows in your app log because the exception happens before your handler runs. Add explicit logging around verification, and test against the Stripe CLI sender.

• API version drift is a ticking clock. Stripe deprecates old API versions on a rolling basis. A pinned 2016-era SDK will eventually receive responses its parser doesn't understand. Check the account's pinned API version against the SDK's ApiVersion::CURRENT — if there's more than one major version gap, budget the migration.

• Keys in config.yml, not in code. The bundle's convention is parameters.yml for secrets — equivalent to Laravel's config/services.php + .env. Never commit real keys; never read them from the bundle's config tree at runtime — go through your own config('services.stripe.*') seam so migration is a one-file change.

• Debugging checklist when a charge mysteriously fails: (1) Stripe dashboard logs first — the API response body tells you more than any stack trace; (2) confirm the idempotency key isn't being reused across different requests; (3) confirm the currency is a zero-decimal or two-decimal currency and the amount is in minor units; (4) confirm the API version in use matches the SDK's assumption.

• Extension points you'll actually use: the bundle is a thin wrapper — there's rarely a useful hook beyond swapping the client service definition. Don't try to extend it; wrap it. If you need custom behavior (retries, metrics, circuit breaking), put it in your PaymentService, not in a bundled subclass.

• Nobody will answer an issue. 0 stars, 0 dependents, 0 maintainers. Every unknown becomes your archaeology project. Treat any decision to keep this bundle in production as an explicit "we own this fork forever" commitment in the ticket — that's the honest framing to put in front of whoever is asking you to ship against it.