Filament Tenancy Laravel Package

Getting Started

• Treat v1.0.4 as the first stable baseline for Filament Tenancy on Laravel + FilamentPHP. It is intended for production multi-tenant SaaS panels, so start by pinning this version and validating it in a staging app before rolling it into existing beta deployments.
• Look first at the official docs: https://docs-tenancy.angelitosystems.net/. Prioritize the setup guides for central and tenant databases, the user/role management examples, and the SaaS deployment tutorial.
• Confirm Laravel/Filament version compatibility directly from the package’s composer.json and docs, since the release notes do not list exact framework constraints.
• First practical use case: build a central admin panel for managing tenants, then a tenant-aware Filament panel where users, roles, and tenant-scoped resources are isolated per tenant. If relevant, use PayPalSettingsResource as the first tenant settings screen to validate resource registration, navigation, and tenancy-aware access.
• Install in a fresh Laravel app first, configure central and tenant connections, wire the package’s tenant middleware and user resolver, create a test tenant, and verify login/logout plus tenant switching before adding custom resources.

Implementation Patterns

• Use the package’s provided tenant boot process, middleware, and user resolver rather than writing custom tenant-resolution logic. v1.0.4 explicitly improves these areas, so leaning on the package’s flow reduces upgrade risk.
• Separate concerns clearly:
  • Central context: tenant management, global admin users, billing/configuration screens, and cross-tenant reporting.
  • Tenant context: tenant users, roles, tenant-owned Filament resources, and tenant-specific settings such as PayPalSettingsResource.
• Make Filament resources tenant-aware by relying on the package’s tenancy integration and resolved tenant context. Avoid hardcoding tenant IDs or connection names in resources, policies, or queries.
• Use documented user/role examples as the base for authentication and authorization. Test whether users are central, tenant-scoped, or shared before designing guards and policies.
• Keep tenant-aware configuration in the tenant context: database connections, cache prefixes, filesystem disks, queue connections, and mail settings where applicable. This is especially important for SaaS deployments.
• For PayPalSettingsResource, treat it as a settings/admin UI integration unless the docs confirm broader billing behavior. Validate credential handling and tenant scoping before exposing it to tenant admins.
• Add smoke tests for the core tenancy flow: tenant resolution, middleware order, user resolution, panel access, resource authorization, and tenant switch. These are the highest-risk areas after a stability-focused release.

Gotchas and Tips

• v1.0.4 is a stability release, but moving from a beta can still require config, migration, or service-provider updates. Re-read the docs and re-publish/compare config and migrations rather than assuming a drop-in upgrade.
• Middleware order matters. Tenant resolution must happen before tenant-aware auth, Filament panel bootstrapping, and tenant-scoped resource queries. If login or user resolution behaves oddly, inspect middleware ordering first.
• The release notes mention an improved user resolver and middleware. Test login, logout, password reset, remember-me, and session behavior in both central and tenant contexts.
• Avoid global caches, sessions, or queues leaking between tenants. Verify cache prefixes, session domains, queue payloads, and scheduled jobs include tenant context where necessary.
• PayPalSettingsResource and navigation/translation changes are worth a visual QA pass. Check custom Filament labels, navigation groups, and translations if you override package language files.
• Debug tenant issues by logging the resolved tenant ID and connection name at key points: middleware, panel access, model queries, and jobs. Confirm whether the code is running in central or tenant context before changing authorization logic.
• Because the release notes point to fully updated official documentation, use the docs as the source of truth for installation, deployment, and support. Pin v1.0.4 in production and review future releases for migration notes before upgrading.