Stripe Bundle Laravel Package

Getting Started

Verdict up front: for a new Laravel app, do not install this bundle. It is a Symfony 2 bundle with no Laravel auto-discovery, no service provider, no facade, and dependency constraints that will fight modern Laravel. Install stripe/stripe-php directly and write a small Laravel service provider. Use this package as a reference for how to structure configuration and service wiring, not as a runtime dependency.

If you are maintaining a legacy Symfony 2 application, the minimal path is:

1. composer require wemakecustom/stripe-bundle
2. Register the bundle in app/AppKernel.php:

   new WemakeCustom\Bundle\StripeBundle\WemakeCustomStripeBundle(),
   

3. Add configuration under the bundle's config key in app/config/config.yml — check DependencyInjection/Configuration.php for the exact root key and available options (typically API key, API version, and possibly public key).
4. Put real keys in app/config/parameters.yml / environment-specific config, never in the bundle config committed to the repo.
5. First use case: create a customer or charge from a controller by injecting the bundle's Stripe service rather than calling $this->container->get(...) directly.

Where to look first:

• README.md for the documented config key and service id.
• DependencyInjection/Configuration.php for the real config schema.
• Resources/config/services.xml (or YAML) for the service ids and constructor arguments.
• Tests/ for the expected usage shape and mocked Stripe interactions.

For a Laravel developer evaluating it, the mapping is:

If you want to reuse the bundle's ideas in Laravel, copy the config shape and the thin wrapper approach into a StripeServiceProvider, and bind Stripe\StripeClient (or a small StripeGateway class) as a singleton.

Implementation Patterns

Inject a wrapper, not the SDK everywhere. The bundle's main value is that it centralizes Stripe client construction. In Laravel, mirror that: bind one StripeClient or StripeGateway singleton in a service provider, configure it from config('services.stripe.secret'), and inject that into controllers, jobs, and listeners. Avoid scattering new \Stripe\StripeClient(...) across the codebase.

Keep Stripe calls behind an application service. Create something like App\Services\Billing\StripeGateway with methods such as charge(), createCustomer(), refund(), and createSubscription(). This is the same reason the Symfony bundle exposes a service instead of letting controllers touch the SDK: it gives you one place to mock, log, retry, and change API versions.

Configuration per environment. In Symfony 2, the bundle expects keys from parameters.yml; in Laravel, use config/services.php plus .env. Never let production and test keys share the same config path. Use Stripe test keys locally and in CI.

Webhook handling. The bundle does not remove the need for a webhook endpoint. In Symfony, you would add a route and controller that receives the raw body and verifies the Stripe signature. In Laravel, do the same with a route that bypasses CSRF and reads $request->getContent(). Verify the signature with the current stripe/stripe-php helper, then dispatch a job. Treat webhook handlers as idempotent: Stripe can deliver the same event more than once.

Use events/listeners for post-payment side effects. Rather than putting email sending, provisioning, or invoice updates inside the controller after a charge, dispatch a domain event (PaymentSucceeded, SubscriptionCancelled) and handle it in listeners or queued jobs. This mirrors Symfony's event dispatcher pattern and keeps the Stripe integration thin.

Testing pattern. Mock your own gateway interface, not the Stripe SDK. If you must test against Stripe, use test keys and Stripe's test card numbers. For the Symfony bundle, the existing tests likely mock the SDK service; follow that pattern rather than hitting the network.

Laravel bridge pattern, if you insist on using the bundle. You can manually register the bundle's service definitions in a Laravel service provider by loading its XML/YAML config and binding the service id, but this is usually more work than rewriting the ~50 lines of wiring yourself. The bundle's service definitions assume Symfony's container features and may not resolve cleanly in Laravel's container.

Extension point. In Symfony, the bundle's compiler pass or service definition can be overridden in services.yml. In Laravel, the equivalent extension point is your own service provider: bind an interface to your gateway and swap the implementation in tests or across environments.

Gotchas and Tips

• Symfony 2 is end-of-life. The bundle targets an obsolete framework and likely pins old PHP and Symfony constraints. Composer will probably refuse to install it alongside modern Laravel or Symfony versions. Do not fight the resolver; use the Stripe SDK directly.
• No Laravel package discovery. There is no extra.laravel block, no service provider, and no facade. You must wire everything manually, and the bundle's Symfony-specific classes will not autoload usefully in a Laravel app.
• Old Stripe SDK API surface. The bundle was written against an older stripe/stripe-php. Exception classes, method signatures, and object properties have changed. Code copied from the bundle may use Stripe\Error\Card instead of modern Stripe\Exception\CardException, or may assume pre-StripeClient static calls.
• API version drift. Stripe changes its API over time. If the bundle pins an old API version, objects may lack fields your code expects. Explicitly set the API version in your own client configuration and test against it.
• Amounts are in the smallest currency unit. A $10.00 charge is 1000. This is an easy source of off-by-100 bugs, especially when copying examples.
• Webhook signature verification is mandatory. If the bundle predates Stripe's signature scheme or examples skip it, add verification yourself. Also ensure your route is excluded from CSRF and that you read the raw request body.
• Idempotency and duplicate events. Use idempotency keys for create operations and make webhook handlers safe to run twice. Store processed event IDs if needed.
• Secrets in config. Symfony 2's parameters.yml is often committed. Keep Stripe secret keys in environment variables or an untracked parameters file. In Laravel, use .env and never commit it.
• Error handling. Catch Stripe exceptions at the gateway boundary, map them to domain exceptions, and return safe messages to users. Do not leak raw Stripe error payloads.
• Maintenance risk. Seven stars and zero dependents means this is effectively an abandoned, low-traffic package. There is no community safety net. Treat it as a reference implementation, not a dependency you can rely on for security updates.
• Debugging tips. Log the Stripe request ID from responses and errors; it is the fastest way to get help from Stripe support. In Symfony, use the profiler to inspect the service; in Laravel, use Log::withContext() around gateway calls.
• Extension points are limited. The bundle likely exposes a service you can override, but it is not designed for Laravel-style swapping. If you need custom retry logic, circuit breaking, or multi-account routing, build that in your own gateway class rather than trying to extend the bundle.