filament-sentinel

KO | EN

gitlite — search

#editor #generative-ai #animation #ui #redis #linux #typescript #java #mcp #machine-learning

filament-sentinel

(★ 9)

Branded, diagnostic error pages (500, 403, 404, 419, 503) for Filament — native UI, dark mode, i18n.

File Explorer

ZIP Download

- - 403-light.png
  - 403.png
  - 404-light.png
  - 404.png
  - 419-light.png
  - 419.png
  - 500-overlay-light.png
  - 500-overlay.png
  - 503-light.png
  - 503.png
- banner.png
- directory-cover.jpg
- sentinel.php
- - scripts.blade.php
- - Sentinel.php
- SentinelPlugin.php
- SentinelServiceProvider.php
- - ErrorPagesTest.php
- - SentinelPluginTest.php
  - SentinelTest.php
- Pest.php
- TestCase.php
.gitignore
CHANGELOG.md
composer.json
LICENSE.md
phpunit.xml
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Filament Sentinel</h1>

Branded, diagnostic error pages for <a href="https://filamentphp.com">Filament</a>.

---

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

<table>
<tr>
<td width="50%"><img src="art/screenshots/403.png" alt="403 Access denied"> 403 — access denied, with the real reason</td>
<td width="50%"><img src="art/screenshots/404.png" alt="404 Page not found"> 404 — page not found, with the missing path</td>
</tr>
<tr>
<td width="50%"><img src="art/screenshots/419.png" alt="419 Session expired"> 419 — session expired</td>
<td width="50%"><img src="art/screenshots/503.png" alt="503 Down for maintenance"> 503 — maintenance, with <code>Retry-After</code></td>
</tr>
</table>

#### Every page follows your panel's light or dark theme automatically

<table>
<tr>
<td width="50%"><img src="art/screenshots/403-light.png" alt="403 Access denied, light theme"> 403 — light theme</td>
<td width="50%"><img src="art/screenshots/404-light.png" alt="404 Page not found, light theme"> 404 — light theme</td>
</tr>
<tr>
<td width="50%"><img src="art/screenshots/419-light.png" alt="419 Session expired, light theme"> 419 — light theme</td>
<td width="50%"><img src="art/screenshots/503-light.png" alt="503 Down for maintenance, light theme"> 503 — light theme</td>
</tr>
</table>

## Installation

```bash
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.

```php
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:

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

| Option | Description | Default |
| --- | --- | --- |
| `enabled` | Serve the branded pages at all | `true` |
| `codes` | Status codes Sentinel provides | `[500, 403, 404, 419, 503]` |
| `brand` | Wordmark shown on each page | panel / app name |
| `message_number.enabled` | Show the `SNT-500-087` reference | `true` |
| `message_number.prefix` | Message-number prefix | `SNT` |
| `request_id.enabled` | Show and assign a request id | `true` |
| `show_exception_details` | Reveal the real exception on 500: `null` follows `APP_DEBUG`, `true` always, `false` never | `null` |
| `window.style` | 500 presentation: `window` (small docked) or `page` (full page, like the other codes) | `window` |
| `window.position` | Docked window placement: `bottom-left`, `bottom-right`, `top-left`, `top-right`, `top-center`, `bottom-center`, `center`, or a full-height slide-over with `slide-right` / `slide-left` | `bottom-left` |
| `window.width` | Docked window width — a number (pixels) or CSS length (`"28rem"`) | `400` |
| `support_url` | URL / `mailto:` for "Contact support" | `null` |
| `home_url` | Destination of the primary button | `/` |

## Fluent API

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

| Method | Purpose |
| --- | --- |
| `->brand($name)` | Wordmark on every page |
| `->messagePrefix($prefix)` | Prefix of the message number |
| `->messageNumbers($bool)` | Toggle message numbers |
| `->requestId($bool)` | Toggle the request id |
| `->showExceptionDetails($bool)` | Force the 500 exception panel on (`true`) or off (`false`); omit to follow `APP_DEBUG` |
| `->windowPosition($position)` | Where the docked 500 window sits (`center`, `top-right`, `slide-right`, …) |
| `->windowWidth($width)` | Docked window width (`460` or `"28rem"`) |
| `->fullPage($bool = true)` | Render the 500 as a full page like the other codes |
| `->supportUrl($url)` | "Contact support" link |
| `->email($address)` | "Contact support" as a `mailto:` link |
| `->homeUrl($url)` | Primary "back to safety" destination |
| `->codes($array)` | Status codes to brand |
| `->enabled($bool)` | Disable the whole package |

## Publishing & customization

```bash
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

```bash
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

```bash
composer test
```

## License

MIT. See [LICENSE.md](LICENSE.md).

filament-sentinel

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README