DEV Community: yebor974

Laravel Filament Multi-Tenant Starter - Build your app fast

yebor974 — Fri, 26 Jun 2026 13:52:00 +0000

Building a SaaS with Laravel Filament? You need more than two panels. You need teams, invitations, tenant-aware permissions, and a member experience that works for multiple users within the same organization.

Laravel Filament Multi-Tenant Starter does it for you. Backend panel, tenant member panel, team-based multi-tenancy, invitation system, team roles. All wired up and ready to go with Laravel 13 and Filament PHP v5.

What you get

Two panels, two worlds

Backend panel for your admins, accessible via subdomain or path
Member panel for your users, tenant-aware, with team switching built in

Each panel has its own middleware, routing config, and permission scope.

Team-based multi-tenancy

Multi-tenancy is powered by a Team model. Each user can belong to multiple teams and switch between them directly from the member panel.

Users can belong to multiple teams simultaneously
Team switching built into the member panel
Each team has its own profile page (name), editable by Team Admins
Tenant-aware resources and access control throughout the member panel

Two-tier role system

Application roles secure the Filament panels:

Backend - access to the backend admin panel
Member - access to the member panel

Team roles govern what users can do inside their team:

Team_Admin - manages team members, sends invitations, edits team profile

All roles are pre-seeded and defined via enums, clean, extensible, no magic strings.

Complete invitation flow

For existing users:

Team Admin sends an invitation
User accepts
User is immediately attached to the team

For new users:

Team Admin sends an invitation
User receives an invitation email
User registers
User is automatically attached to the team and can access the panel immediately

Secure authentication

Email invitation system for backend and member users
First-login password setup enforced
Password renewal flow via Filament Renew Password
MFA with authenticator app support

Production infrastructure, included

Laravel Horizon - queue monitoring, backend-only access
Logs Viewer - backend-only access
Redis for queues and cache
Multi-stage Docker setup - PHP-FPM, Nginx, PostgreSQL, Redis, Horizon, scheduler, all wired with healthchecks

Developer experience

app/Filament/Shared - shared schemas between panels
app/Models/TeamUser - team membership with role scoping
app/Services/TeamUserService - team user logic cleanly extracted
Per-user timezone applied automatically everywhere
Strong password policy enforced globally
Light & Dark theme switch + empty custom theme scaffold
Database notifications (Filament native)
Fully localized - English by default
Laravel Debugbar, PHPStan, Laravel Pint, PestPHP included

Tech stack


Framework	Laravel 13
Admin panel	Filament PHP v5
Frontend	TALL Stack: Tailwind v4, Alpine, Livewire
Testing	Pest PHP v4
PHP	8.3+
Database	PostgreSQL or MySQL
Queue & cache	Redis + Laravel Horizon

Who is it for?

✅ SaaS applications with team-based access

✅ B2B platforms where each client is a team

✅ Project management tools

✅ Any app where users belong to organizations with different roles

✅ Add your own billing layer (Laravel Cashier, Paddle, LemonSqueezy)

Need a simpler setup without multi-tenancy? See the Multipanel Starter or the Backend Starter

Compare starter templates

Feature	Backend Starter	Multipanel Starter	Multi-Tenant Starter
Laravel 13 + Filament v5	✅	✅	✅
Backend Panel	✅	✅	✅
Member Panel	❌	✅	✅
Subdomain or Path Routing	✅	✅ (per panel)	✅ (per panel)
Email Invitation	✅	✅	✅
Public Registration	❌	✅	✅
First-login Password Renewal	✅	✅	✅
MFA (App authenticator)	✅	✅	✅
Roles & Permissions (Spatie)	✅	✅	✅
Team-based Multi-Tenancy	❌	❌	✅
Team Switching	❌	❌	✅
Team Invitations	❌	❌	✅
Team Profile Management	❌	❌	✅
Team Roles (Admin)	❌	❌	✅
Per-panel Permission Scope	✅	✅	✅
Per-user Timezone	✅	✅	✅
Logs Viewer	✅	✅	✅
Laravel Horizon	✅	✅	✅
Dark Mode	✅	✅	✅
Multi-language	✅	✅	✅
Docker Setup	✅	✅	✅
Use case	Internal tools	Full-stack app	SaaS, B2B platforms

Billing

This starter does not include a billing module. The Team model is designed to be extended. Add your Stripe customer ID, subscription status, or any billing-related fields directly to the Team model and TeamUser as needed.

How to install

Without Docker

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

Configure your .env, database, Redis, mail, and your panel access:

# Backend panel at backend.yourdomain.com
FILAMENT_PANELS_BACKEND_DOMAIN=backend.yourdomain.com
FILAMENT_PANELS_BACKEND_PATH=

# Or at yourdomain.com/backend
FILAMENT_PANELS_BACKEND_DOMAIN=
FILAMENT_PANELS_BACKEND_PATH=backend

# Member panel at member.yourdomain.com
FILAMENT_PANELS_MEMBER_DOMAIN=member.yourdomain.com
FILAMENT_PANELS_MEMBER_PATH=

# Or at yourdomain.com/member
FILAMENT_PANELS_MEMBER_DOMAIN=
FILAMENT_PANELS_MEMBER_PATH=member

Then run the setup command - migrations, roles & permissions, first backend user:

php artisan backend:setup

All panels are live.

With Docker (recommended)

A docker-compose.example.yaml is included with everything pre-configured: PHP-FPM, Nginx, PostgreSQL, Redis, Horizon, and the scheduler. A dedicated bootstrap service runs migrations automatically before the app starts.

For a deep dive into the Docker architecture:

👉 Production-Ready Docker Setup for Laravel Filament

👉 Production-Ready Docker Compose for Laravel Filament

cp docker-compose.example.yaml docker-compose.yaml
cp .env.docker.example .env
docker compose up -d --build
docker compose exec php-fpm php artisan backend:setup

Access your panels:

Backend: https://localhost:4443/backend
Member: https://localhost:4443/member

⚠️ Always use https:// - Nginx expects SSL on port 4443. ⚠️ Self-signed certificate warning in local dev is expected. Certificates are provided in docker/example/nginx/certs/.

For production, adapt the compose file and Nginx config to your own infrastructure. See the GitLab CI guide for a complete production pipeline.

Visual overview

Laravel Filament Multi Tenant Member Login

Laravel Filament Multi Tenant Member Sign up

Laravel Filament Multi Tenant Member Team Registration

Laravel Filament Multi Tenant Member Dashboard

Laravel Filament Multi Tenant Member Team Profile

Laravel Filament Multi Tenant Member Team Users List

Laravel Filament Multi Tenant Member Team User Invite

Laravel Filament Multi Tenant Member Team User Invitation Email

Laravel Filament Multi Tenant Member Team User Invitation On Login Page

Laravel Filament Multi Tenant Backend Dashboard

Laravel Filament Multi Tenant Backend Members List

Laravel Filament Multi Tenant Backend Teams List

Laravel Filament Multi Tenant Backend Teams Edit

Laravel Filament Multi Tenant Backend Teams List - Attach User

Laravel Filament Multi Tenant Backend Backend Users List

Get access

The Multi-Tenant Starter is included in the Member tier of Filament Mastery, along with the Backend Starter, the Multipanel Starter, all premium articles, and every future starter and guide.

Your membership grants you the right to use this starter on unlimited personal or client projects

Join Filament Mastery ->

Understanding Filament themes in v4/v5: from Colors to custom CSS

yebor974 — Fri, 26 Jun 2026 07:41:24 +0000

Filament provides a flexible theming system that lets you customize the look and feel of your admin panel. This guide covers how to create and apply custom themes for Filament v4/v5 with Tailwind CSS v4.

This is an updated version of an earlier guide written for Filament v3 and Tailwind v3. The overall approach is similar, but what the theme command generates and the CSS syntax have changed with Tailwind v4's CSS-first configuration. If you're still on Filament v3, the original guide is available here.

Setting primary colors for panels

Before touching the theme files, the simplest customization is setting your panel's color palette. This part hasn't changed: Filament still uses the Filament\Support\Colors\Color class.

Option 1: define colors per panel

In your panel provider:

use Filament\Support\Colors\Color;

public function panel(Panel $panel): Panel
{
    return $panel
        ->colors([
            'danger' => Color::Rose,
            'gray' => Color::Gray,
            'info' => Color::Blue,
            'primary' => Color::Indigo,
            'success' => Color::Emerald,
            'warning' => Color::Orange,
        ]);
}

Option 2: define colors globally

In AppServiceProvider, applied across all panels:

use Filament\Facades\Filament;
use Filament\Support\Colors\Color;

public function boot(): void
{
    Filament::defaultColors([
        'danger' => Color::Rose,
        'gray' => Color::Gray,
        'info' => Color::Blue,
        'primary' => Color::Indigo,
        'success' => Color::Emerald,
        'warning' => Color::Orange,
    ]);
}

When to stop here: if your goal is only to change branding colors, ->colors() is all you need. Create a custom theme only when you need structural UI changes, like repositioning elements, changing spacing, or styling parts of the interface that color tokens don't reach.

Generating the theme

The command itself hasn't changed:

php artisan make:filament-theme

You'll be prompted for a panel name (default: admin). What changed is what this command generates and does for you.

On a Tailwind v4 setup, running it for a member panel generates a theme.css scoped to that panel:

@import '../../../../vendor/filament/filament/resources/css/theme.css';

@source '../../../../app/Filament/Member/**/*';
@source '../../../../resources/views/filament/member/**/*';

Notice the @source paths point specifically to Member, not a generic Filament/**/*. Each panel gets its own scoped theme out of the box.

That's it: the generated file is intentionally minimal. If you want a dedicated place for CSS variables or light/dark overrides, you can add your own @layer base block:

@layer base {

    :root {

    }

    :root[class~="dark"] {

    }

}

The other change worth noting: in Filament v3, you had to manually add the theme to vite.config.js and register it with ->viteTheme() in your panel provider. In v4/v5, the command does both for you automatically. No manual wiring required.

A few things changed compared to Tailwind v3:

No more tailwind.config.js. Tailwind v4 no longer requires a tailwind.config.js file for basic theme customization. It moved to CSS-first configuration. There's nothing left to generate or maintain in a separate JS config file for the theme.

@source directives replace the old content array. Tailwind v4 scans these paths directly from CSS to know which files to look at for class usage, instead of declaring them in a JS config.

The generated file is intentionally minimal. Just the import and the @source paths for that panel. No boilerplate @layer base block is added automatically; that's something you add yourself if and when you need it, as shown above.

Adding your own directories to @source

The generated @source directives only cover Filament's own files. Your resources, components, or anything outside app/Filament won't be scanned by default. If you use Tailwind classes in Blade components, Livewire components, or custom views, you need to add those directories yourself:

@source '../../../../app/Filament/**/*';
@source '../../../../resources/views/filament/**/*';
@source '../../../../resources/views/components/**/*';
@source '../../../../resources/views/livewire/**/*';
@source '../../../../app/Livewire/**/*';

Forget to add a directory here, and Tailwind will purge classes it never saw being used, even if they're correctly written in your code. Rebuild with npm run build after adding new paths.

What gets registered automatically

Since the command handles registration for you, vite.config.js already includes the new theme after running make:filament-theme:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',
                'resources/css/filament/admin/theme.css',
                'resources/js/app.js',
            ],
            refresh: true,
        }),
        tailwindcss(),
    ],
});

And your panel provider already has the theme registered too:

->viteTheme('resources/css/filament/admin/theme.css')

Nothing left to wire up manually. Just run the command, and both files are updated for you.

Multiple panels, multiple themes

If your application has more than one panel, an admin panel and a member panel for example, each one gets its own theme file and is registered independently.

Run make:filament-theme once per panel:

php artisan make:filament-theme backend
php artisan make:filament-theme member

Each run automatically adds its theme to vite.config.js and registers it in the matching panel provider. You'll end up with both entries already in place:

laravel({
    input: [
        'resources/css/app.css',
        'resources/css/filament/backend/theme.css',
        'resources/css/filament/member/theme.css',
        'resources/js/app.js',
    ],
    refresh: true,
}),


// BackendPanelProvider
->id('backend')
->viteTheme('resources/css/filament/backend/theme.css')

// MemberPanelProvider
->id('member')
->viteTheme('resources/css/filament/member/theme.css')

Each theme.css is scoped to its own panel by default. The @source directives only point to that panel's files, and customizing one theme doesn't affect the other. This is how the Multipanel and Multi-Tenant starters are set up: two themes, generated empty and scoped, ready for each panel to be styled differently if needed.

Sharing one theme across panels: you don't have to generate a separate file per panel. If two panels should look identical, you can point both panel providers at the same theme file:

// BackendPanelProvider
->viteTheme('resources/css/filament/shared/theme.css')

// MemberPanelProvider
->viteTheme('resources/css/filament/shared/theme.css')

Just make sure the @source paths in that shared file cover both panels directories, since a single generated theme only scopes to the panel it was created for.

Reading Filament's hook classes

Once you start customizing beyond colors, you'll be targeting Filament's own CSS classes, the ones used in the sidebar example below and throughout the interface. They follow a consistent naming convention worth knowing:

fi is short for "Filament"
fi-ac is used for classes from the Actions package
fi-fo is used for classes from the Forms package
fi-in is used for classes from the Infolists package
fi-no is used for classes from the Notifications package
fi-sc is used for classes from the Schema package
fi-ta is used for classes from the Tables package
fi-wi is used for classes from the Widgets package
btn is short for "button"
col is short for "column"
ctn is short for "container"
wrp is short for "wrapper"

Once you know this pattern, hook class names become much easier to read without digging through Filament's source every time.

Finding hook classes in practice: the naming convention tells you what a class means once you've found it, but you'll still need to find it first. The fastest way:

Open your browser's dev tools on the panel you want to customize
Inspect the element you want to target
Look for classes starting with fi- in the inspector
Use that class in your theme's CSS

This is the most reliable way to target the exact element you're looking at, rather than guessing from the naming convention alone.

Customizing your theme

With the theme registered, you can now add your own styles directly in theme.css. Filament's hook classes, documented in the Filament docs, let you target specific parts of the interface.

Here's an example customizing the sidebar, the same idea as in the original v3 guide, adapted to the new file structure:

@import '../../../../vendor/filament/filament/resources/css/theme.css';

@source '../../../../app/Filament/**/*';
@source '../../../../resources/views/filament/**/*';

.fi-sidebar {
    @apply !bg-gray-500;

    .fi-sidebar-header {
        .fi-icon-btn-icon {
            @apply text-primary-500;
        }
    }

    .fi-sidebar-group-label, .fi-icon-btn-icon, .fi-sidebar-group-icon, .fi-sidebar-item-icon, .fi-sidebar-item-button, .fi-sidebar-item-label {
        @apply text-white;
    }

    .fi-sidebar-item-active {
        .fi-sidebar-item-button {
            @apply bg-primary-500;
        }
    }

    .fi-sidebar-item, .fi-sidebar-item-button {
        :hover {
            @apply hover:bg-primary-500;
        }
    }

    .fi-icon-btn {
        :hover {
            @apply hover:text-primary-500;
        }
    }

    .fi-sidebar-nav-groups {
        @apply gap-y-0;
    }
}

The @apply syntax and the hook classes themselves haven't changed. What changed is everything around them: how the theme is generated, how Tailwind scans your files, and how the build is configured.

Using CSS variables for reusable values

If you find yourself repeating the same color or value across multiple rules, defining a CSS variable in @layer base keeps things consistent and easier to update later:

@layer base {
    :root {
        --sidebar-bg: #1f2937;
    }

    :root[class~="dark"] {
        --sidebar-bg: #111827;
    }
}

Then reference it directly in your styles:

.fi-sidebar {
    background: var(--sidebar-bg);
}

This is especially useful for values you'll reuse in several places, or want to swap between light and dark mode without duplicating rules.

Run npm run build once you're done, and your custom theme is live.

Common mistakes when customizing Filament themes

A few things come up repeatedly when developers start working with Filament themes for the first time.

Creating a theme when ->colors() is enough. If the only goal is changing the primary color, buttons, and sidebar accents, ->colors() in the panel provider covers that without generating any files. A custom theme is only necessary for structural changes, targeting specific interface elements via hook classes, or using CSS variables for fine-grained control. Generating a theme file when it isn't needed just adds a build step and a file to maintain.

Forgetting to add custom Blade directories to @source. The generated theme only scans Filament's own directories by default. Any Tailwind classes used in custom Blade components, Livewire components, or views outside app/Filament won't be detected unless you explicitly add those paths. Tailwind silently purges the undetected classes, and the issue only shows up at build time when styles randomly stop working in production.

Styling internal Filament classes instead of hook classes. Filament's hook classes, prefixed with fi-, are the intended surface for CSS customization. Styling classes without the fi- prefix means targeting internal implementation details that can change between releases without notice. Filament's own documentation explicitly warns against this: if a hook class you need doesn't exist yet, the recommended path is to open a pull request to add it, not to target internal classes and accept the maintenance risk.

Overriding too much. The more CSS overrides added to a theme, the harder upgrades become. When Filament ships a new version, any structural change to the interface can break rules that were written against the old markup. Prefer color tokens, CSS variables, and targeted hook class overrides before rewriting large sections of the interface. A theme should adapt Filament to a brand, not turn Filament into a completely different application.

And of course, editing vendor files directly. Any change made inside vendor/filament is overwritten the next time composer update runs. If something in Filament's default theme needs to be overridden, the right place is the custom theme.css file, using hook classes to target the element. The vendor directory is never the right place.

Don't want to build a theme from scratch?

If building a custom Filament theme isn't where you want to spend your time, Filafly offers premium themes and plugins ready to drop into your panel.

Use code MASTERY15 for 15% off your purchase.

Discover Filafly themes →

Originally published on Filament Mastery

Extending Filament exports with Laravel Excel

yebor974 — Wed, 17 Jun 2026 15:49:47 +0000

Filament's export action is great. It's quick to set up, supports queued exports, includes column mapping, handles notifications, and keeps a history of generated files through the Export model. For most use cases, it's exactly what you need.

But I recently ran into a limitation that the native export couldn't solve.

When XLSX isn't really Excel

I was exporting financial data or measurements from a Filament table. The export worked. The file downloaded. Excel opened it without any issue.

The problem was that every amount was exported as text instead of a real numeric value.

For an accountant, that creates several problems immediately:

Excel formulas such as =SUM() don't work correctly
Selecting a range of cells doesn't display totals in Excel's status bar
Conditional formatting based on numeric values becomes unreliable
Additional manual cleanup is required before the file can be used

Technically the export contained the data. Practically, it wasn't usable.

The root cause is simple: Filament's export system is designed around CSV-style exports. That's perfect for many scenarios, but it doesn't expose the full spreadsheet capabilities offered by PhpSpreadsheet and Laravel Excel.

On top of that, I also had a second, completely different requirement: a yearly report with one worksheet per month, merged headers, borders, conditional formatting, and custom layouts. Not a table dump but a report.

Why not just use Laravel Excel directly?

Laravel Excel already solves all of these problems. It's built on PhpSpreadsheet and provides complete control over cell types, number formats, formulas, styling, and multiple worksheets.

The obvious solution would have been to abandon Filament's export action entirely and build custom exports from scratch. But that means losing everything Filament already provides:

Export modal and options form
Column mapping UI
Queue handling
Progress notifications
Download links
Export model history

I didn't want to rebuild all of that. I simply wanted a different file generator underneath.

The full article is available on Filament Mastery for free members - create a free account to access the complete code.

Adding a full docker setup to the Filament Mastery Starters

yebor974 — Fri, 29 May 2026 06:57:02 +0000

For a while, my starter kits didn't include any Docker configuration. The foundation was solid with auth, roles, MFA, Horizon, Logs Viewer, but the deployment side was left to whoever cloned the project.

That was a deliberate choice at first. Docker setups vary a lot depending on the infrastructure: some people use a reverse proxy, others have Cloudflare in front, some run on bare metal, others on managed platforms. I didn't want to ship something that would need to be ripped out immediately.

But over time I changed my mind. Here's why and what the process taught me.

The problem with "just configure it yourself"

Leaving deployment out of a starter kit sounds reasonable. In practice, it means every project starts with the same 4-6 hours of Docker work that never really changes.

Multi-stage Dockerfile. PHP-FPM config. Nginx with HTTPS. PostgreSQL and Redis wired up. Horizon and the scheduler running as proper services. Healthchecks everywhere so Docker knows when things are actually ready.

None of it is so complicated. But it's time-consuming, easy to get subtly wrong, and almost identical from one project to the next.

Once I admitted that, the question wasn't whether to include Docker, it was how to do it in a way that's actually useful without being too opinionated about production infrastructure.

What I ended up building

The setup I settled on covers the full local development stack:

A multi-stage Dockerfile : separate stages for Composer dependencies, Node assets, and the final PHP-FPM image. Keeps the production image lean.
Nginx with HTTP-to-HTTPS redirect and a self-signed certificate for local dev, already included, no setup needed.
PostgreSQL and Redis as services with proper healthchecks.
Horizon and the scheduler as dedicated services, not crammed into the main app container.
A bootstrap service that runs php artisan migrate --force before the app starts.

The Dockerfile uses three stages to keep the final image as lean as possible:

FROM php:8.4-fpm-alpine AS composer_builder
# Install extensions, run composer install
# ...

FROM node:24-alpine AS node_builder
# Install npm dependencies, build Vite assets
# ...

FROM php:8.4-fpm-alpine AS php_fpm
# Final image, only what's needed to run
# Copy vendor/ from composer_builder
# Copy public/build/ from node_builder
# ...

Each stage does one thing. The final image never contains Composer, Node, or dev dependencies.

The full Dockerfile architecture with extensions, non-root user, Xdebug for local dev, is covered here: Production-Ready Docker Setup for Laravel Filament.

The bootstrap service

Running migrations on deploy is one of those things that sounds simple until you've had a deployment fail because the app started before the database was ready.

The pattern I use is a dedicated bootstrap service that exits when migrations succeed. The app service depends on it, so the app simply doesn't start until migrations are done.

bootstrap:
  image: ${APP_IMAGE}:${APP_VERSION}
  command: php artisan migrate --force
  depends_on:
    db:
      condition: service_healthy
    # ...

app:
  image: ${APP_IMAGE}:${APP_VERSION}
  depends_on:
    bootstrap:
      condition: service_completed_successfully
    # ...

horizon:
  image: ${APP_IMAGE}:${APP_VERSION}
  command: php artisan horizon
  depends_on:
    bootstrap:
      condition: service_completed_successfully
    # ...

scheduler:
  image: ${APP_IMAGE}:${APP_VERSION}
  command: php artisan schedule:work
  # ...

No SSH. No manual commands. No "did someone run the migrations?" before going live.

A word of honesty on this pattern: it works well for single-instance deployments, one VPS, one app container. If you're running multiple replicas or need strict zero-downtime guarantees, this approach has limits. Multiple bootstrap services running simultaneously can conflict, and the app will be briefly unavailable during migration. In those cases, migrations should be handled at the CI/CD pipeline level, before containers are deployed. That's a topic worth a dedicated article, and it's on the roadmap.

The full compose setup, volumes, healthchecks, network config, restart policies, is covered in detail here: Production-Ready Docker Compose for Laravel Filament.

What I deliberately left out

I didn't include a production-ready Nginx config. Not because it's hard to write, but because production environments vary too much.

Some projects sit behind Traefik. Others use Cloudflare in front. Some have real Let's Encrypt certificates managed externally, others use internal PKI. Shipping a "production" Nginx config that works for one setup and silently breaks another isn't helpful.

What I do ship is a docker-compose.example.yaml, clearly labeled as a starting point, not a drop-in solution. The dev config is complete and ready to use. The production side is documented, commented, and deliberately left for the developer to adapt.

I think that's the right balance for a starter kit. Give people enough to be productive immediately, without making decisions that belong to them.

What this changes for the starters

Both the Backend Starter and the Multipanel Starter now include the full Docker setup.

Copy the repo, copy .env.example, define your app key, rundocker compose up -d --build, then php artisan backend:setup, and you have a running panel with auth, roles, MFA, Horizon, and Logs Viewer, all in one go.

It's a meaningful improvement over "configure Docker yourself." Not because Docker is complicated, but because those 4-6 hours are better spent on the actual project.

Both starters are available with the Filament Mastery membership.

As always, if something doesn't work the way you'd expect or you'd approach it differently, let me know in the comments.

Implement SAML SSO Authentication in Laravel Filament with Socialite

yebor974 — Wed, 20 May 2026 11:10:04 +0000

Single Sign-On (SSO) is a common requirement in enterprise applications.

When working with Laravel Filament in internal business environments, clients often want to authenticate users directly through:

Active Directory
Microsoft Entra ID (Azure AD)
Okta
Keycloak
Google Workspace

Instead of managing passwords inside your application.

In this article, we’ll build a clean SAML SSO integration using:

Laravel Socialite
The Socialite SAML2 provider

The goal is not only to make authentication work, but also to build a maintainable foundation for enterprise environments.

At the end of this article, you’ll have:

SAML authentication working inside Filament
A metadata endpoint for your Identity Provider
A dedicated authentication flow
A clean architecture ready for role synchronization

In the premium follow-up article, we’ll implement:

Active Directory group mapping
Spatie Permission synchronization
Production-ready role handling
Enterprise access control strategies

Installing the SAML2 Provider

First, install Laravel Socialite and the SAML2 provider:

composer require laravel/socialite
composer require socialiteproviders/saml2

You can then configure your SAML provider inside config/services.php.

Configuring the SAML Provider

Here is a simple SAML configuration:

'saml2' => [
    'metadata' => env('SAML2_METADATA_URL', 'http://localhost:4000/api/saml/metadata'),
    'sp_acs' => 'auth/saml2/callback',
    'sp_default_binding_method' => \LightSaml\SamlConstants::BINDING_SAML2_HTTP_POST,
    'sp_name_id_format' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified',
],

Depending on your security requirements, you may also need signed or encrypted assertions.

Understanding the Configuration

`metadata`

This is the Identity Provider metadata URL.

Depending on your environment, this could come from:

Microsoft Entra ID
Okta
Keycloak
A local SAML testing provider

The provider uses this metadata to retrieve:

certificates
SSO endpoints
bindings
entity identifiers

`sp_acs`

This is your Assertion Consumer Service (ACS) endpoint.

After authentication, the Identity Provider redirects the user back to this endpoint.

In our case:

/auth/saml2/callback

`sp_default_binding_method`

This defines how SAML responses are transmitted.

Using POST binding is generally the safest and most common option.

Creating the Controller

A dedicated controller keeps the authentication flow clean and isolated.

<?php

namespace App\Http\Controllers\Auth;

use App\Services\SAML2Service;
use Filament\Notifications\Notification;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Response;

class SAML2Controller extends Controller
{
    public function __construct(protected SAML2Service $saml2Service) {}

    public function metadata(): Response
    {
        return $this->saml2Service->metadata();
    }

    public function redirect(): RedirectResponse
    {
        return $this->saml2Service->redirect();
    }

    public function callback(): RedirectResponse
    {
        $user = $this->saml2Service->callback();

        if (! $user) {
            Notification::make()
                ->title(__('Unable to connect. Please contact an administrator.'))
                ->danger()
                ->send();
        }

        return redirect(filament()->getUrl());
    }
}

Why Use a Dedicated Service?

Many authentication tutorials place all the logic directly inside the controller.

This quickly becomes difficult to maintain when adding:

role synchronization
multiple providers
access policies
audit logging
tenant support

Moving the SAML logic into a dedicated service keeps the architecture maintainable.

Defining the Routes

Next, create the authentication web routes:

Route::prefix('auth/saml2')
    ->name('auth.saml2.')
    ->controller(\App\Http\Controllers\Auth\SAML2Controller::class)
    ->group(function () {
        Route::get('metadata', 'metadata')->name('metadata');
        Route::get('redirect', 'redirect')->name('login');
        Route::post('callback', 'callback')->name('callback');
    });

This gives us:

/auth/saml2/metadata : Service Provider metadata
/auth/saml2/redirect : Redirect to Identity Provider
/auth/saml2/callback : Handle SAML response

Building the SAML Service

Now let’s implement the service.

<?php

namespace App\Services;

use App\Models\User;
use Filament\Facades\Filament;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Auth;
use Laravel\Socialite\Facades\Socialite;
use SocialiteProviders\Saml2\Provider;
use Symfony\Component\HttpFoundation\RedirectResponse;

class SAML2Service
{
    public function redirect(): RedirectResponse
    {
        return Socialite::driver('saml2')->redirect();
    }

    public function callback(): ?User
    {
        /** @var Provider $saml2Provider */
        $saml2Provider = Socialite::driver('saml2');

        /** @var \SocialiteProviders\Saml2\User $socialiteUser */
        $socialiteUser = $saml2Provider->stateless()->user();

        $user = User::query()->updateOrCreate(
            ['email' => strtolower($socialiteUser->getEmail())],
            ['name' => $socialiteUser->getName()]
        );

        if ($user->canAccessPanel(Filament::getCurrentOrDefaultPanel())) {
            Auth::login($user);

            return $user;
        }

        return null;
    }

    public function metadata(): Response
    {
        /** @var Provider $saml2Provider */
        $saml2Provider = Socialite::driver('saml2');

        return $saml2Provider->getServiceProviderMetadata();
    }
}

Understanding the Authentication Flow

Redirecting the User

return Socialite::driver('saml2')->redirect();

This sends the user to the Identity Provider login page.

Depending on the environment, users may already be authenticated through their corporate session.

Retrieving the Authenticated User

$socialiteUser = $saml2Provider->stateless()->user();

The provider validates the SAML response and extracts the user information.

At this stage, you usually receive:

email
first name
last name
groups
claims

The exact payload depends on your Identity Provider configuration.

Creating or Updating the User

User::query()->updateOrCreate(...)

This approach allows users to authenticate without pre-creating accounts manually.

It also keeps user information synchronized automatically.

Restricting Filament Access

$user->canAccessPanel(...)

This is an important step.

Authenticating a user does not necessarily mean they should access your Filament panel.

By checking panel access explicitly, you keep your authorization layer consistent with the rest of your application.

Generating Service Provider Metadata

One of the most useful features of the provider is automatic metadata generation.

return $saml2Provider->getServiceProviderMetadata();

This endpoint can be shared directly with your Identity Provider administrator.

It avoids:

manually crafting XML files
configuration mistakes
certificate inconsistencies

In many enterprise environments, this alone saves a significant amount of setup time.

Improving the Login Experience in Filament

You can now add a custom login button inside your Filament login page.

For example with a render hook:

FilamentView::registerRenderHook(
    PanelsRenderHook::AUTH_LOGIN_FORM_BEFORE,
    fn (): View => view('filament.components.saml-login-button')
);

In provider file (like AppServiceProvider.php boot function)

<x-filament::button
    href="{{ route('auth.saml2.login') }}"
    tag="a"
    color="primary"
    class="w-full"
    icon="heroicon-o-arrow-right-circle"
    aria-label="Connect with your SSO account"
>
    {{ __('Connect with your SSO account') }}
</x-filament::button>

In view file filament.components.saml-login-button.blade.php

This provides a much cleaner enterprise login experience.

Testing

For local development and testing, I personally use MockSAML:

This is also why the default metadata configuration points to port 4000:

'metadata' => env(
    'SAML2_METADATA_URL',
    'http://localhost:4000/api/saml/metadata'
),

Using a lightweight mock Identity Provider makes it much easier to test:

SAML authentication flows
user provisioning

Without requiring access to a real enterprise Active Directory during development.

What About Active Directory Groups?

At this point, authentication works.

However, most enterprise applications also need:

role synchronization with Active Directory group mapping
dynamic authorization

This is where things become significantly more interesting.

In the premium article, we’ll implement:

automatic role synchronization
group parsing from SAML claims
Active Directory CN extraction
role mapping strategies
production-ready access control

SAML authentication is often perceived as complex, but Laravel Socialite combined with the SAML2 provider makes the integration surprisingly clean.

By isolating the authentication flow into a dedicated service and integrating directly with Filament, you can build enterprise-ready authentication while keeping your application maintainable.

The next step is implementing proper authorization and Active Directory role synchronization.

To receive more articles like this one, subscribe to Filament Mastery!

Improve Filament Import UX with Persistent Error CSV Downloads

yebor974 — Sun, 10 May 2026 17:10:31 +0000

By default, FilamentPHP provides a convenient import action with built-in feedback once the process is complete.

After an import finishes, a notification is displayed showing the result, along with a link to download a CSV file containing failed rows.

While this works well for simple use cases, it quickly becomes limiting in real-world applications:

Only the user who initiated the import can access the error file
The download link disappears once the notification is dismissed
There is no built-in way to view past imports or retry analysis

👉 In a team environment, this can become frustrating very quickly.

In this article, we'll implement a simple and clean solution to:

List all imports in a Filament resource
Allow authorized users to download error CSV files
Manage and delete past imports

Understanding Filament's Default Behavior

Filament already provides an internal model to handle imports:

Filament\Actions\Imports\Models\Import

This model includes several useful attributes:

completed_at → timestamp
processed_rows → integer
total_rows → integer
successful_rows → integer

It also exposes computed values like:

$import->getFailedRowsCount()

Filament also defines an internal route used to download failed rows:

Route::get('/imports/{import}/failed-rows/download', DownloadImportFailureCsv::class)
    ->name('imports.failed-rows.download');

You don't need to override this route, we'll simply control access to it.

The Access Problem

By default, if no Policy is defined, Filament restricts access like this:

$importPolicy = Gate::getPolicyFor($import::class);

if (filled($importPolicy) && method_exists($importPolicy, 'view')) {
    Gate::forUser($user)->authorize('view', Arr::wrap($import));
} else {
    abort_unless($import->user()->is($user), 403);
}

Extract of Filament\Actions\Imports\Http\Controllers\DownloadImportFailureCsv Controller

This means:

If no policy exists → only the owner can download the file
If a policy exists → Filament defers authorization to it

So the solution is simple: define a Policy.

Creating the Import Policy

Generate the policy:

php artisan make:policy ImportPolicy --model="Filament\Actions\Imports\Models\Import"

Here is an example implementation:

namespace App\Policies;

use App\Enums\ImportImporterEnum;
use App\Enums\PermissionEnum;
use App\Models\User;
use App\Services\PermissionService;
use Filament\Actions\Imports\Models\Import;
use Illuminate\Auth\Access\HandlesAuthorization;

class ImportPolicy
{
    use HandlesAuthorization;

    public function __construct(protected PermissionService $permissionService) {}

    public function viewAny(User $user): bool
    {
        return $user->hasPermissionTo($this->permissionService->getPermissionName(PermissionEnum::VIEW_ANY, Import::class));
    }

    public function view(User $user, Import $import): bool
    {
        if (is_null($import->completed_at) || $import->getFailedRowsCount() == 0) {
            return false;
        }

        return $user->hasPermissionTo($this->permissionService->getPermissionName(PermissionEnum::VIEW, Import::class));
    }

    public function delete(User $user, Import $import): bool
    {
        if ($import->importer == ImportImporterEnum::PRODUCT_MAPPING->value) {
            return false;
        }

        return $user->hasPermissionTo($this->permissionService->getPermissionName(PermissionEnum::DELETE, Import::class));
    }
}

In this example, permissions are handled using a role/permission system (e.g. Spatie Laravel Permission) with a own Permission Service and Enum. Adapt this logic to your own application.

Ideally, Filament would use a dedicated download method instead of view, as these represent different concerns. However, we'll stick with the default behavior for simplicity.

Registering the Policy

Don't forget to register the policy in your service provider:

use Filament\Actions\Imports\Models\Import;

public function boot(): void
{
    Gate::policy(Import::class, ImportPolicy::class);
    ...
}

Creating the Filament Resource

Now let’s expose imports in the admin panel:

php artisan make:filament-resource Import --model-namespace=Filament\\Actions\\Imports\\Models

We don’t need forms here, only a listing page. So you can delete Schemas format and some pages like CreateImport and EditImport

Resource class

class ImportResource extends Resource
{
    protected static ?string $model = Import::class;

    public static function table(Table $table): Table
    {
        return ImportsTable::configure($table);
    }

    public static function getPages(): array
    {
        return [
            'index' => ListImports::route('/'),
        ];
    }
}

Simplified Import Resource

Building the Imports Table

Here's a simplified version of the table:

class ImportsTable
{
    public static function configure(Table $table): Table
    {
        return $table
            ->columns([
                TextColumn::make('file_name')->searchable(),
                TextColumn::make('importer'),
                TextColumn::make('user.name'),
                TextColumn::make('total_rows')->numeric(),
                TextColumn::make('processed_rows')->numeric(),
                TextColumn::make('successful_rows')->numeric(),
                TextColumn::make('completed_at')->sortable(),
            ])
            ->recordActions([
                ActionGroup::make([
                    Action::make('downloadFailedRowsCsv')
                        ->label('Download errors')
                        ->color('warning')
                        ->icon(Heroicon::ArrowDownCircle)
                        ->url(fn (Import $import) => URL::signedRoute('filament.imports.failed-rows.download', ['authGuard' => filament()->getAuthGuard(), 'import' => $import], absolute: false), shouldOpenInNewTab: true)
                        ->authorize('view'),

                    DeleteAction::make(),
                ]),
            ])
            ->defaultSort('created_at', 'desc');
    }
}

Simplified ImportsTable

Key Feature: Downloading Failed Rows

The most important part is this action:

Action::make('downloadFailedRowsCsv')

It:

Uses Filament's internal signed route
Relies on the view policy for authorization

👉 Combined with the policy, this ensures:

Only authorized users can access error files
Downloads remain secure
UX is significantly improved

Final Result

With just a Policy and a Resource, you now have:

A complete history of imports
Persistent access to error CSV files
Team-friendly access control
A cleaner and more professional admin experience

Import's actions with failed rows

Import's actions without failed rows

Conclusion

Filament provides powerful building blocks, but some features, like import history, require a bit of customization to fully shine.

With this approach, you enhance both usability and maintainability without adding unnecessary complexity.

From here, you could go further by adding:

Retry mechanisms
Import status filters
etc.

🚀 Want to go further?

Production Mindset - Laravel with Docker Compose

yebor974 — Wed, 06 May 2026 07:49:26 +0000

Introduction

In the previous article, I showed how to build a production-ready Docker image for Laravel & Filament.

But in real-world applications, a single container is never enough.

Running a production application means dealing with multiple concerns:

web server
PHP runtime
database
cache
background workers
scheduled jobs

And this is where things usually start to get messy.

The problem with "simple" setups

Most Docker Compose examples look like this:

one container
maybe a database
everything else mixed together

It works.

Until it doesn’t.

From my experience, this approach quickly leads to:

poor observability
difficult debugging
no real scaling strategy
fragile deployments

A simple rule I follow

Over time, I ended up following one principle:

👉 one container = one responsibility

It sounds simple, but it completely changes how you design your architecture.

A production-oriented architecture

Instead of one container doing everything, I split responsibilities:

app → PHP-FPM runtime
web → reverse proxy (Nginx)
db → PostgreSQL
redis → cache & queues
horizon → queue workers
scheduler → scheduled jobs

Each service is isolated.

Each service can scale independently.

Each service can fail independently.

👉 This is what makes the system predictable.

A common trap: the "public volume"

One mistake I’ve seen (and made) multiple times is how static assets are handled.

A typical setup uses:

public:/var/www/app/public

Looks fine.

But in practice:

old assets can persist between deployments
new builds may not be reflected
deployments become inconsistent

👉 This kind of issue is subtle… and painful in production.

Another key point: bootstrap vs runtime

In many setups, migrations and initialization tasks run inside the main container.

I prefer separating concerns:

runtime containers → long-running processes
bootstrap → one-time tasks (migrations, setup)

👉 In real production systems, this is often handled in CI/CD pipelines instead.

Why this matters

This kind of architecture gives you:

better isolation
clearer debugging
safer deployments
real scalability

It’s not the simplest setup.

But it’s much closer to what you actually need in production.

Going further

In this article, I intentionally kept things focused on concepts and architecture.

👉 I cover the full Docker Compose setup (with real configuration, volumes, healthchecks, and production patterns)

https://filamentmastery.com/articles/production-ready-docker-compose-for-laravel-filament/

Series

This article is part of a series on production-ready Laravel & Filament setups:

Docker image (multi-stage build)
Docker Compose architecture
CI/CD pipelines
deployment strategies

I’ll be covering each part progressively.

If you’ve already built similar setups, I’d be curious to hear how you structure your containers in production.

Production-Ready Docker Setup for Laravel & Filament

yebor974 — Tue, 28 Apr 2026 09:46:47 +0000

Introduction

Most Docker setups for Laravel applications are… fine.

They work locally, they run php artisan serve, and that’s about it.

But when you start building real-world Laravel & Filament applications used in production, those setups quickly become a liability:

slow builds
bloated images
security issues
poor separation between development and production

I’ve personally run into these issues multiple times before refining this setup.

👉 This article focuses on the core ideas and architecture.
The full production-ready implementation (with complete Dockerfile, edge cases and CI/CD integration) is available on Filament Mastery.

What This Article Covers

In this article, I’ll walk through the key concepts behind a Docker setup I use in production for Laravel & Filament projects.

This includes:

multi-stage builds
optimized dependency installation
frontend asset compilation
non-root execution for better security
environment-specific configuration (dev vs production)

The Problem with “Basic Docker Setups”

A typical Dockerfile often looks like this:

FROM php:8.4-fpm
COPY . .
RUN composer install
RUN npm install

Simple… but problematic.

Main issues:

installs dev dependencies in production
no asset compilation strategy
runs as root
large and slow images
no separation of concerns

👉 This is fine for learning, but not for production.

A Better Approach

Instead of a single container doing everything, I rely on multi-stage builds and clear separation of responsibilities.

Typical structure:

a Composer stage to install PHP dependencies
a Node stage to build frontend assets
a final PHP-FPM image focused only on runtime

👉 The goal is simple: keep the runtime image as small, secure and predictable as possible.

Key Idea: Build-Time vs Runtime

One of the biggest improvements comes from moving as much work as possible to build time.

In my experience, this means:

installing dependencies during build (not at runtime)
compiling assets once
shipping only the final artifacts

👉 The container becomes immutable and easier to reason about.

Example (Simplified)

Instead of a single-stage Dockerfile, the idea is to split concerns:

# Composer stage (dependencies)
RUN composer install --no-dev

# Node stage (assets)
RUN npm ci && npm run build

# Final image
COPY built assets + vendor only

👉 This is intentionally simplified, but it reflects the core idea.

Why This Matters

With this approach:

builds are faster thanks to caching
images are significantly smaller
attack surface is reduced
development and production concerns are clearly separated

In production environments, these differences quickly become critical.

Going Further

This article only covers the Docker image itself.

In a real production setup, you also need:

a proper Docker Compose architecture
a CI/CD pipeline to build and validate images
deployment strategies

👉 I’m progressively documenting this production setup (Docker, Compose, CI/CD and more) here:
https://filamentmastery.com/articles/production-ready-docker-setup-for-laravel-filament/

Docker setups are often underestimated in Laravel projects.

But in my experience, investing in a clean, production-ready setup early saves a lot of time later, especially when your application starts scaling.

How I Structure My Filament Projects Today

yebor974 — Wed, 08 Apr 2026 15:19:23 +0000

I’ve been working with Laravel for several years now, and around 3 years with Filament. Today, most of my client projects use Filament for backend management, and sometimes for frontend components using Livewire.

Over time, I’ve developed a simple and pragmatic way to structure my Filament projects. It’s not necessarily the best approach, but it’s the one that allows me to move fast and stay efficient.

Starting Point

I almost always start from one of my two templates:

Laravel Filament Backend Starter (for simple backends)
Laravel Filament Multi Panel Starter (when multiple panels are needed)

I’m not covering multi-tenancy here, as I’ve only worked on one such project so far. It would be close to the multi-panel setup, but I haven’t industrialized it enough yet to publish it.

These starters allow me to begin with a solid base that already includes:

Authentication + optional 2FA
Queue management with Laravel Horizon, to easily monitor jobs from the backend
Log management with Log Viewer, accessible from the backend
Roles and permissions with Spatie Laravel Permission
Password expiration handling with my own package Filament Renew Password (useful for projects in France where clients often require periodic password changes)
Pest for unit and feature testing
Laravel Debugbar for development
Pint for code style
PHPStan for static analysis

Project Structure

For project structure, I stick to Filament’s default organization.

I typically:

create a subfolder per panel
add a shared folder for reusable schemas if I have some panels with shared components (Tables, Forms, etc.)

I don’t always extract schemas into dedicated shared folder. Sometimes I keep them directly inside resource folders and refactor later if needed.

Over-optimization can hurt efficiency 😄

Project structure example

I work with PHPStorm, and usually host my code on my personal GitLab with a CI/CD pipeline (including SAST, secret detection, Composer & NPM audit, container scanning, etc.). I might share some of these resources in a future article.

One of my Gitlab CI Project

Architecture Choices

For larger projects with a more complex roadmap, I usually introduce a Service layer to centralize business logic.

I’ve experimented with more advanced patterns like Domain-Driven Design or hexagonal architecture. However, in most real-world projects I’ve worked on, these approaches added complexity without bringing significant long-term value.

Today, I prefer to keep things simple and refactor when necessary.

In some cases, I add a Repository layer on top of Services, but I feel it often reduces the power and simplicity of Eloquent while adding an unnecessary layer.

😅

This may not be the “best” way to do things, but it’s the one I use in most of my projects.

Additional Tools

With this setup, I already have a strong foundation that saves me a lot of time when starting a project.

Depending on the needs, I then add specific packages such as:

Laravel Excel for advanced Excel exports, often combined with Filament’s export system
Laravel Socialite for authentication with client providers (SAML v2, Google, etc.)
Spatie Laravel Activity Log for user activity tracking, sometimes extended with timestamping and hashing for audit purposes
Some filesystem libraries like league/flysystem-sftp-v3 for SFTP file transfers

Conclusion

Over time, I’ve realized that what matters most is not having a perfect architecture from day one, but having a simple foundation that allows you to move forward quickly.

Today, I tend to prioritize simplicity and efficiency, improving things along the way when needed.

Feel free to let me know in the comments if this kind of article is useful. It’s a bit different from what I’ve shared so far on Filament Mastery.

For more posts: Filament Mastery

A fresh start with GHOST for Filament Mastery!

yebor974 — Mon, 06 Apr 2026 14:59:39 +0000

After several months of reflection, I’ve moved the site to a new platform.

The goal is simple: focus on what matters most, creating useful content , including tutorials, practical insights, and actionable development resources.

What’s New

The site now runs on a simpler platform, better suited for publishing content
Reading experience is smoother and faster
You can now comment on posts! Your feedback and questions are welcome.
I’ll be able to publish more regularly, with fewer technical constraints

Note: Some old links may not work immediately but will be reactivated gradually.

Your Accounts

Good news:

👉 Your accounts have been automatically migrated

If you were subscribed to the newsletter:

You’ll continue to receive upcoming content
No action is required on your part

What’s Next

I’ll be gradually publishing:

Practical tutorials
Hands-on guides
Insights and lessons from my projects

With a clear goal: sharing content that’s useful, actionable, and free of unnecessary fluff.

Thank you all for your support 🙏

I can’t wait to read your comments and share the next pieces of content soon!

📬 Join the community on filamentmastery.com

Filament slow on large table? Optimize with Postgres partitions

yebor974 — Tue, 13 Jan 2026 07:20:56 +0000

When I started working on a client project, I ran into a familiar challenge: a Filament Resource managing millions of sensor measurements.

The table contained several years of historical data. Most users usually focused on the current month, but occasionally they needed to look back at older measurements for special cases.

At first, it looked like the resource was slow simply due to its sheer size, but profiling revealed a deeper issue. It became clear that Filament itself was not the bottleneck, the database was.

Identifying the problem

Filtering by date or sensor type took several seconds, even for just the current month. Sorting and pagination felt sluggish. It was a classic case of “everything works, but not fast enough for production.”

The goal was simple: allow fast access to current data while keeping historical queries possible, without rewriting the panel.

The example below has been simplified for clarity. In the real project, additional filters and performance optimizations were applied. Default dates focus on the current month, but older data queries remain fully supported. The project was built with FilamentPHP and PostgreSQL.

Partitioning the table by month

To solve the problem, I used PostgreSQL table partitioning, splitting the data by month. Here’s a simplified example:

// Parent table
CREATE TABLE sensor_measurements (
    id BIGSERIAL NOT NULL,
    sensor_id BIGINT NOT NULL REFERENCES sensors(id) ON DELETE CASCADE,
    value NUMERIC(10,2) NOT NULL,
    measured_at TIMESTAMP(0) NOT NULL,
      data JSONB
      created_at TIMESTAMP(0) DEFAULT now(),
    updated_at TIMESTAMP(0) DEFAULT now(),
      PRIMARY KEY (id, measured_at)
) PARTITION BY RANGE (measured_at);

// a month partition
CREATE TABLE IF NOT EXISTS sensor_measurements_2026_01 PARTITION OF sensor_measurements
    FOR VALUES FROM ('2026-01-01') TO ('2026-02-01');

CREATE TABLE IF NOT EXISTS sensor_measurements_2026_02 PARTITION OF sensor_measurements
    FOR VALUES FROM ('2026-02-01') TO ('2026-03-01');

The partition key need to be in the primary key.

Partitioning ensures queries for the current month only scan a small, relevant subset, keeping performance high. Historical queries still work efficiently by targeting older partitions.

I created a scheduled job to automatically create new year/month partitions. More information about PostgreSQL partitioning is available in the official PostgreSQL documentation

Adding indexes and optimizing queries

Indexes must be created on each partition, not on the parent table. For example:

CREATE INDEX idx_sensor_measurements_2026_01_data_gin
    ON sensor_measurements_2026_01(sensor_id)
      USING GIN (data);

CREATE INDEX idx_sensor_measurements_2026_01_measured_at 
    ON sensor_measurements_2026_02(measured_at)
      USING GIN (data);

This ensures that even with filters, the database can quickly find the relevant rows.

Adjusting the Filament Resource

Finally, I adapted the Filament Resource with default filters for the current month:

use Carbon\Carbon;

class SensorMeasurementResource extends Resource
{
      //...

    public static function table(Table $table): Table
    {
        $now = Carbon::now();

        return $table
            ->columns([
                TextColumn::make('sensor_id')->sortable(),
                TextColumn::make('value'),
                TextColumn::make('measured_at')->dateTime(),
            ])
            ->filters([
                Filter::make('date')
                    ->form([
                        DatePicker::make('from')
                            ->default($now->copy()->startOfMonth()),
                        DatePicker::make('to')
                            ->default($now->copy()->endOfMonth()),
                    ])
                    ->query(fn(Builder $query, array $data) => $query
                        ->when($data['from'], fn($q) => $q->where('measured_at', '>=', $data['from']))
                        ->when($data['to'], fn($q) => $q->where('measured_at', '<=', $data['to']))
                    ),
            ]);
    }
}

I didn't include the TableSchema file in this example for simplicity. One limitation is that the filter cannot be made mandatory without allowing users to remove it from the indicators toolbar. The goal is to always have a date range to optimize database loading.

Results

The impact was immediate:

Queries for the current month now return in under 300ms
Historical queries remain fast enough for occasional analysis
Users can explore both current and past data without frustration

Lessons Learned

Filament can handle large datasets, if the underlying database is optimized.
Partitioning by time periods is ideal for sensor or historical measurement data.
Proper indexes + pagination make huge tables usable in production.
Profiling queries first saves hours of wasted debugging in the admin panel.
Small tweaks in Filament (filters, lazy-loading) can dramatically improve UX.

If you enjoyed this kind of real-world experience and case study, don’t forget to like and share it!

📬 Join the community on filamentmastery.com

One year of Filament Mastery - A personal look back at 2025

yebor974 — Wed, 31 Dec 2025 08:13:03 +0000

About a year ago, I launched Filament Mastery with a pretty simple goal: create a place around FilamentPHP that I would genuinely enjoy reading myself.

No hype, no endless tutorials rewritten ten times, no over-engineered examples, just clear, useful content for developers building things with Filament.

As 2025 comes to an end, this felt like the right moment to pause for a bit and look back at what Filament Mastery has become over its first year.

Filament Mastery in numbers

I usually don’t obsess too much over metrics, but numbers can still tell part of the story.

After one year, Filament Mastery looks like this:

347 community members
274 newsletter subscribers
35 published articles
12 community links
4 partners supporting the project

They’re just numbers, but behind them are real people reading, learning, experimenting, and building things with Filament.

A community that goes beyond borders

One thing that surprised me early on was how international the audience became.

Looking at the dashboard, users are spread across many different time zones. Some of that data isn’t perfectly accurate (a lot of users are still grouped under UTC), but the overall trend is clear:

Filament Mastery is being read all over the world.

Different countries, different projects, different levels of experience — but the same interest in building solid back-offices with Filament.

What this year taught me

Working on Filament Mastery over the past year reinforced a few things I already suspected:

Developers value clarity more than complexity.
Not every problem needs a clever abstraction or a custom solution.
Filament works best when you lean into its conventions instead of fighting them.
Writing content that you would actually use is usually the right approach.

I intentionally kept Filament Mastery focused and calm. No rush to publish, no pressure to cover everything, just content that feels useful and honest.

A sincere thank you

Even though I’m writing this from a personal perspective, Filament Mastery wouldn’t exist without the people reading it and writing.

So thank you, whether you’ve read one article, subscribed to the newsletter, shared a link, wrote an article or simply bookmarked the site and come back from time to time.

Where to follow Filament Mastery

If you’d like to stay updated, share content, or help the community grow, you can also find Filament Mastery on:

X.com
Dev.to
Facebook
LinkedIn

Following and sharing helps more than you might think.

Looking ahead to 2026

I don’t have a big roadmap or ambitious promises for 2026 — and that’s very much on purpose.

Most of what I share on Filament Mastery comes directly from real client projects.

Things I actually use, patterns that work in practice, and decisions made under real-world constraints. I usually avoid diving too deep into heavy concepts like strict DDD or over-abstracted architectures, not because they’re wrong, but because they often add complexity and make articles harder to read and reuse.

My goal is to keep sharing practical ideas that you can adapt easily, without forcing a specific methodology or way of thinking.

I also want Filament Mastery to stay open and community-driven.

Anyone can write and publish content directly from their member area, and this will remain free. No paywalls, no hidden requirements, just useful content shared by people building real things.

On a more personal note, 2026 will also be a bit different for me. I’m planning to spend around six months in Europe, and if the opportunity comes up, I’ll try to attend local meetups or events. Nothing official or planned yet, just a chance to meet people from the community in real life.

For now, the direction stays simple: build, learn, share and keep things approachable.

Thanks for being part of this first year, and see you in 2026 🚀

📬 Join the community on filamentmastery.com