Stripe Cashier Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. If you're a Laravel developer, your day-to-day Stripe work should stay on laravel/cashier — it's first-party, heavily tested, and documented. This bundle is relevant to you only if you also maintain Symfony services or are evaluating it as a reference port. That framing hasn't changed in v1.6.0.

Minimal setup on a Symfony app:

1. composer require makfly/stripe-cashier-bundle:^1.6.0 (pin the minor — see Gotchas).
2. Register the bundle in config/bundles.php (MakFly\StripeCashierBundle\StripeCashierBundle::class => ['all' => true]).
3. Publish/import the bundle config (config/packages/stripe_cashier.yaml) and set STRIPE_KEY, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET in .env.
4. Run the bundle's Doctrine migrations to create subscriptions, subscription_items, and invoice-related tables.
5. Make your user entity "billable" by adding the provided trait/interface (the Cashier analogue of Billable).

First use case: attach a subscription to a user after checkout — inject the Cashier-style manager service, call subscribe($user, 'price_xxx'), and persist the returned subscription entity. Confirm the webhook endpoint is reachable before you wire any UI.

Where to look first: the README — which now has substantive 1.6.0 sections covering multi-plan, Meters API, and automatic tax — then the DependencyInjection/ config loader and the Entity/ directory. The source is still the primary documentation; there's no doc site.

Implementation Patterns

• Billable entity trait. Mirror the Laravel Billable contract: your User gets subscriptions(), subscribed(), onTrial(), subscribedToPrice() helpers. Treat the trait as the seam — wrap it behind your own application service rather than calling the bundle directly from controllers, because the API surface is a small, single-maintainer project and you'll likely need to swap or pin it.
• Service injection over facades. Symfony has no Cashier:: facade; inject the cashier manager into your checkout/subscription services. Keep the bundle types out of your controller signatures and map to your own DTOs so an upgrade can't cascade through your app.
• Multi-plan is now real (v1.6.0). refactor: real multi-plan operations means you can hold several plans on one subscription entity instead of hand-rolling parallel subscriptions. Model your app around the subscription's items rather than the subscription itself — this is also the shape you'll need for metered lines.
• Metered billing via Meters API (v1.6.0). createUsageRecord is superseded by Stripe's Meters API in this release. If you're porting existing usage-billing code, create the meter in Stripe first, attach a metered price, then report usage through the bundle's manager. Verify the quantity method signatures — the same release ships an explicitly named align quantity method signatures refactor, which is the kind of change that renames arguments on you.
• Automatic tax is wired end-to-end (v1.6.0), including customer tax ID handling. If you previously skipped the bundle because you needed tax, re-evaluate — but audit your webhook handlers for the new customer-update events before enabling it on live keys.
• Webhook-first, not redirect-first. Treat the Stripe webhook as the source of truth for subscription state and use the checkout redirect only for UX. Confirm the bundle verifies Stripe-Signature before you trust any event; if the bundle's listener doesn't, add your own guard kernel event.
• Idempotency. Still assume webhook handlers are not production-hardened. Store processed event.ids yourself and short-circuit duplicates, especially for invoice.paid and customer.subscription.updated. New in 1.6.0: metered-usage and tax events add more idempotency surface — dedupe on event.id, not on your own subscription ID.
• Integration tips. Keep STRIPE_WEBHOOK_SECRET per-environment, expose /stripe/webhook as an unauthenticated POST route excluded from CSRF, and test with stripe listen --forward-to. For Connect, or features beyond subscriptions/meters/tax, reach for the raw stripe/stripe-php SDK the bundle already depends on.

Gotchas and Tips

• Adoption risk is still the headline. ~21 stars, 0 dependents, one maintainer, Symfony 8-only. 1.6.0 is a large feature drop from a small project — that's more surface to own, not less. Pin the version (^1.6.0 at most), read the changelog before every update, and budget for the possibility that you become the maintainer of your fork.
• Phantom tags — now explained, not fixed retroactively. 1.6.0 removes the auto-tag workflow that generated a release on every push to main. Good change, but the existing tag history is polluted: old tags/dates you see on Packagist may not correspond to intentional releases. Trust specific tags (v1.6.0) and the changelog over the release list, and sanity-check commit SHAs before pinning.
• The "anomalous release date" caveat is resolved. The prior 2026-07-18 oddity traces back to the auto-tag pipeline; with that workflow removed, release dates from 1.6.0 forward should be trustworthy. Don't carry the old suspicion forward, but don't retroactively trust the pre-1.6.0 dates either.
• Not a Laravel drop-in. There's no Cashier:: facade, no familiar Billable namespace, no artisan commands, and Doctrine entities instead of Eloquent models. Any "just like Cashier" assumption will cost you time.
• Webhook signature verification is the #1 thing to audit. Open Event/ or Http/ and confirm Webhook::constructEvent is invoked with the raw body. A mis-verified listener is a silent security hole — and 1.6.0 touches the payload paths (meter payload hardening, tax events), so re-audit rather than trusting a prior review.
• "Harden meter payload" is a hint. The refactor commit name implies payload shape changed. If you were already sending usage records via a pre-1.6.0 path, treat that as breaking and re-test against a Stripe test clock.
• Migrations. The bundle ships Doctrine migrations; check whether they're auto-run or manual, and whether table names collide with existing billing tables in a brownfield schema. Multi-plan support may alter subscription_items semantics — review the diff before migrating a table with live rows.
• Extension points. The config tree and the service definitions in Resources/config/ are where you'd override the manager or swap an entity. Prefer decorating the manager service over editing vendor code — you'll need that overlay when you patch webhook handling or the new tax flow.
• Fallback plan. If you hit a blocker, drop the bundle and use stripe/stripe-php directly with two Doctrine entities (Subscription, SubscriptionItem). That gap is narrower than it was — 1.6.0 now covers meters and tax, which used to be the strongest argument for going raw — but the SDK remains the only thing with Stripe's own support behind it.