README

Filament Sentinel

Branded, diagnostic error pages for Filament.

A drop-in replacement for Laravel's default 500, 403, 404, 419 and 503 pages, built from native Filament UI so they inherit your panel's colours, fonts, brand logo and dark mode automatically.

• Native Filament, not a bespoke theme — pages are composed from <x-filament::button>, badge, section and icon, on a light theme-aware scaffold. No design system to maintain.
• Real data, never invented — content is derived from the actual exception: authorization detail on 403, the missing path on 404, Retry-After on 503, and on 500 the real exception behind a "View more" panel — class, location, message and a structured, debugger-style stack trace, unwrapped to the root cause. Exposure follows APP_DEBUG by default; force it on/off with show_exception_details.
• SAP-style message numbers (e.g. SNT-500-087), stable per error signature — the same failure always quotes the same number, easy to give to support.
• Request ids assigned by middleware and echoed on the response, so the id on the page matches your logs.
• Translations for English, European Portuguese and Brazilian Portuguese.

Screenshots

A panel action failed — the branded 500 appears over the real, still-visible page

403 — access denied, with the real reason	404 — page not found, with the missing path
419 — session expired	503 — maintenance, with Retry-After

Installation

composer require anselmokossa/filament-sentinel

That's it. The package auto-registers and its pages become the default for aborted requests — nothing to publish. Your app can still override any page by adding its own resources/views/errors/{code}.blade.php.

The pages reuse Filament's published base stylesheet (public/css/filament/filament/app.css). It is created by php artisan filament:assets, which Filament already runs on install and deploy.

Register the plugin (optional)

Add the plugin to a panel to configure it fluently. This is optional — the pages work without it.

use Filament\Sentinel\SentinelPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            SentinelPlugin::make()
                ->brand('Acme')                 // defaults to the panel/app name
                ->messagePrefix('ACM')           // ACM-500-087
                ->windowPosition('bottom-right')  // or ->fullPage() for a full-page 500
                ->email('help@acme.test')        // "Contact support" mailto:
                ->homeUrl('/admin'),
        ]);
}

Configuration

Publish the config to tweak defaults:

php artisan vendor:publish --tag=sentinel-config

Fluent API

Every option above is also settable on SentinelPlugin::make(); anything left unset falls back to config/sentinel.php.

Publishing & customization

php artisan vendor:publish --tag=sentinel-config        # config/sentinel.php
php artisan vendor:publish --tag=sentinel-translations  # lang files to edit the wording
php artisan vendor:publish --tag=sentinel-views         # the Blade views, to restyle

Overriding a page

Because the pages register as the default errors::{code} views, you override any of them the standard Laravel way — add your own resources/views/errors/404.blade.php and it wins.

Eject — keep the pages after removing the plugin

php artisan vendor:publish --tag=sentinel-errors

This drops a self-contained set of error pages (500, 403, 404, 419, 503) straight into resources/views/errors/. They have no dependency on this package — or even on Filament (their own palette, inlined styles and icons, only Laravel core for the message number, request id and exception detail), so they stay branded and keep working even after you composer remove the plugin. From then on they are yours to edit. The published copies live in your app, so they take precedence over the plugin immediately.

Testing

composer test

License

MIT. See LICENSE.md.