Filament Debugger Laravel Package

Getting Started

Prerequisites. This package is a thin Filament integration layer, not a replacement for the underlying tools. Install and configure the tools you actually want to expose first:

composer require laravel/telescope laravel/horizon laravel/pulse
php artisan telescope:install && php artisan pulse:install
php artisan migrate

Horizon additionally needs Redis and a running php artisan horizon process.

Install the plugin.

composer require stephenjude/filament-debugger

Register it in the panel provider where you want the debug surfaces to appear:

use Stephenjude\FilamentDebugger\FilamentDebuggerPlugin; // confirm exact class name in the README

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentDebuggerPlugin::make());
}

Publish any package config if the README lists a publish tag, then clear caches:

php artisan vendor:publish --provider="Stephenjude\FilamentDebugger\FilamentDebuggerServiceProvider"
php artisan config:clear
php artisan filament:optimize-clear

Where to look first.

1. README.md — installation snippet and screenshots show whether the package links to, embeds, or re-implements each dashboard.
2. src/FilamentDebuggerServiceProvider.php — how pages/navigation/routes are registered.
3. config/filament-debugger.php (if published) — per-tool enable/disable flags and navigation settings.
4. src/Pages/ — the canAccess() implementation is the most important security surface.
5. composer.json — Filament version constraint tells you whether this is a v3 or v4 panel.

First use case. You have a staging environment and want a single authenticated admin URL where the team can check queue health (Horizon/Pulse), recent slow requests and exceptions (Telescope), and application health metrics (Pulse) without passing around three separate dashboard URLs.

Implementation Patterns

Scope registration by environment and panel. Only register the plugin where it makes sense. The cleanest pattern is a dedicated "ops" panel or a guarded condition in the panel provider:

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->path('admin')
        ->plugin(
            FilamentDebuggerPlugin::make()
            // only if the package exposes per-tool toggles:
            // ->telescope()
            // ->horizon()
            // ->pulse()
        );
}

For local-only Telescope and always-on Pulse, register the plugin on your main panel but gate the Telescope entry separately (see authorization below). If the package supports a config array, prefer environment-driven config:

// config/filament-debugger.php
'telescope' => env('FILAMENT_DEBUGGER_TELESCOPE', app()->environment('local')),
'horizon'   => env('FILAMENT_DEBUGGER_HORIZON', true),
'pulse'     => env('FILAMENT_DEBUGGER_PULSE', true),

Align Filament access with tool gates. Telescope, Horizon, and Pulse each have their own authorization gates (viewTelescope, viewHorizon, viewPulse). The package's navigation items are only as secure as the page's canAccess(), so lock both layers down:

use Illuminate\Support\Facades\Gate;

Gate::define('viewTelescope', fn ($user) => $user->hasRole('developer'));
Gate::define('viewHorizon',   fn ($user) => $user->hasRole('ops'));
Gate::define('viewPulse',     fn ($user) => $user->hasAnyRole(['ops', 'admin']));

Then ensure the Filament panel itself is restricted (canAccessPanel() on the User model) so non-ops users never see the navigation group at all. This is the single most important integration step.

Use a separate panel for observability. A common pattern is a second Filament panel mounted at /ops with its own auth guard and a stricter canAccessPanel() check. This avoids mixing debug navigation into the day-to-day admin UI and makes it trivial to disable the whole surface in production by removing the panel provider registration.

Use each tool for its strength.

• Pulse — production-friendly, low-overhead: slow queries, slow requests, cache hit rates, exceptions, queue throughput. Keep this enabled on production behind authorization.
• Horizon — queue operations: failed jobs, retries, wait times, supervisor status. Only useful when the app actually uses Redis queues and Horizon is running.
• Telescope — deep local/staging request inspection: queries, mail, notifications, jobs, events. Keep it local/staging only.

Cross-link from resources and widgets. If you build custom Filament widgets (e.g. a queue-health widget), link to the plugin's page URLs via the page classes' getUrl() rather than hardcoding /telescope or /horizon. This keeps links working if the package changes route prefixes.

Customize navigation. If the package exposes navigation configuration, set a dedicated group so debug tools don't clutter the main nav:

->navigationGroup('Observability')
->navigationSort(99)

If those methods are not exposed, publish the views/pages and override getNavigationGroup() on the page classes.

Extension point. Because the package is small, the practical extension point is publishing its pages/config and subclassing the plugin's page classes. Override canAccess(), getNavigationLabel(), or getSlug() rather than forking the package.

Gotchas and Tips

Never expose Telescope in production. Telescope records request payloads, headers, session data, and queries. Even behind Filament auth, a single misconfigured panel is a data leak. Use APP_ENV gating and the viewTelescope gate together.

Telescope storage grows fast. Configure TELESCOPE_DB_CONNECTION and pruning (telescope:prune --hours=48 scheduled daily), otherwise your default database bloats. This is the most common "why is the admin slow" cause after enabling Telescope.

Horizon needs more than the package. Installing the plugin does not install Redis, configure a supervisor, or start horizon. If the Horizon page is empty or 500s, check php artisan horizon:status, REDIS_* env vars, and that config/horizon.php exists.

Route collisions. Telescope, Horizon, and Pulse each register root-level routes (/telescope, /horizon, /pulse). If those paths conflict with app routes or another panel, adjust the tool's path config (config/telescope.php, config/horizon.php, config/pulse.php) before blaming the plugin.

Embedding vs. redirecting. Check the README/source to know whether the plugin embeds dashboards in an iframe or links out. If it embeds, X-Frame-Options: DENY, CSP frame-ancestors, or Content-Security-Policy headers set by your app or proxy will produce a blank page. Fix at the middleware/proxy level; you cannot fix it from Filament.

Gates must be registered before the panel boots. Defining viewTelescope/viewHorizon/viewPulse inside a service provider that runs after Filament's panel provider can result in "user not authorized" or, worse, an open page. Put gate definitions in AuthServiceProvider (Laravel 10/11) or a dedicated AppServiceProvider::boot() that runs early.

Config and Filament caches. After changing plugin config or panel providers:

php artisan config:clear
php artisan filament:optimize-clear
php artisan route:clear

In production deployments, php artisan filament:optimize caches panel components; a newly installed plugin page may not appear until you re-run it.

Multiple panels. Registering the same plugin on two panels can produce duplicate navigation or slug conflicts. Prefer one ops panel, or give each panel a distinct path and confirm the plugin supports multi-panel registration.

Version compatibility. Filament 3 vs. 4 plugin APIs differ (notably around Plugin contracts and page registration). Confirm the package's composer.json constraint matches your Filament major version. With a small package (105 stars, zero dependents, last release 2026-06-25), pin the version in composer.json and read the source before upgrading Filament.

Debugging checklist when a page doesn't appear.

php artisan route:list | grep -E 'telescope|horizon|pulse'
php artisan about
php artisan filament:optimize-clear

Then verify: plugin registered in the correct panel provider, panel canAccessPanel() allows the current user, the tool's gate returns true, and the corresponding tool is actually installed (class_exists(\Laravel\Telescope\Telescope::class)).

Low-adoption risk. With no dependents, treat the package as a convenience wrapper you can replace. The functionality—navigation entries plus authorization—is straightforward to reimplement as three custom Filament pages if the package breaks. Keep your own canAccess() logic in application code, not solely in the package, so you retain control of the security boundary.