Tomato Saas Module Laravel Package

Product Decisions This Supports

• Build vs. buy the SaaS "undifferentiated middle." This package is a candidate answer to a recurring build-vs-buy question: do we hand-roll tenant resolution, plan catalogs, subscription state, and entitlement gating, or adopt scaffolding? It is the "adopt" (MIT, free) option for that layer only — it is explicitly not a billing system, a payments integration, or a customer-facing product surface.
• Monetization roadmap sequencing. It supports decisions about how we ship plans and tiers. Config-driven plan/feature definitions plus a single enforcement boundary mean pricing experiments — adding a tier, moving a feature between plans, grandfathering a cohort — become config and seed changes rather than engineering projects. That materially de-risks the roadmap item "introduce tiered pricing."
• Multi-tenant architecture direction. The migration schema is the de facto answer to whether we run shared-database-with-discriminator vs. schema-or-database-per-tenant. Committing to this module is committing to its tenancy model, so it should be evaluated as an architecture decision, not a library decision — with the security and operational consequences that implies.
• Back-office scoping. For a Filament-based internal admin, the bundled plan/tenant/subscription resources represent real CRUD surface we would otherwise spec, design, and build. That is a direct reduction in the back-office workstream's scope and estimate.
• Scope containment on the payments workstream. Because billing stays behind our own interface, this package does not decide our PSP, dunning, tax, or invoicing strategy. It supports the decision to keep those concerns out of the tenancy layer — a boundary worth stating explicitly in the PRD so it doesn't get re-litigated later.
• Risk framing for the tenancy bet. It makes the tradeoff legible to stakeholders: we are choosing a thin, single-maintainer foundation for a security-critical boundary, and we are buying it with our own review and test effort. That is a decision we can make deliberately rather than by default.
• What it does not decide: pricing strategy, customer segmentation, trial/upgrade flows, usage metering, reporting, and lifecycle communications. Those remain ours, and the package's thinness on billing means our roadmap for them stays fully in our hands.

When to Consider This Package

Consider it when all of the following hold:

• The target product is a greenfield or lightly customized Laravel app where tenancy does not yet exist. There is no incumbent tenant model to reconcile against — dual ownership of tenant identity is the failure mode that kills this integration.
• We are already on — or are willing to be on — the TomatoPHP/Filament admin stack. The admin UI is a large share of the shipped value; adopting the migrations while discarding the UI is the worst cost-to-benefit ratio available.
• The team is small and the alternative is 4–8 weeks of foundational work on tenancy, plans, and entitlements that is genuinely undifferentiated for our business.
• We accept pinning to the exact version and owning our own adversarial test suite around tenant isolation, because upstream has not published coverage we can rely on.
• Billing will be integrated through our own provider-agnostic service layer, not through the package.

Look elsewhere when:

• We already own a tenancy layer. Retrofitting this alongside existing tenant scoping creates two sources of truth for the highest-risk boundary in the product.
• Our admin surface is not Filament (Inertia/Vue, bespoke admin, API-only). Most of the shipped value evaporates and we inherit only dependency weight.
• We need mature, battle-tested multi-tenancy. Established alternatives (e.g., stancl/tenancy, spatie/laravel-multitenancy) have larger install bases, documented tenancy strategies, and years of production exposure. Multi-tenancy is a security boundary; a 1.0.0 with one star, zero dependents, and no changelog is not a foundation I would put customer data behind without a deliberate, resourced bet.
• We need billing depth — provider webhooks, proration, dunning, tax, invoicing. This module provides hooks, not implementations.
• Compliance or procurement requires vendor support, an SLA, or a security disclosure policy. Community-only, single-maintainer support means our incident response is bounded by our own ability to read the source.
• We need a dependable upgrade cadence. No documented release rhythm, no migration notes, no BC guarantees beyond the version number, and no activity since March 2024.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed Laravel package that supplies the plumbing for running a subscription SaaS — tenants, plans, subscriptions — with an admin screen attached. The pitch is not "buy this product"; it is "avoid spending a quarter reinventing tenancy and plan gating." The honest framing includes the caveats: it is a brand-new 1.0.0 with a single maintainer, one GitHub star, zero dependents, no changelog, and no published test coverage, last touched in March 2024. My recommendation is therefore a time-boxed evaluation spike, not an adoption decision: three to five days to install it on a throwaway branch and run adversarial tenant-isolation tests. If tenancy holds, the upside is several weeks of foundational engineering avoided. If it doesn't, we've spent a week and learned our tenancy requirements in detail — which we needed anyway. Do not schedule this against customer data until the spike passes and we own a test suite around it.

To engineering: This is infrastructure, not a feature. Our app owns the domain models and business logic; the package owns tenant resolution, the plan catalog, subscription state, and the entitlement records. If we adopt, we pin the exact version (no caret constraint — it touches tenant scoping and billing), mirror the repo internally, and require a code read of the migrations and the tenant-resolution middleware before sign-off, because the release notes document nothing. The specific risks we are underwriting: global-scope defects are cross-tenant data exposure, not merely "a bug"; queued jobs lose tenant context unless the tenant ID is serialized and re-bound; and Filament/Livewire upgrades have historically changed query behavior in ways that can silently disable global scopes. After any such upgrade, our adversarial tenancy tests run before deploy — that suite is the price of admission, and it is cheaper than the alternative we would have built ourselves.