packstub / filament-saas-starter
A multi-tenant SaaS starter kit for Laravel and Filament: sign-up, workspaces, team invitations, plans with limits and Stripe billing.
Package info
github.com/packstub/filament-saas-starter
Type:project
pkg:composer/packstub/filament-saas-starter
Fund package maintenance!
Requires
- php: ^8.3
- filament/filament: ^5.0
- laravel/cashier: ^16.10
- laravel/framework: ^13.17
- laravel/sanctum: ^4.5
- laravel/socialite: ^5.33
- laravel/tinker: ^3.0
- packstub/filament-account-switcher: ^4.4
- packstub/filament-features: ^1.1.1
- packstub/filament-teams: ^1.1
Requires (Dev)
- fakerphp/faker: ^1.23
- laravel/boost: ^2.10
- laravel/pail: ^1.2.5
- laravel/pao: ^1.0.6
- laravel/pint: ^1.27
- mockery/mockery: ^1.6
- nunomaduro/collision: ^8.6
- pestphp/pest: ^4.0
- pestphp/pest-plugin-laravel: ^4.0
- pestphp/pest-plugin-livewire: ^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 19:47:41 UTC
README
A starting point for a multi-tenant SaaS on Laravel 13 and Filament 5: people sign up, get a workspace, invite their team, and pay for a plan that sets their limits. It is a regular Laravel app that you own and change from the first commit.
Free and open source, under the MIT license.
What you get in the first hour
- Sign-up and log-in: Filament's own auth pages, with e-mail verification, Google and GitHub sign-in, password reset, a profile page, two-factor authentication, a download of your data and account deletion.
- Workspaces: every sign-up gets one, with a Get started checklist on its dashboard; a person can belong to several, and everything in the panel is scoped to the current one.
- Team members: invitations by e-mail or link, the roles Owner, Admin and Member, and seats counted against the plan.
- Plans and limits: Free, Pro and Business in one config file, a Your plan page with usage, and overrides for a single workspace.
- Billing: Stripe Checkout and the customer portal through Laravel Cashier, monthly and yearly prices, a free trial and optional per-seat pricing, with a webhook that puts the workspace on the plan it pays for.
- An API: API tokens per workspace with abilities and expiry, and a versioned REST API for projects that respects the plan's limits.
- Audit log: who joined, left, changed role, was invited or took over a workspace, and every plan change, on an Activity page for owners and admins.
- Revenue metrics: MRR, paying subscriptions, trials, churn, sign-ups and plans on the admin dashboard, read from your own database.
- Support logins: an admin panel where you sign in as a customer to see what they see, with a log of every switch and every workspace's activity.
- One complete example: Projects, scoped to the workspace, guarded by a policy and counted against a plan limit.
- A home page: a landing page with features, pricing read from your plans, a FAQ, Terms and Privacy placeholders, and the meta tags, sitemap and robots.txt search engines look for.
- Tests: a Pest suite over all of the above, and GitHub Actions to run it.
It is built from Packstub's free plugins Filament Teams, Filament Features and Filament Account Switcher, together with Laravel Cashier and Filament's built-in tenancy.
Requirements
| Version | |
|---|---|
| PHP | 8.3 or newer |
| Laravel | 13 |
| Filament | 5 |
| Node | 20.19 or newer, to build the home page's CSS |
The database is SQLite out of the box. For MySQL or PostgreSQL, change DB_CONNECTION in .env.
composer.json pins config.platform.php to 8.3.0, so the lock file installs on PHP 8.3 whatever version you develop on. While it is there, Composer resolves every package as if you ran PHP 8.3, so a package that needs PHP 8.4 will not install. Once you know where the app will run, raise it to your server's PHP version, or remove it:
composer config --unset platform.php composer update --lock
Install
With the Laravel installer:
laravel new my-app --using=packstub/filament-saas-starter
That creates the project, migrates an SQLite database and seeds the demo accounts below.
Or click Use this template on GitHub (or clone the repository), then:
composer install
cp .env.example .env
php artisan key:generate
npm install && npm run build
php artisan migrate --seed
php artisan storage:link
composer setup runs those steps in one go.
Serve it with Laravel Herd or composer dev, and sign in:
| Sign in at | Password | Who | |
|---|---|---|---|
/app |
demo@example.com |
password |
Owner of the Acme workspace, on the Pro plan |
/app |
member@example.com |
password |
Member of Acme |
/admin |
admin@example.com |
password |
Admin: users, workspaces, support logins |
In the local environment the login pages also show the three accounts as one-click buttons.
Or open /app/register and sign up as a new customer. The verification e-mail goes to storage/logs/laravel.log (MAIL_MAILER=log), and its link opens the panel. .env.example sets QUEUE_CONNECTION=sync, so that e-mail is sent without a queue worker. In production, use a real queue.
When you are done with the demo, remove the three demo accounts: first take their e-mail addresses out of app/Support/SupportLogins.php, then empty database/seeders/DatabaseSeeder.php. The seeder skips the demo accounts when APP_ENV is production. The one-click logins exist only while APP_ENV is local, so never deploy with APP_ENV set to local.
A tour
The app has two Filament panels:
/app/{workspace}is what your customers use. It is defined inapp/Providers/Filament/AppPanelProvider.php, and its pages and resources live inapp/Filament/App./adminis your back office. It is defined inapp/Providers/Filament/AdminPanelProvider.php, with its resources inapp/Filament/Admin.
The public site around them (the home page, Terms, Privacy) is described in The home page.
The home page
/ is a landing page for the example product: a hero, a feature list, pricing, a FAQ and a call to action. It is plain Blade and Tailwind (resources/views/site, built by npm run build), follows the visitor's light or dark mode, and works without JavaScript. Rewrite the copy for your product; the parts below keep themselves up to date.
- Pricing is generated by
app/Support/Pricing.phpfrom the plans inconfig/packstub-features.php(names, descriptions, what each includes) and the amounts inconfig/billing.php. The Monthly / Yearly switch appears once a plan has a yearly price, and the free trial is mentioned whileBILLING_TRIAL_DAYSis above 0. Once Stripe prices are set, a plan shows only the intervals it is sold at, as on the Billing page; before any is set, every amount shows, so a fresh copy looks complete. Every button leads to sign-up; people pick a paid plan from the Billing page. config/site.phpholds the tagline, the meta description, the company name and contact address on the legal pages and in the footer, and an optional X/Twitter handle (SITE_*in.env).- Every URL search engines keep (the canonical URL,
og:url, the sitemap and robots.txt'sSitemap:line) is built onAPP_URLbyapp/Support/SiteUrl.php, never on the host a request came in on, so setAPP_URLto the public address, withhttps://. Behind a load balancer or a CDN that terminates TLS, also trust its proxy ($middleware->trustProxies(...)inbootstrap/app.php), and consider$middleware->trustHosts()to refuse other hosts altogether. - Meta tags live in
resources/views/components/site/layout.blade.php: title, description, canonical URL, Open Graph and Twitter cards. Put a 1200×630public/images/og.pngthere and link previews show it. /sitemap.xmllists the public pages (the home page, and Terms and Privacy once they are your own) and/robots.txtkeeps search engines out of/adminand the panel, apart from the log-in and sign-up pages. Outside production, robots.txt asks them to stay away altogether, so a staging copy is never indexed. Both are routes inroutes/web.php; add a new page's route name to the sitemap there.- Terms (
/terms) and Privacy (/privacy) are placeholders with a "Replace with your own" notice and anoindextag, and stay out of the sitemap. Write your own (they are needed before Stripe takes payments), then setSITE_LEGAL_PLACEHOLDERS=false(legal_placeholdersinconfig/site.php): the notice andnoindexgo, and both pages join the sitemap.
Workspaces
A workspace is the tenant: the App\Models\Workspace model, with its slug in the URL. All workspaces share one database, and Filament scopes every resource in the app panel to the current one.
- Signing up creates the person's first workspace, named after them. The closure that does it is
personalTeams()inAppPanelProvider. - The panel opens once the new account's e-mail address is verified (
emailVerification()inAppPanelProvider,MustVerifyEmailonUser). Invitations are matched by e-mail address, so an address has to be verified before it counts. A new address typed on the Profile page replaces the old one only after the link sent to it is followed (emailChangeVerification()). - New workspace in the workspace menu is
app/Filament/App/Pages/Tenancy/RegisterWorkspace.php. A person can create as many as they like, each starting on the Free plan. If your pricing needs a limit, add it there. Workspace::named()creates a workspace from a name: at most 60 characters, with a unique slug of at most 50, the suffix of a repeated name included.- A name that matches a page of the panel gets a suffix too: "New" becomes
new-x7k2, because/app/newis the New workspace page.Workspace::reservedSlugs()reads those words from the panel's routes, so a page or plugin you add later is covered. - Workspace settings is
EditWorkspace.phpnext to it, open to owners and admins throughapp/Policies/WorkspacePolicy.php. It holds the workspace's name and its Logo, shown in the workspace menu and at the top of the workspace's e-mails. See Uploaded files. - Delete workspace, at the bottom of Workspace settings, is for owners only (
WorkspacePolicy::delete()), never during a support login, and asks for the workspace's name. It runs$workspace->delete(): the Stripe subscription is cancelled first, then the projects, members, invitations, subscription rows and overrides go in one transaction. If Stripe refuses, nothing is deleted and the owner is told. Afterwards the panel opens another of their workspaces, or the New workspace page. - Get started, on the dashboard of a new workspace (
app/Filament/App/Widgets/GettingStarted.php), shows owners and admins four steps: invite a teammate, create a first project, choose a plan, turn on two-factor authentication. Each one is worked out from what is really there (members and invitations, projects, a subscription or a paid plan, the person's authenticator app), so it ticks itself off. The checklist goes once every step is done, or when someone clicks Dismiss, which hides it for the whole workspace (workspaces.onboarding_dismissed_at). Change the steps inGettingStarted::steps(). User::getDefaultTenant()picks the workspace a person lands in after signing in.
Accounts and security
- Passwords follow
Password::defaults()inapp/Providers/AppServiceProvider.php, on the sign-up, password reset and profile pages: at least 12 characters and not found in known data leaks in production, at least 8 elsewhere so the demo accounts can keeppassword. - Two-factor authentication is Filament's own, with an authenticator app and recovery codes. Customers switch it on from their Profile page. The admin panel requires it: an admin without it is sent to set it up before any page opens. In the local environment
/adminskips that step, so the demo admin gets in with one click. - The secret and the recovery codes are stored encrypted in two columns of the
userstable. - Download your data, on the Profile page, gives a person one JSON file with everything the app holds about them: their account, the workspaces they are in and their role, their notifications, and every support login into their account. Export workspace data, in Workspace settings, does the same for a workspace, for owners only (
WorkspacePolicy::export()): members, invitations, subscriptions, overrides and projects. Both come fromapp/Support/DataExport.phpand are plain GET downloads (/exports/me,/exports/workspaces/{slug}, inapp/Http/Controllers) streamed to the browser as they are read, so a workspace with many projects never sits in memory whole. The buttons link there rather than returning the file from a Filament action, which Livewire would buffer whole. A table you add for a workspace belongs inDataExport::forWorkspace()too. - Delete account is at the bottom of the Profile page (
app/Filament/App/Pages/Auth/EditProfile.php), behind the person's password.User::deleteAccount()deletes every workspace where they are the only member (cancelling its subscription first) and takes them out of the others. Someone who is the only owner of a workspace others still use is asked to hand it over under Members (Transfer ownership) or delete it first, so no workspace is left without an owner. The button is hidden during a support login. Filament Account Switcher's own log loses the support logins into a deleted account (itsaccount_switchesrows go with the user); the workspaces' audit logs keep what support did, under "Deleted user". A module that keeps something about a person removes it in a listener ofApp\Events\AccountDeleting, dispatched inside the same transaction. - Google and GitHub sign-in (Laravel Socialite) turn on once their keys are in
.env; until then no button shows. See Signing in with Google and GitHub. - Profile picture: on the Profile page, shown in the user menu instead of the initials. See Uploaded files.
- Strict models: outside production,
Model::shouldBeStrict()turns a lazy-loaded relation (an N+1 query), a missing attribute and a field left out ofFillableinto an error, so you find them while developing.
Uploaded files
Workspace logos and profile pictures are Filament file uploads, set up in config/uploads.php and app/Support/Uploads.php:
- Where: the
publicdisk by default (storage/app/public, linked intopublic/byphp artisan storage:link, whichcomposer setupruns). SetUPLOADS_DISK=s3and theAWS_*variables for an S3 or S3-compatible bucket, aftercomposer require league/flysystem-aws-s3-v3 "^3.0". Files are stored withpublicvisibility (UPLOADS_VISIBILITY); a bucket without per-file ACLs needs a public-read policy. On Laravel Cloud, attach a public bucket namedpublic(the guide). With several servers or replicas the default disk must be a shared bucket too, for Livewire's temporary uploads. - What: PNG, JPEG or WebP, up to
UPLOADS_MAX_SIZEkilobytes (1024 by default). No SVG: a picture people upload is served from your domain, and an SVG can carry scripts. - Who owns it: every file sits in its owner's folder,
workspaces/{id}/…orusers/{id}/…. The models refuse a path outside it (workspaces.logo_path,users.avatar_path), so nobody can point their workspace at another one's file, and a replaced logo or picture is deleted from the disk. - Deleting:
app/Listeners/DeleteWorkspaceFiles.phpandDeleteAccountFiles.phpremove the owner's whole folder when the workspace or the account is deleted, once the deletion is committed; a deletion that fails keeps the files. A file your own code stores for a workspace goes underUploads::workspaceDirectory($workspace)and is removed with it for free. - Public by link: anyone with a file's URL can open it. Keep files that must stay private on a private disk and hand them out with
Storage::temporaryUrl().
E-mails
Every e-mail the app sends, Filament's verification and password reset included, uses one layout: resources/views/vendor/mail/html/message.blade.php with the saas theme (html/themes/saas.css, Laravel's default in the panel's Indigo; markdown in config/mail.php). The top shows APP_NAME, or the workspace's name and Logo when the e-mail is about a workspace; the bottom shows SITE_COMPANY and SITE_CONTACT_EMAIL. Change the colours in the theme, the wording in the views. Names people choose (a workspace's, a person's) appear in these e-mails, so AppServiceProvider turns on Markdown::withSecuredEncoding(): Markdown inside a {{ }} is printed as text, and a workspace called [Verify](https://…) never becomes a link. Keep links and other Markdown in the view, outside {{ }}.
| Sent to | From | |
|---|---|---|
| Invitation | The invited address | Filament Teams, with the workspace's logo (resources/views/vendor/packstub-teams/mail/invitation.blade.php) |
| Payment failed | The workspace's owners, also in the bell menu | app/Notifications/PaymentFailed.php, when a Stripe webhook moves the subscription to past due (app/Listeners/NotifyOwnersOfFailedPayment.php), once per failure |
| Workspace deleted | Everyone who was in it, and who deleted it | app/Notifications/WorkspaceDeleted.php, after the deletion is committed (app/Listeners/SendWorkspaceDeletedNotice.php) |
| Account deleted | The deleted account's address | app/Notifications/AccountDeleted.php, after the deletion is committed (app/Listeners/SendAccountDeletedNotice.php) |
Receipts and invoices come from Stripe: turn them on in Stripe's customer e-mail settings, where you can also brand them. All of these are queued, so a worker must run in production. Preview one with php artisan tinker and (new App\Notifications\AccountDeleted('Ada'))->toMail(new Illuminate\Notifications\AnonymousNotifiable)->render(), or send them to Mailpit locally with MAIL_MAILER=smtp and MAIL_PORT=1025.
Languages
The kit's own text lives in lang/en and lang/es (Spanish, complete, as the example), behind __(). Filament is translated too; the pages of the Packstub plugins (Members, Invitations, Your plan) are English-only for now, and can be translated in lang/vendor (see the guide). A signed-in person picks a Language on the Profile page, which their e-mails follow too; a visitor picks one in the home page's footer. The languages on offer are locales in config/app.php. docs/translations.md shows where each text lives and how to add a language; TranslationsTest fails when a key is missing in one of them.
Signing in with Google and GitHub
Create an OAuth app with Google and/or GitHub, register the callback URL (https://my-app.test/auth/google/callback, https://my-app.test/auth/github/callback), and fill in .env:
GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... GITHUB_CLIENT_ID=... GITHUB_CLIENT_SECRET=...
A provider with both values set gets a Continue with … button under the sign-in and sign-up forms, and a Connect button in Connected accounts on the Profile page. The routes are in routes/web.php, the flow in app/Http/Controllers/Auth/SocialCallbackController.php, the enabled providers in app/Support/SocialLogin.php.
- An account already connected signs its user in. A new one whose e-mail address the provider has verified is connected to the user with that address, or creates a user (already verified, with their first workspace, or the workspace of the invitation that brought them).
- An address is linked only when both sides have verified it. If the provider has not verified it, or the account with that address has not been verified yet, nothing is linked and the person is asked to sign in with their password: otherwise whoever registered an address they do not own could take over the other account.
- Two-factor authentication is never skipped: someone with an authenticator app, and every admin, signs in with their password and code instead.
- Never during a support login: both routes refuse while an admin is signed in as someone, so support can never leave a Google or GitHub account of their own on a customer's account.
- Someone who signed up this way has no password (
users.passwordis nullable) until they choose one on the Profile page, which then does not ask for a current one. Disconnect is refused for their last way to sign in, and Delete account asks them to type their e-mail address instead of a password. - Connected accounts are in
social_accounts, a central table removed with the user, and in the personal data export. - A copy made before 1.0.0 (from the template between 2026-11-17 and the release) has
users.passwordasNOT NULL. To add Google and GitHub sign-up to it, add a migration with$table->string('password')->nullable()->change();onusers. A new project needs nothing: the column is nullable increate_users_table.
Members and invitations
The Members and Invitations pages come from Filament Teams. An owner or admin clicks Invite member, and the invited person gets an e-mail with a link to the sign-in page.
Someone with an account signs in there and joins. They also find the invitation under the bell icon. Someone new follows sign up for an account, finds the invited address filled in, and joins the workspace instead of getting one of their own.
- Roles and what each may do are in
config/packstub-teams.php: Owner can do everything, Admin manages members, settings and billing, Member works with the workspace's data. - Transfer ownership, on a member's row, is for owners: the member becomes the owner and the former owner stays on as an admin. Only an owner can delete the workspace or export its data, and Stripe's receipts go to the owner's address, so
app/Listeners/UpdateStripeBillingContact.phpqueuesapp/Jobs/SyncStripeCustomer.phpto update the Stripe customer after a transfer (by the workspace's id, like the seat sync). - Check a role anywhere with
$user->hasTeamPermission($workspace, 'delete')or$user->canManageTeam($workspace). - Seats are members plus pending invitations, and their limit comes from the plan.
- Invitation e-mails go to the log locally (
MAIL_MAILER=log): the link is instorage/logs/laravel.log. They are queued (invitations.mail.queueinconfig/packstub-teams.php), which withQUEUE_CONNECTION=syncstill means sent right away.
Read more in the Filament Teams docs.
Plans and limits
Plans and the features they include are defined once, in config/packstub-features.php:
| Plan | Projects | Seats | API access | Priority support |
|---|---|---|---|---|
| Free | 3 | 2 | ||
| Pro | 50 | 10 | Included | |
| Business | Unlimited | Unlimited | Included | Included |
A workspace's plan is its plan column. Filament Features reads it and answers the questions your code asks:
use Packstub\Features\Facades\Features; Features::limit('projects'); // 50, or null for unlimited Features::canUse('projects'); // is there room for one more? Features::active('priority_support'); // is the feature included?
app/Support/Plans.phptells Features how much of each limit a workspace has used, and points Upgrade to the Billing page.- Your plan in the
apppanel shows the workspace its limits and usage. - Feature flags and Feature overrides in
/adminturn a feature off everywhere or give one workspace more than its plan, with an optional end date. - Change plan on a workspace in
/adminputs it on a plan without a subscription.
To add a limit, define the feature in the config file, give each plan a value, and add a usage() line in Plans.php. Read more in the Filament Features docs.
Billing with Stripe
The Billing page (app/Filament/App/Pages/Billing.php) shows the plans to a workspace's owners and admins. The workspace is the Stripe customer, so one subscription covers all its members.
The app runs without a Stripe account: the Billing page then lists the .env keys that are still missing, and every workspace keeps its plan. To turn billing on:
-
In the Stripe dashboard, in test mode, create a product for Pro and one for Business, each with a monthly recurring price and, if you sell it yearly, a yearly one.
-
Fill in
.env:STRIPE_KEY=pk_test_... STRIPE_SECRET=sk_test_... STRIPE_PRICE_PRO_MONTHLY=price_... STRIPE_PRICE_PRO_YEARLY=price_... STRIPE_PRICE_BUSINESS_MONTHLY=price_... STRIPE_PRICE_BUSINESS_YEARLY=price_...
Leave a yearly price empty to sell that plan monthly only. In a copy made before yearly prices the keys were
STRIPE_PRICE_PROandSTRIPE_PRICE_BUSINESS; they are still read as the monthly prices, but rename them. -
Forward Stripe's webhooks to your machine with the Stripe CLI, and copy the signing secret it prints into
STRIPE_WEBHOOK_SECRET:stripe listen --forward-to https://my-app.test/stripe/webhook
-
Turn on the customer portal in Stripe, so customers can update their card and cancel.
In production, php artisan cashier:webhook creates the webhook endpoint in Stripe; its signing secret goes into STRIPE_WEBHOOK_SECRET.
How a payment becomes a plan:
- A plan's button opens Stripe Checkout for the price in
config/billing.php. A workspace that already pays gets Switch to instead, which moves its subscription to the other price. - A workspace's first subscription starts with a free trial: 14 days, set by
BILLING_TRIAL_DAYS(trial_daysinconfig/billing.php, 0 turns it off). Checkout still takes the card, so the plan carries on when the trial ends; the Billing page and the dashboard say when that is. A workspace that has had a subscription before pays from the first day. The trial is per workspace, so a new workspace gets one too;config/billing.phpsays how to make it one per person if that matters to you. If the trial ends without a payment, the webhook puts the workspace back on the Free plan. Should Stripe pause the subscription instead (a trial whose card was removed), the Billing page asks for a card under Manage billing and offers Resume subscription, which bills from that day. - Monthly and Yearly above the plans switch the prices the cards show, once any plan has a yearly price. Both prices of a plan map back to it, so a yearly subscriber gets the same limits as a monthly one, and a monthly subscriber can move to yearly billing on the same plan.
- Stripe calls
/stripe/webhook. Cashier stores the subscription, thenapp/Listeners/SyncWorkspacePlanFromStripe.phpputs the workspace on the plan of that price. - When the subscription ends, the same listener puts the workspace back on the Free plan. Its members and projects stay, but inviting and creating stop at the Free limits. The same happens when you delete the customer in Stripe.
- While Stripe retries a failed payment (
past_due), the workspace keeps its plan. The Billing page then shows "Your last payment did not go through" with Manage billing. It does not offer a new checkout while that subscription is still running. - A switch that needs the card confirmed (3D Secure) continues on Cashier's payment page. So does a first payment left unfinished at Checkout: the Billing page shows "Your payment is not finished yet" with Complete payment.
- Manage billing opens Stripe's customer portal.
- Deleting a
Workspacecancels its Stripe subscription first (thedeletinghook on the model), so nothing keeps billing, then removes its projects, subscription rows and feature overrides. Owners do it from Workspace settings. - A subscription on a price that
config/billing.phpdoes not list (a price added in the Stripe dashboard, say) leaves the plan as it is and writes a warning to the log.
Per-seat pricing
Plans are flat by default: one price, whatever the number of members. To bill a plan per member instead, set 'per_seat' => true on it in config/billing.php, give it per-unit prices in Stripe ("$9 per seat"), and say so in its amount. Then:
- Checkout starts the subscription with one seat per member. Pending invitations hold a seat against the plan's limit but are billed only once accepted.
- When someone joins (an accepted invitation included) or leaves,
app/Listeners/SyncSeatQuantityWithStripe.phpqueuesapp/Jobs/SyncSeatQuantity.php, which sets the subscription's quantity to the number of members, and Stripe prorates the difference. The job runs once the membership is saved, so run a queue worker in production; a call Stripe refuses is reported and tried again. It carries the workspace's id only: Filament Teams' events hold wholeUsermodels, and a queued listener would write their password hashes and remember tokens into thejobstable. - Every subscription webhook queues the same job, so a change made in the Stripe dashboard or a failed update is put right; a Stripe error there never fails the webhook.
- Switching between a flat and a per-seat plan sets the quantity to match.
- Give a per-seat plan unlimited
seatsinconfig/packstub-features.php(or a cap you want), since every seat is paid for.
In production, set STRIPE_WEBHOOK_SECRET before taking payments. Cashier verifies a webhook's signature only when the secret is set. Until it is, the app refuses Stripe's webhooks with a 403 and an error in the log (app/Listeners/RefuseUnsignedStripeWebhooks.php), and the Billing page sells nothing.
The amounts people see ($29/mo, $290/yr) are text next to each price in config/billing.php. Keep them in step with your Stripe prices. Read more in the Laravel Cashier docs.
API tokens and the API
API tokens, in the app panel, lets owners and admins create tokens for their scripts and integrations: a name, what the token may do (read projects, create projects) and when it expires (30 days, 90 days, a year or never). The token is shown once, right after it is created; only its hash is stored. Revoke stops it at once. Creating and revoking are in the audit log. During a support login tokens can be revoked but not created, so support never leaves with access of its own.
- Tokens are Laravel Sanctum personal access tokens whose owner is the workspace, not a person (
HasApiTokensonWorkspace,App\Models\ApiToken). The table shows who created each token. That person saw it in full, so their tokens are revoked as soon as they are no longer an owner or admin: removed from the workspace, made a member, or gone with their account (app/Listeners/RevokeApiTokensOfFormerManagers.php, with an entry in the audit log). Tokens made by the people who still manage the workspace keep working. Deleting a workspace deletes its tokens. - The API lives in
routes/api.phpunder/api/v1, withapp/Http/Controllers/Api/V1/ProjectController.phpas the example: list (GET /api/v1/projects, paginated), show (GET /api/v1/projects/{id}) and create (POST /api/v1/projects). A request authenticates as the workspace ($request->user()is theWorkspace), so every query starts from it and another workspace's records are out of reach. - Each route names the ability it needs (
abilities:projects:read); add yours toApiToken::ABILITIESand they appear on the page. - The API is a plan feature,
api_accessinconfig/packstub-features.php(Pro and Business). On a plan without it the page offers an upgrade, and the API answers 403, also for tokens created before a downgrade (app/Http/Middleware/EnsureWorkspaceHasApiAccess.php). - Creating a project goes through
App\Actions\CreateProject, so the plan'sprojectslimit holds: the API answers 403 with the limit and anupgrade_url. - Each token may make 60 requests a minute (the
apirate limiter inAppServiceProvider). Errors are JSON, whatever the client asks for. - The API answers to tokens only, never to a signed-in browser session (
guardis empty inconfig/sanctum.php). - Expired tokens are deleted a day after they expire (
sanctum:prune-expired, scheduled daily).
curl https://my-app.test/api/v1/projects \ -H "Authorization: Bearer 1|..." -H "Accept: application/json" curl https://my-app.test/api/v1/projects \ -H "Authorization: Bearer 1|..." -H "Accept: application/json" \ -H "Content-Type: application/json" -d '{"name": "Website relaunch"}'
The personal_access_tokens table is central, like billing: a request names no workspace until its token has been read.
Audit log
Every workspace keeps a log of what happened in it: members who joined, left or changed role, invitations sent and accepted, ownership transfers, plan changes (from Stripe, from the admin panel or from the code), API tokens created and revoked, and the workspace's deletion. Activity, in the app panel, shows it to owners and admins, with a filter by kind. In /admin, Activity lists every workspace's entries, deleted workspaces included, with filters by kind, by workspace and for what happened during a support login; Activity on a row of Workspaces opens that workspace's entries.
app/Models/AuditEvent.phpis an entry, andAuditEvent::record($workspace, AuditEventType::…, [...])writes one. Its kinds, with their labels, colours and icons, areapp/Enums/AuditEventType.php.app/Listeners/RecordWorkspaceActivity.phpturns Filament Teams' membership events into entries;Workspace::changePlan()and the model'sdeletedhook write the plan changes and the deletion.- An entry names who did it, or "System" for a webhook or a command. During a support login it also names the admin behind it, so the customer's log shows "Ethan Park (support: Sam Carter)".
- People and workspaces are kept by id and by name as they were, with no foreign keys, so an entry still reads well after a workspace is deleted. When someone deletes their account,
AuditEvent::forget()replaces their name and e-mail address with "Deleted user" in every entry; what happened stays. Their entries are part of Download your data. Deleting a workspace removes its entries and writes one "Workspace deleted" entry, which stays for the back office. - The table is central, next to billing and the support-login log: the admin panel reads it across workspaces and it keeps the entry of a deleted workspace, so it stays on the main database if workspaces get databases of their own.
- Entries older than 365 days (
AUDIT_RETENTION_DAYS,config/audit.php) are removed bymodel:prune, scheduled daily inroutes/console.php. Entries hold names and e-mail addresses, so keep them no longer than your privacy policy says. - A workspace's entries are part of its data export.
To log something of your own, add a case to AuditEventType with its sentence in AuditEvent::description(), and call AuditEvent::record() where it happens.
Revenue metrics
The dashboard of /admin shows how the business is doing: monthly recurring revenue (and the year's worth), paying subscriptions, free trials, churn over the last 30 days, sign-ups and new workspaces per day, plan changes, MRR per plan and workspaces per plan. The widgets are in app/Filament/Admin/Widgets, the figures in app/Billing/RevenueMetrics.php.
- Everything is read from the app's own tables: Cashier's
subscriptions,users,workspacesand the audit log. Nothing asks Stripe, so the dashboard opens fast and works before you have a Stripe account. - A subscription's price becomes money through
unit_amountinconfig/billing.php(cents, inCASHIER_CURRENCY), next to theamountpeople see. Keep both in step with Stripe. A yearly price counts as a twelfth a month, and a per-seat plan once per seat. - MRR and Paying subscriptions count the same subscriptions:
activeorpast_due(Stripe is still retrying the payment), on a priceconfig/billing.phpsells, including one cancelled at the end of its period until that period ends. Trials (Stripe'strialing) are listed on their own and are not revenue yet. The sums are made per price in the database, so the dashboard reads one row per price, not one per subscription. - Churned is the subscriptions that ended in the last 30 days after paying at least once: a trial that ended without a payment is not churn, and a cancellation that takes effect later is not churn yet. The rate is the share of the subscriptions paying 30 days ago (started, past any trial, not ended) that have ended since; subscriptions that started within the window are left out of it.
- Each figure is cached for five minutes (
RevenueMetrics::CACHE_SECONDS), so a busy dashboard runs its queries once. - A price changed in Stripe without a matching
unit_amountchange shows the old amount here, and a subscription on a priceconfig/billing.phpdoes not list is left out of both MRR and the paying count. For accounting, Stripe's own reports remain the reference.
Support logins
In /admin, Users lists everyone with an account. Impersonate signs you in as that person and takes you to their workspace, under a banner that says who you are signed in as. Switch back returns you to the admin panel.
- Only users with
is_admincan open/admin(User::canAccessPanel()), and only with two-factor authentication set up. - Only admins can sign in as someone else, and never as another admin (
User::canImpersonate()andUser::canBeImpersonated()). - Every switch is written to the
account_switchestable, and what the admin does while signed in as someone is in the workspace's audit log under both names. - The plugin is set up once for both panels in
app/Support/SupportLogins.php.
Make your own account an admin from php artisan tinker:
App\Models\User::where('email', 'you@example.com')->update(['is_admin' => true]);
Read more in the Filament Account Switcher docs.
The Projects pattern
Projects are the example to copy for your own models. Seven files make a resource belong to a workspace and count against a plan:
database/migrations/workspace/holds the migrations of the tables a workspace owns. A table there has a ULID key and an indexedworkspace_idwithout a database foreign key; the folder's README says why.app/Models/Project.phphas aworkspace()relationship. Filament uses it to scope every query in the panel and to fill in the workspace on create.app/Enums/ProjectStatus.phpis thestatuscolumn as a backed enum. It carries its own label and colour (HasLabel,HasColor), so the select in the form and the badge in the table need no extra code.app/Policies/ProjectPolicy.phpdecides who may do what from the member's role, and allows creating only while the plan has room. It asksUser::canInWorkspace(), which looks the role up once per request however many rows the table shows, and again as soon as a membership or a role changes.app/Filament/App/Resources/Projects/Pages/ManageProjects.phpshows "3 of 50 projects on the Pro plan", and swaps New project for Upgrade for more projects at the limit.app/Actions/CreateProject.phpcreates a project, checking the limit once more under a lock per workspace, so two people saving at the same moment cannot pass it. Everything that makes a project goes through it.app/Support/Plans.phpcounts the workspace's projects for theprojectslimit.
For a new model:
- Put its migration in
database/migrations/workspace, with a ULID key and an indexedworkspace_id. - Add
HasUlidsand theworkspace()relationship to the model. - Delete its rows in
Workspace'sdeletinghook, and add them toDataExport::forWorkspace(). Code you would rather keep out of the model (a module's tables, say) listens toApp\Events\WorkspaceDeletinginstead: the hook dispatches it inside the same transaction, while the workspace's projects are still there. - Write the policy.
- Create the resource in
app/Filament/App/Resources. - Add a limit if the plan should cap it.
Tests
Run them with:
composer test
This checks the code style with Pint and runs the Pest suite. In tests/Feature:
HomePageTest: the home page links to sign-up and log-in, its pricing follows the billing config and the free trial, the meta tags, canonical and sitemap URLs onAPP_URLwhatever the request's host, the sitemap with and without the legal placeholders, robots.txt in and out of production, the Terms and Privacy placeholders and their switch.SignUpTest: signing up creates a workspace with the person as owner, the panel opens after e-mail verification, long names, a second workspace, guests and other people's workspaces stay closed.MailTest: the branded layout and theme on every e-mail, the workspace's name and logo on its invitation, the failed payment notice to owners only and once per failure, the deletion notices to members and to a deleted account, none after a rollback.TranslationsTest: every key and placeholder in every language, a person's language in the panel and their e-mails, the home page's language switch.UploadsTest: logos and profile pictures stored in their owner's folder and shown in the menus, size and type limits, a replaced file removed, never another workspace's or person's file, the folders removed when a workspace or an account is deleted (and kept when the deletion fails), the exports.DataExportTest: what the personal and the workspace exports hold and leave out, the download routes and who may use them.AccountTest: deleting an account with its password, what goes with it and what stays, the only owner of a shared workspace, support logins.AuthenticationTest: the password rules, signing in with and without an authenticator app, two-factor authentication required for the admin panel.WorkspaceTest: reserved slugs, workspace settings by role, deleting a workspace from its settings (owners only, the typed name, Stripe first) and what that removes.TableRulesTest: every table is either central (listed, with the reason) or a workspace's own one with its migration indatabase/migrations/workspace, a ULID key, an indexedworkspace_idand no foreign key to a central table; and a deleted workspace leaves no row behind in any table (rowsLeftOf()intests/Pest.php).PluginsTest: the optional plugins listed inapp/Filament/Plugins.phpare registered on their panel.DeletionEventsTest: the events a module listens to when a workspace or an account is deleted, inside the transaction, and never on the queue.OwnershipTest: transferring ownership from the Members page, owners only, what the new owner may do, the Stripe billing contact following.InvitationTest: inviting from the Members page, signing up through an invitation, accepting with an existing account, an unverified account that claims an invited address, expired invitations, the seat limit.ProjectLimitTest: projects stay in their workspace, creating stops at the plan's limit and resumes on a bigger plan, a smaller plan keeps what is there.ProjectAccessTest: what each role may do with a project, other workspaces' projects stay out of reach by URL and by action, and the list runs the same number of queries however long it is.BillingTest: subscription webhooks (created, updated, each Stripe status, a trial and its end, deleted, customer deleted) change the plan and the limits; signed and unsigned webhooks; unknown prices.QueuedJobsTest: queued jobs, stored by a real database queue, never hold a person's password hash, remember token, two-factor secret or e-mail address; a job for a deleted workspace is dropped.SeatBillingTest: per-seat plans: Checkout with a seat per member, the quantity following members who join, leave or accept an invitation, flat plans left alone, Stripe errors, a quantity put right by the next webhook.BillingPageTest: the Billing page by role, with and without Stripe keys, monthly and yearly prices, the free trial, Checkout, switching plans and intervals, the customer portal, a past-due subscription, a subscription paused after its trial and resumed, and a payment that needs confirming.AuditLogTest: what is recorded and by whom (a support login included), plan changes from Stripe and from the admin panel, a deleted workspace and deleted people, pruning, the Activity page by role and by workspace.OnboardingTest: the Get started steps worked out from real data, the checklist for owners and admins only, going away when done, dismissing it for one workspace and never another, members unable to dismiss it.SocialLoginTest: buttons only for providers with credentials, signing up and signing in, linking only verified addresses on both sides, two-factor accounts and admins refused, a failed provider, an invitation followed by a social sign-up, connecting and disconnecting on the Profile page (never the last way in), choosing a first password, deleting an account without one, the export.ApiTokenTest: the API stays inside the token's workspace (lists, by id, creating), validation, the plan's project limit, plans without API access, abilities, missing, wrong, revoked and expired tokens, no browser sessions, the rate limit per token; the API tokens page by role, creating a token shown once, revoking, other workspaces' tokens, the upgrade on the Free plan, deleting a workspace.RevenueMetricsTest: MRR from monthly, yearly and per-seat prices, what is left out (trials, ended, unknown prices), churn (trials that never paid, cancellations not over yet, the base at the start of the window), plans, sign-ups per day, plan changes, the cache, the dashboard for admins only, no calls to Stripe.SupportLoginTest: the admin panel is for admins, signing in as a customer and switching back, changing a plan by hand, the admin tables, the Activity of every workspace.AgentGuidelinesTest: every file, class and method thatAGENTS.mdand the guidelines in.ainame exists.SeederTestandScheduleTest: the demo data seeds once and never in production; the daily housekeeping (invitations, overrides, the audit log, expired API tokens) is scheduled.
tests/Unit/ArchTest.php holds the architecture tests: Pest's php, security and laravel presets and a few rules of the kit's own.
The webhook tests post Stripe's payloads to the app, and fakeStripe() in tests/Pest.php answers the calls the app makes to Stripe, so the suite needs no Stripe account. .github/workflows/tests.yml runs it on PHP 8.3, 8.4 and 8.5.
Coding agents
The kit is ready for Claude Code, Cursor, Codex and the other coding agents:
AGENTS.md(andCLAUDE.md, a link to it) maps the code and lists the conventions..ai/guidelinesexplains the parts an agent is most likely to get wrong: the architecture, the rules for a workspace's tables, billing, testing, how to add a resource, a plan limit or a module, and a list of what never to do..ai/skills/adding-a-workspace-resourcewalks an agent through a new kind of record from the migration to the tests.
Laravel Boost is installed as a dev dependency. Run it once and pick your agents:
php artisan boost:install
It adds Boost's MCP server (the database schema, read-only queries, the logs, a search of the Laravel docs for the versions you have installed), Laravel's own guidelines and skills, and copies the guidelines and skills from .ai into each agent's files. Your text in AGENTS.md stays; Boost writes inside its own <laravel-boost-guidelines> block. The files it generates for each agent (.mcp.json, .claude/skills, .agents/skills, opencode.json) are in .gitignore; commit boost.json if your team should share the same setup. After composer update, run php artisan boost:update. Edit the sources in .ai, never the copies.
Optional modules
The kit leaves out what only some products need. Each of these is a short recipe in docs/modules: the composer require line, one line in app/Filament/Plugins.php, the migrations, a plan limit where one fits, what happens when a workspace or an account is deleted, a test to copy, and how to take it out again.
| Recipe | What it adds |
|---|---|
| Themes with Nitpick | Designed themes and an Appearance page in the app panel; owners set one for their workspace |
| Session Replay | Recordings of customer sessions, watched from /admin next to support logins |
| Workflows with Flow | Automations per workspace, with the number of workflows as a plan limit |
| Forms with Form Builder | Forms per workspace, hosted or embedded, with the number of forms as a plan limit |
| A Projects board with Kanban | The Projects resource as a board by status (a beta package) |
| An AI assistant with credits | A chat assistant per workspace, paid for by monthly AI credits from the plan (needs the next releases of the AI packages) |
Four things in the kit keep the recipes short: the plugin lists in app/Filament/Plugins.php, the App\Events\WorkspaceDeleting and App\Events\AccountDeleting events a module cleans up in, the one-value-per-line plans in config/packstub-features.php, and TableRulesTest, which makes each module say where its tables live.
Deploying
The app needs a MySQL or PostgreSQL database, a queue worker, the scheduler and a mail provider in production, and a Stripe webhook once you sell plans. The guides in docs/deploy walk through each host:
- Laravel Cloud: build and deploy commands, a managed queue, the scheduler toggle, buckets for uploads, secrets, your domain and the live Stripe webhook.
- Your own server, with Forge, Ploi or by hand: the deploy script, a Supervisor worker (and when Horizon is worth it), the cron entry, Redis, files and backups.
- Environment variables: every value the app reads, and what it should be in production.
- Production checklist: what to check before the first customer, from
APP_DEBUGto two-factor authentication for every admin.
Going further
A database per workspace
One shared database is the simplest setup and the right one for most products. When a customer needs their data kept apart, or one database stops being enough, Filament Tenancy (paid) adopts the app as it is and lets you move a workspace to a shard or to a database of its own.
The kit is laid out for that move: what a workspace owns sits in database/migrations/workspace, with ULID keys and no foreign keys to the tables that stay central (users, workspaces, memberships, invitations, billing).
The steps, in the order you meet them:
-
PHP 8.4. Filament Tenancy needs PHP 8.4 or newer. The kit itself runs on 8.3.
-
Adopt. After
composer require packstub/filament-tenancy, runphp artisan tenancy:adopt "App\Models\Workspace". Every workspace becomes a tenant with the same table, ids andworkspace_userpivot. Adopting keeps all workspaces in the shared database; nothing moves yet. -
The
Workspacemodel. Both Filament Tenancy'sIsPackstubTenantand Filament Teams'HasTeamMembersdefineisOwnedBy(), so the command prints the new class declaration for you to paste. Add one line to it:use IsPackstubTenant { IsPackstubTenant::isOwnedBy insteadof HasTeamMembers; }
-
The
Usermodel. It getsHasPackstubTenants, which brings its owngetTenants(),canAccessTenant()andgetDefaultTenant(). SwapHasTeamMembershipsforHasTeamRoles, remove the kit'sgetDefaultTenant(), and add stancl/tenancy'sCentralConnectiontrait, so accounts are always read from the central database. The app's own code asks theTeamsfacade (Teams::ownersOf(),Teams::membersOf(),Teams::teamsOf()) instead of the traits' relations, so it keeps working. Two places name thejoinedTeams()relation: the tests, which can useTeams::teamsOf(), and the workspace count of the admin Users table (withCount('joinedTeams')inUserResource), which becomeswithCount('tenants'). -
Paths or subdomains. The kit serves workspaces under
/app/{workspace}. To keep that, set'identification' => 'path'and'route_prefix' => nullinconfig/packstub-tenancy.phpbefore you runphp artisan migrate. Without the second line, URLs become/app/teams/{workspace}. The default is a subdomain per workspace, which needs wildcard DNS and$workspace->ensureDefaultDomain()afterWorkspace::named(). -
The panel.
->tenant(),->tenantRegistration()and->tenantProfile()inAppPanelProvidermake way forTenancyPlugin::make(), which registers its own onboarding and profile pages. -
Moving a workspace. With a shard connection added (
shard_2here) and the migrations indatabase/migrations/workspacerun on it, check withphp artisan tenants:move acme --to=shard_2 --dry-run --exclude=subscriptions,audit_events, then run it without--dry-run. Always pass--exclude=subscriptions,audit_events: Cashier'ssubscriptionstable and the audit log carryworkspace_idbut stay central, where the webhooks write and the admin panel reads. -
Tables that stay central. Inside a moved workspace the default connection is the workspace's database, so everything central has to name its connection. The kit already does:
config/packstub-teams.phpandconfig/packstub-features.phpsetconnectiontoDB_CONNECTION, which is the connection Filament Tenancy treats as central. Filament Account Switcher's tables, notifications and Cashier's subscriptions follow theUserandWorkspacemodels, which are central. Give a central model of your own theCentralConnectiontrait too. -
Code outside a workspace's request. The admin panel, jobs and commands run on the central database. To read what a workspace owns there, run inside it:
$workspace->run(fn () => Project::count()). The usage counter inapp/Support/Plans.phpand thedeletinghook onWorkspaceare the two places in the kit that read projects.
Read Adopting an existing app and Database strategies before you start. The command prints every step it leaves to you.
Built and launched for you
XLITE builds and launches your SaaS for you, as the SaaS MVP package.
Security
If you discover a security issue, please e-mail security@packstub.dev instead of using the issue tracker.
License
The MIT License (MIT). See LICENSE.