Filament Tenancy Laravel Package

Technical Evaluation

Package: angelitosystems/filament-tenancy — multi-tenant SaaS plugin for Laravel + FilamentPHP Release under review: v1.0.4 (declared first stable release; prior 1.0.x were betas) Assessment basis: Release notes only — no source review, no Packagist metadata, no prior assessment on file.

Architecture fit

• Targets a stack we are already standardizing on (Laravel + FilamentPHP), so it slots into the admin-panel layer rather than introducing a parallel UI framework. That is the strongest argument in its favor.
• The tenancy model appears to be central database + per-tenant database, based on the documentation summary ("setup guides for central and tenant databases"). This is the heavier of the two common multi-tenancy patterns and dictates our provisioning, migration, and backup story from day one.
• The package owns the tenant boot process, user resolver, and middleware, which is exactly the code path where a defect becomes a cross-tenant data exposure. It is a high-blast-radius dependency, not a convenience library.
• PayPalSettingsResource shipping inside a tenancy plugin is scope creep. Billing-provider concerns should not be coupled to tenant resolution; this signals a product that is being shaped by one customer's requirements.

Integration feasibility

• Mechanically straightforward: Composer install, register a service provider / panel configuration, wire middleware into the Filament panel, run central and tenant migrations.
• Real effort is in our decisions the package does not make for us: tenant identification strategy (subdomain vs path vs header), central-vs-tenant user ownership, role/permission scoping, and what data lives centrally.
• No published support matrix for Laravel, PHP, or Filament major version. Filament has moved through breaking majors quickly; an unpinned or loosely pinned constraint is the most likely source of an upgrade collision.

Technical risk

• Vendor concentration: single named maintainer at a small Peruvian company, with support routed to a personal email and a WhatsApp number. Effectively a bus factor of one.
• Licensing ambiguity: the release is stamped "All rights reserved" with no OSS license cited. This may be a commercial/proprietary package. We cannot ship a dependency whose redistribution, modification, and indemnification terms are unknown — this is a procurement blocker, not a footnote.
• Release hygiene: the changelog link is compare/v1.0.4...v1.0.4 — a self-comparison, i.e. an empty diff. Combined with betas shipped as patch versions (1.0.0–1.0.3), semver discipline is not yet demonstrated.
• Stability signal: "more stable multi-tenant boot process" and "improved user resolver and middleware" in a stable release imply these were unreliable in beta. Stability is asserted, not evidenced — no test suite, CI status, or coverage claim appears anywhere.
• Opaque change surface: no breaking-change declaration, no migration notes, no deprecations listed. For a 1.0 stable gate, that omission is itself a finding.

Key questions (blocking before adoption)

1. What is the license and commercial model, and what are the support/indemnification terms?
2. Exact compatibility matrix: Laravel, PHP, and Filament versions — and the policy for tracking Filament majors?
3. Which tenancy pattern is implemented, and how is tenant context propagated to queues, scheduled jobs, cache, filesystem, sessions, and logs?
4. Is there an automated test suite (Pest/PHPUnit), and does it include isolation-negative tests (asserting Tenant A cannot read Tenant B)?
5. Has any third party performed a security review of the resolver/middleware path?
6. Can PayPalSettingsResource be disabled, or is it a hard dependency?
7. Is documentation versioned per release, or does the hosted site track main?
8. What is the upgrade/backport policy now that 1.0 is declared stable?

Integration Approach

Stack fit

• Good fit for greenfield SaaS panels built on Filament where we control the schema from day one.
• Poor fit for retrofitting an existing single-tenant application: the central/tenant database split is a data-migration project, and the package's resolver assumes it owns authentication context.

Migration path

• Recommended path: isolated spike, not incremental adoption. Stand up a throwaway two-tenant environment, run the documented central + tenant setup, and exercise the resolver with adversarial cases (user in Tenant A requesting Tenant B's panel, tenant deleted mid-session, tenant DB unreachable).
• The beta→1.0 step is a one-way door for anyone already on 1.0.x betas: the notes claim consolidation and finalization but publish no upgrade instructions. Treat any existing beta installation as requiring a full re-validation, not a patch bump.
• Sequenced behind licence clearance. Do not invest integration effort into a package whose distribution terms are unresolved.

Compatibility

• Unverified and must be pinned explicitly in composer.json once known. Our standing rule should be: exact-minor pin plus a documented re-validation task on every Filament major.
• Filament navigation and translation changes in this release are low-risk but do touch panel rendering — expect visual regressions on upgrade, and budget for them.

Sequencing

1. Licence and commercial-terms review (legal).
2. Source read of resolver + middleware + migration generators (engineering), including a check for raw where tenant_id vs global scopes.
3. Two-tenant spike with isolation-negative tests.
4. Only then: architecture decision on central/tenant data boundaries.
5. Pilot on one bounded internal project before any customer-facing surface.

Operational Impact

Maintenance

• We inherit the maintenance burden of a dependency with a single upstream maintainer and no visible release cadence beyond this one. Realistically we should plan to vendor/fork or wrap the resolver layer so a stalled upstream does not block our Filament upgrades.
• Filament's release tempo means this package will need frequent catch-up releases. If upstream lags, we either pin an old Filament (accumulating security debt) or patch the package ourselves.

Support

• Support channel is direct email/WhatsApp to an individual. No public issue tracker engagement, no SLA, no severity process is described. Suitable for a relationship-driven vendor engagement; not suitable as our sole escalation path for a production tenant-isolation incident.
• Mitigation: contractually require a support SLA and a named secondary contact, or budget internal ownership of the code.

Scaling

• Per-tenant databases scale well for isolation and noisy-neighbour control but multiply operational surface: connection pooling, migration fan-out across N tenant DBs, per-tenant backup/restore, and cold-start cost for large tenant counts.
• Tenant boot runs on every request; "more stable boot process" is a performance-sensitive path. We need a benchmark with a realistic tenant count and a warm/cold cache comparison before committing.
• Queue and scheduler workers must carry tenant context. If the package only handles HTTP middleware, background processing isolation becomes our problem — a common and dangerous gap in this class of plugin.

Failure modes

• Cross-tenant data leakage — highest severity, lowest detectability. Arises from a missed scope, a stale tenant context on a long-lived worker, or cache keys not namespaced by tenant.
• Tenant resolution failure — user lands in wrong panel or default context when resolution silently falls back instead of failing closed. Watch specifically for fail-open behaviour.
• Migration drift — a tenant DB left behind after a partial migration fan-out; no described mechanism for detecting or repairing this.
• Upstream abandonment — package stops tracking Filament majors; we are stranded on a pinned stack.
• Scope creep — bundled resources like PayPal settings pulling unwanted config or dependencies into our panel.
• Empty-diff changelog — we cannot audit what changed between versions, which undermines incident forensics.

Ramp-up

• Engineers already fluent in Laravel + Filament will absorb the API in roughly a day; the cost is not learning the package but learning our tenancy boundaries, which the package does not define.
• Required onboarding artifacts we must author ourselves: tenant provisioning runbook, isolation test suite, migration fan-out procedure, and an incident playbook for suspected cross-tenant exposure.
• Estimate: one engineer, ~1–2 weeks to reach a defensible go/no-go, inclusive of the isolation spike and source read.

Recommendation Do not adopt as a core dependency on the strength of these notes alone. v1.0.4 is a credible signal that the package is maturing — a stable declaration plus real documentation is meaningful progress from beta — but the release publishes no compatibility matrix, no test evidence, no breaking-change statement, and a broken changelog link, while carrying unresolved licensing and single-maintainer risk. Proceed to a time-boxed evaluation gated on the eight questions above; treat a successful two-tenant isolation spike plus licence clearance as the minimum bar for pilot use.