Filament Starter Kit Laravel Package

Getting Started

This is a starter kit, not a drop-in Composer package — there is no composer require. You scaffold from it once, then live inside the app it generates.

1. Fork and clone the repository (or git clone and re-point the remote) into a fresh project directory.
2. Install dependencies:

   composer install
   cp .env.example .env
   php artisan key:generate
   npm install && npm run dev
   

3. Configure your database in .env, then run the seeders — they are not optional here. The seeders create the initial tenant, admin user, roles, and permissions. Without them you cannot log in.

   php artisan migrate --seed
   php artisan storage:link
   

4. Serve the app (php artisan serve or a Valet/Herd site) and log in at /admin (or whatever the panel path is) with the seeded credentials — check database/seeders/ for the exact email/password the kit uses; do not assume [email protected] unless you have confirmed it.

Where to look first, in order:

First realistic use case: get a working multi-tenant login where an admin can create a second tenant, assign a user to it, and confirm the user only sees that tenant's records. Once that loop works, you have validated the three pillars (tenancy, roles, exceptions) simultaneously.

Implementation Patterns

Tenancy is wired through the Panel, not through your models ad hoc. In the PanelProvider you will find something like:

->tenant(Team::class)
->tenantMiddleware([
    \Filament\Middleware\TenantMiddleware::class, // plus custom tenancy resolver
], isPersistent: true)

Day-to-day, this means:

• Every Eloquent model that is tenant-scoped must resolve tenancy consistently. Use a global scope or Filament's tenant scoping. Do not rely on developers remembering ->where('team_id', ...) in every query — add a trait or override getEloquentQuery() in resources.

• Adding a tenant-scoped resource is the most common daily task:

  php artisan make:filament-resource Invoice --tenant
  

  Then verify the generated resource respects the tenant relationship and that policies allow the right roles.

• Roles and permissions are almost certainly Spatie + Filament Shield (or a hand-rolled equivalent). The pattern is:

  1. Define permissions in a seeder (view_any_invoice, create_invoice, etc.).
  2. Generate policies (php artisan shield:generate) or write them manually.
  3. Assign permissions to roles, roles to users — ideally scoped per tenant via a team_id on model_has_roles.

  If the kit uses per-tenant roles, you must include the tenant in the role lookup context; otherwise a user's role in Tenant A leaks into Tenant B.

Exceptions: a ExceptionsResource reads from Laravel's failed_jobs table or a custom exceptions table. The daily pattern is to treat it as a read-only observability surface — do not build write workflows on it. Filter by date, user, tenant; use it as your first stop when a tenant reports a 500.

Workflow for extending the kit:

1. Add a migration and model (tenant-scoped, include team_id).
2. Generate the Filament resource with --tenant.
3. Generate or write the policy; register in the AuthServiceProvider if not auto-discovered.
4. Seed the new permissions; run php artisan permission:cache-reset (or shield:generate --all).
5. Verify with a non-super-admin user in a second tenant — this is the step people skip.

Integration tip: keep a SuperAdmin (or panel_user) role that bypasses tenancy (often via canAccessTenant() returning true). Filament resolves this through ->tenant(..., isScoped: true) or via a custom canAccessPanel — confirm which the kit uses before granting roles.

Gotchas and Tips

• Fork, don't expect updates. With a last release in March 2024 and 40 stars, upstream will not track Filament's major versions. Pin filament/filament and spatie/laravel-permission in composer.json and treat upgrades as deliberate migrations, not composer update runs.
• Seeder dependency is real. Fresh environments fail silently (login rejected, 403 everywhere) if seeders are skipped or if you change the tenancy model without re-seeding. Add a health check or a deploy step that seeds roles/permissions.
• Tenancy cache bugs are the most common complaint. Spatie's permission cache is not tenant-aware. After changing roles or permissions, php artisan permission:cache-reset — schedule this or clear in a deploy hook. Permission changes that "don't take effect" are almost always cache.
• Middleware order matters. If your tenancy middleware runs after auth but before permission, you get 403 instead of 404 for cross-tenant access (or vice versa). Document the intended order in the PanelProvider and don't reorder casually.
• Exception logging should be redacted. Check whether the exception resource dumps request payloads or session data. In production, either gate the resource behind a super-admin-only ability or redact before storage. A shared exception dashboard across tenants is a data-leak risk.
• storage:link and npm run build are the two steps that break "it works locally but not in staging." Include both in your deploy pipeline; the kit's package.json may target Vite 5, which does not match a stale CI image.
• Debug tenancy with php artisan tinker: check auth()->user()->getTenants() (or ->teams) and Filament::getTenant() while impersonating a real user in the target tenant. Impersonation plugins (if present) are the fastest way to reproduce tenant bugs.
• Extension points worth documenting for your team: the PanelProvider (panel config, plugins, navigation), policies (authorization), a TenantScoped trait (query scoping), and the seeder files (role/permission schema). Everything else is meant to be edited in place — do not try to package it.

Bottom line: this kit gives you a legitimate head start on Filament multi-tenancy and RBAC, but it is a 2024 snapshot with a small maintainer footprint. Budget a half-day to audit version compatibility and the tenancy/permission cache behavior before putting it on a real multi-tenant workload, and write the tenancy-scoping conventions down the moment you fork it.