Laravel Billing Laravel Package

Getting Started

• Install with Composer alongside a Laravel 4 project (mmanos/laravel-billing), then register Mmanos\Billing\BillingServiceProvider and the Billing facade in app/config/app.php.
• Publish the package config and migrations, then run them:

  php artisan config:publish mmanos/laravel-billing
  php artisan migrate --package="mmanos/laravel-billing"
  

• Put your gateway credentials (typically Stripe keys) in the published package config under app/config/packages/mmanos/laravel-billing/.
• Add the package's billable trait to your User model so the user becomes a billing "customer" that owns subscriptions, cards, and invoices.
• Look first at: the README's Usage section, src/ (the service provider, the Billing facade, and the gateway driver(s)), and the migrations — the migrations are the real contract: they define customers, plans, subscriptions, invoices, charges/coupons tables.
• First use case: store a card token, create a customer, and subscribe to a plan:

  Billing::customer($user)->card($token);          // attach token
  Billing::customer($user)->subscription($plan);   // start subscription
  

Implementation Patterns

• Plan mapping: Seed local Plan rows whose gateway plan IDs match what you create in Stripe. Always resolve plans server-side by ID; never accept client-supplied prices.
• Subscription lifecycle: Model subscribe / swap / cancel-at-period-end / resume as explicit service methods. Keep the local subscriptions row as a cache of gateway state and reconcile via webhooks.
• Webhooks are the source of truth: Build a webhook controller for invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted, and route them into package handlers or your own listeners. This is how renewals, dunning, and cancellations actually land.
• Invoices and one-off charges: Use the package to list/download invoices for the user's billing history, and issue one-off charges for metered or overage usage.
• Entitlements/gating: In controllers and views, gate features on Billing::customer($user)->subscription(...) and its plan, rather than duplicating subscription logic.
• Card management: Store only tokens; support updating the default card and surface failure states from the gateway.
• Wrap the facade: Hide Billing::… behind your own BillingService/repository so you can mock it in tests and swap gateways (or the entire package) later without touching controllers.
• Testing: Use gateway test keys and a null/fake driver if available; otherwise inject your wrapper and assert on recorded calls instead of hitting Stripe.

Gotchas and Tips

• Laravel 4 only. Last release was 2017; there is no Laravel 5+ support. Expect Illuminate 4.x constraints and old PHP idioms — check compatibility before pulling it in.
• Config location is L4-style: published package config lives under app/config/packages/mmanos/laravel-billing/, not the L5+ config/ directory. Don't copy L5 instructions.
• Stripe API drift: The package predates Sources/PaymentMethods and Idempotency-Key conventions. Code written for card tokens may fail against a modern Stripe account unless you pin an appropriate API version — test subscribe, charge, and cancel against the current API early.
• Webhooks, not return values: A successful subscribe() call does not mean the renewal succeeded. Failed payments happen out of band; without webhooks your local state silently drifts.
• Idempotency: Gateway webhooks retry. Deduplicate on the event ID or you will double-charge or double-cancel.
• Migrations: Verify what actually ran (php artisan migrate:status) — --package behavior differs across L4 versions, and the schema's unique indexes on gateway IDs matter.
• Debugging: The package can swallow gateway exceptions. Log raw webhook payloads and check app/storage/logs, plus enable gateway request logging in config.
• Extension points: Gateway drivers are configurable — a null/test driver or a custom driver is the cleanest seam. Models may be overridable via config, which is useful for adding scopes or accessors.
• Never trust client plan input and never store card data — tokens only.