DEV Community: yebor974

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

How to send Filament database notifications to a specific queue

yebor974 — Thu, 04 Sep 2025 10:10:16 +0000

When working with Filament\Notifications\Notification, sending database notifications with sendToDatabase() is super convenient. But what if you want to control which queue these notifications are dispatched to?

At first glance, this looks tricky, Filament doesn’t expose a queue configuration option directly. But the good news is: you can still take full advantage of Laravel’s queue system.

Default behavior for Filament notifications on database

The usual Filament way looks like this:

use Filament\Notifications\Notification;

Notification::make()
    ->title("Your request has been processed")
    ->body("Some details about the request")
    ->sendToDatabase($user);

What happens under the hood:

Filament calls $user->notify($this->toDatabase()).
toDatabase() creates a Filament\Notifications\DatabaseNotification, which extends Laravel’s Notification, implements ShouldQueue, and uses the Queueable trait.
That means the notification goes into the queue defined by your QUEUE_CONNECTION (database, redis, etc.), but you cannot specify which queue name this way.

How to control the queue: Using `toDatabase()` + `onQueue()`

Instead of sendToDatabase(), grab the notification instance with toDatabase() and apply onQueue():

use Filament\Notifications\Notification as FilamentNotification;

$databaseNotification = FilamentNotification::make()
    ->title("Your request has been processed")
    ->body("Some details about the request")
    ->toDatabase() // returns a DatabaseNotification (Laravel Notification)
    ->onQueue('notifications'); // from Queueable trait

$user->notify($databaseNotification);

Or, in a single line:

$user->notify(
    FilamentNotification::make()
        ->title("Your request has been processed")
        ->body("Some details about the request")
        ->toDatabase()
        ->onQueue('notifications')
);

This way you keep the simplicity of Filament’s fluent API and you get fine-grained queue control.

Multiple users example

If you need to notify multiple users on the same queue:

$notif = FilamentNotification::make()
    ->title("Your request has been processed")
    ->body("Some details about the request")
    ->toDatabase()
    ->onQueue('notifications');

foreach ($users as $user) {
    $user->notify($notif); // reuses the same notification instance
}

Conclusion

If you just want to send database notifications, Filament’s sendToDatabase() is perfect.

But if you need queue control , switch to toDatabase()->onQueue('...'). That way you stay fully in the Filament ecosystem, so your notifications are correctly stored and displayed in your Filament panels, while still taking advantage of Laravel’s queue flexibility.

🙏 Thanks to @obaume for reaching out on this topic. His question made me dive deeper into Filament notifications and discover this approach!

💡 Community Idea: Currently, sendToDatabase() doesn’t allow specifying a queue. If this article gets enough likes or shares, I’ll consider proposing a Pull Request to Filament to add this feature—making queue management even easier for everyone!

📬 Join the community on filamentmastery.com — it's free!

Filament Email Verification: Leveraging Laravel’s Event System

yebor974 — Wed, 20 Aug 2025 04:11:50 +0000

In this tutorial, we'll explore how to trigger an event when a user's email is verified in a Filament application. While this is primarily a Laravel concept, Filament fully supports and integrates with Laravel's powerful event and listener system. You'll see how to apply this to Filament projects seamlessly.

We’ll cover:

Creating a listener for the email verification event,
Triggering actions such as Stripe registration or newsletter subscription,
Testing the event with Event::fake,
Extending the logic to other events like user registration or login.

By the end, you'll understand how to leverage Laravel's event system in your FilamentPHP apps for advanced user workflows.

To set up your project for enabling email verification on panel, you can check the first step of this article.

Step 1: Create a Listener for the `Verified` Event

Laravel emits the Illuminate\Auth\Events\Verified event when a user successfully verifies their email. Here's how to hook into it.

1.1 Generate the Listener

Run the following command to create a new listener:

php artisan make:listener HandleUserEmailVerified

This command will create a file in App\Listeners folder:

namespace App\Listeners;

use Illuminate\Auth\Events\Verified;

class HandleUserEmailVerified
{
    /**
     * Handle the event.
     *
     * @param \Illuminate\Auth\Events\Verified $event
     * @return void
     */
    public function handle(Verified $event)
    {
        ///
    }
}

1.2 Implement the Listener

Update the listener to perform actions after email verification, for example :

namespace App\Listeners;

use Illuminate\Auth\Events\Verified;

class HandleUserEmailVerified
{
    /**
     * Handle the event.
     *
     * @param \Illuminate\Auth\Events\Verified $event
     * @return void
     */
    public function handle(Verified $event)
    {
        $user = $event->user;

        // Example: Create a Stripe account
        if (!$user->stripe_id) {
            $this->createStripeAccount($user);
        }

        // Example: Subscribe to a newsletter
        $this->subscribeToNewsletter($user);
    }

    protected function createStripeAccount($user)
    {
        // Logic to integrate with Stripe API
    }

    protected function subscribeToNewsletter($user)
    {
        // Logic to integrate with a mailing list API
    }
}

Step 2: Register the Listener for the `Verified` Event

If you're using Laravel 10 or later, Laravel can auto-discover event-listener mappings. So this step may not always be required, but keeping it explicit helps with debugging.

namespace App\Providers;

use Illuminate\Auth\Events\Verified;
use App\Listeners\HandleUserEmailVerified;

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        Verified::class => [
            HandleUserEmailVerified::class,
        ],
    ];
}

Step 3: Test the Listener with `Event::fake`

Before using this in production, ensure everything works as expected. Laravel provides a helpful testing utility to fake events and assert their behavior.

Here’s a test example:

namespace Tests\Feature;

use Illuminate\Auth\Events\Verified;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;
use App\Models\User;

class EmailVerificationTest extends TestCase
{
    use RefreshDatabase;

    /** @test */
    public function it_dispatches_verified_event_after_email_verification()
    {
        Event::fake();

        $user = User::factory()->unverified()->create();

        $user->markEmailAsVerified();

        // Assert the Verified event was dispatched
        Event::assertDispatched(Verified::class, function ($event) use ($user) {
            return $event->user->is($user);
        });
    }
}

Step 4: Applying the concept in FilamentPHP

Why This Matters in Filament

Filament is built on Laravel, meaning you can use Laravel's event system in your Filament-powered applications. For example, when managing a User Resource , you can leverage the same listener to perform actions after email verification.

You could:

Add custom hooks in Filament tables or forms,
Use Filament notifications to display messages when an event is triggered,
Extend user workflows directly within the Filament admin panel.

Step 5: Extending the Principle

Event: `Registered`

The Illuminate\Auth\Events\Registered event fires after a new user is created. This is useful for:

Sending a welcome email,
Assigning default roles,
Creating a related profile or team entry.

Example listener:

namespace App\Listeners;

use Illuminate\Auth\Events\Registered;

class HandleUserRegistered
{
    public function handle(Registered $event)
    {
        $user = $event->user;

        // Assign a default role
        $user->assignRole('default');
    }
}

Event: `Login`

The Illuminate\Auth\Events\Login event fires upon user login. Use it to:

Log user activity,
Update a "last login" timestamp,
Sync data with an external system.

Example listener:

namespace App\Listeners;

use Illuminate\Auth\Events\Login;

class HandleUserLogin
{
    public function handle(Login $event)
    {
        $user = $event->user;

        // Update last login time
        $user->update(['last_login_at' => now()]);
    }
}

Conclusion

By using Laravel's event system into your Filament projects, you can create robust workflows tailored to user actions. Whether it's email verification, registration, or login, the possibilities are endless.

📬 Join the community on filamentmastery.com — it's free!

Laravel Filament Multipanel Starter - Build your app fast

yebor974 — Wed, 13 Aug 2025 11:20:37 +0000

Looking for a ready-to-use admin and member panels for your Laravel projects? Meet Laravel Filament Multipanel Starter — a clean, opinionated starter kit designed to help you ship faster with Laravel 12 and Filament PHP v4.

What’s included?

Setting up a secure and well-structured backend can take hours. With this starter, you get:

Dedicated admin panel accessible via path or subdomain
Dedicated member panel accessible via path or subdomain
Secure authentication with:
- Email invitation system on user creation
- Password renewal required on first login (via Filament Renew Password)
- Multi-factor authentication with App authentication (not required)
User management (Filament Resource) with:
- Spatie Laravel Permission for roles & permissions
- Default roles and policies pre-seeded
User profile management (email, name, password, timezone)
Light & Dark theme switch + empty custom theme ready to be extended
Database notifications (Filament native support)
Logs Viewer integration (opcodesio/log-viewer) — protected by auth & backend role
Laravel Horizon — queued jobs management — protected by auth and backend role
Timezone management from user profile - Custom registration for member panel with timezone auto-detect.
Centralized date display settings (TextColumn, DateTimePicker)
Default password policy (min 12 characters, mixed case, numbers, symbols)
Fully localized , default to 🇬🇧 english. Extends with your own languages
Dev-friendly tools:
- Laravel Debugbar
- PHPStan for static analysis
- Pint for consistent code formatting

Instead of reinventing the wheel every time you need a secure backend panel and a secure member panel , this template gives you a solid, scalable foundation —with the best practices already in place.

Tech stack highlights

Laravel 12
Filament PHP v4
Tailwind CSS v4
PHP 8.2+
PostgreSQL / MySQL
Redis & Laravel Horizon

Who is it for?

✅ SaaS admin and member panels
✅ Internal dashboards
✅ Intended for public-facing user portals (for a simple backend panel without member panel you can see Laravel Filament Backend Starter).

Compare Starter Templates

Feature / Module	Backend Starter	Multipanel Starter
Laravel version	Laravel 12	Laravel 12
Filament version	v4	v4
Backend Panel	✅	✅
Member Panel (User Portal)	❌	✅ User panel with login, registration, profile
Panel-Specific Middleware & Routes	✅	✅ Per panel config & middleware
Subdomain or Path Routing	✅	✅ (separate for each panel)
Authentication via Email Invitation	✅	✅
Password Reset on First Login	✅	✅
Multi-factor authentication	✅ (App authentication)	✅ (App authentication)
Roles & Permissions (Spatie)	✅	✅
Timezone Management	✅	✅
User Profile Management	✅	✅
Logs Viewer (Opcodes)	✅	✅ (protected backend user)
Laravel Horizon	✅	✅ (protected backend user)
Dark Mode & Theme Ready	✅	✅
Multi-language Support	✅	✅
Dev Tools (Debugbar, PHPStan, Pint)	✅	✅
Ready for SaaS Admin Panel	✅	✅
Ready for Public-Facing User Portal	❌	✅ (ideal for memberships)
Use Case	Internal tools, dashboard.	Full-stack app (admin + users)

Get it now

👉 Get Laravel Filament Multipanel Template

Register or connect to your panel and get 10% off from the offers page

You will receive your ZIP template by mail. Your purchase grants you the right to use this starter template on unlimited personal or client projects. Reselling or redistributing the code as a standalone product is not allowed.

Visual overview

What’s next?

I'm working on more Filament templates and plugins to make your life easier.Register to Filament Mastery for updates and new releases.

👉 Get Laravel Filament Multipanel Template

Like this article if you'd like me to share more starter kits!