Download the PHP package cleaniquecoders/laravel-billing without Composer

Laravel Billing

A gateway-agnostic subscription & invoicing engine for Laravel — with an optional Livewire + Flux billing UI. One package to maintain — payment gateways are an extension point (a contract), not separate packages. Ships a built-in local gateway so any app has working billing on day one, plus optional, publishable customer-facing pages (plans, subscription management, invoices, receipts) — ideal for demo, development, UAT, and testing.

Why this design

• One package, one repo. No per-gateway sub-packages. BayarCash, ToyyibPay, Chip, senangPay, Stripe… each app writes a small driver class implementing the PaymentGateway contract. The package never references a real gateway by name.
• Batteries included. A first-class LocalGateway driver (no real money) is the default, so a fresh app can run the full subscribe → activate → invoice flow immediately.
• Headless core, optional UI. Models, services, contract, events, manager — fully usable with no UI at all. Need billing pages fast? Enable the bundled Livewire + Flux UI (browse plans, subscribe, manage the subscription, list/inspect invoices, download invoice & receipt PDFs) behind your own auth middleware. Either way your app keeps control of routes and access.
• Tenancy optional. The bill target is polymorphic: attach Billable to User (single-tenant) or Team/Workspace/Organization (multi-tenant). The package does not care.
• Malaysia-friendly invoicing. MYR default, SST/SSM-aware invoice template, atomic sequential numbering — all configurable and neutral by default.

Installation

Publish the config and (if using the database plan store) the migrations:

Optionally publish the invoice/checkout views and the plan seeder:

A fresh install defaults to BILLING_GATEWAY=local, so demo/UAT works before any merchant account exists.

To use the optional billing UI, install Livewire and Flux in your app (the package guards on their presence, so this is only needed if you enable the UI):

Make a model billable

Any model becomes billable by implementing the Billable contract and using the HasSubscriptions trait.

HasSubscriptions provides billingEmail(), billingName() and billingAddress() defaults (override as needed) plus:

Plans — config and/or database

config('billing.plans') is always the canonical source. The store setting decides where reads come from:

• store = 'config' — Plan instances are built on the fly from the array. No plans table needed.
• store = 'database' — plans are read from the plans table; the publishable PlanSeeder hydrates it idempotently from config (updateOrCreate on tier).

Limits are an open map (seats, messages_per_month, api_calls, …) — your app declares which meters exist. A null limit means unlimited.

Subscribe flow

checkout() creates a pending (Incomplete) subscription, delegates to the active driver, and correlates the eventual webhook by externalId. With the local gateway:

• Approve on the dev-checkout page → a SubscriptionActivated event flows through the same code path a real gateway uses → subscription activates and an invoice is issued.
• Decline → the subscription stays Incomplete.
• Set BILLING_LOCAL_AUTO=true to auto-approve (great for CI/tests).

Webhooks (your app wires the route, the package does the work)

Billing::handle() replay-guards on providerEventId, locates the subscription by gateway_subscription_id/externalId, transitions status, calls IssueInvoice on activate/renew, and fires the matching event.

Write your own gateway

Implement the single extension point and register the driver class in config. That's the entire surface.

The manager resolves the class through the container, so constructor injection works. You can also register a driver at runtime:

Events

Listen to drive your own side effects (provision access, dunning, Slack notifications). The package itself only updates subscription/invoice state and issues invoices.

SubscriptionActivated · SubscriptionRenewed · SubscriptionCanceled · PaymentSucceeded · PaymentFailed · InvoiceIssued

Invoicing

Invoices use atomic, row-locked sequential numbering (INV-2026-000001) and are rendered to PDF from a brandless, SST/SSM-aware Blade template, stored via Laravel's Filesystem (disk configurable). Set seller details under config('billing.company'). Publish and override resources/views/vendor/billing/invoice-pdf.blade.php to brand it.

Billing UI (optional)

The package ships a Livewire + Flux UI that closes the full subscribe → pay → invoice → receipt loop. It is opt-in and scoped to the authenticated billable.

More screenshots and the full walkthrough: Billing UI docs.

Requires livewire/livewire and livewire/flux in your app. Enable and scope it in config('billing.routes'):

That registers:

The billable is resolved via config('billing.billable_resolver') (defaults to request()->user()); set it to scope billing to a Team/Workspace. Every query is constrained to that billable, and the download/receipt routes 403 on a foreign invoice. Publish laravel-billing-views to override the Flux markup.

Component ownership — package vs your app

UI: the package ships an optional Livewire + Flux billing UI (plans, subscription, invoices, receipts) plus the dev-only local checkout page. It is opt-in — disable billing.routes.enabled (or skip installing livewire/flux) and the package stays fully headless. Publish and override the views to brand them, or build your own pages against the same models and facade.

Documentation

Full documentation lives in docs/:

• Getting Started — install, make a model billable, define plans
• Architecture — domain models, gateways, webhooks, events
• Billing UI — pages, routes, invoices & receipts (with screenshots)
• Configuration — every config/billing.php key
• Development — workbench preview & testing
• Examples — full cycle & custom gateway

Testing

Preview the UI locally (Testbench workbench)

The package ships a Testbench workbench so you can click through the full subscribe → pay → invoice → receipt flow with the real Flux UI:

Open the root URL — it auto-logs in a demo billable and lands on /billing/plans. The workbench (workbench/, testbench.yaml) configures a demo plan matrix (config store), the local gateway with the dev "Approve" checkout page, and SST tax — mirroring what a host app sets in config/billing.php.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Nasrul Hazim Bin Mohamad
• All Contributors

License

The MIT License (MIT). Please see License File for more information.