Getting Started

Minimal Setup

Check your version matrix first. v5 targets Filament v5 + Laravel 12/13. If you're still on Filament v4, stay on the v4 line:
```
# Filament v5 / Laravel 12-13
composer require tomatophp/filament-developer-gate:^5.0

# Filament v4 (maintained branch)
composer require tomatophp/filament-developer-gate:^4.0
```
Pin the constraint explicitly rather than relying on * — the two major lines are not interchangeable.
Publish the config (and views/assets if you plan to customise the gate page):
```
php artisan vendor:publish --tag="filament-developer-gate-config"
```
Look at config/filament-developer-gate.php first — the password, the redirect target and the enabled flag all live here.

Register the middleware alias (Laravel 11+ style, in bootstrap/app.php):

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'developer.gate' => \TomatoPHP\FilamentDeveloperGate\Http\Middleware\DeveloperGateMiddleware::class,
    ]);
})

In Filament panels you can usually skip the alias entirely and reference the class directly (see below).

Attach it to your panel — this is the intended first use case:

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->path('admin')
        ->middleware([
            \TomatoPHP\FilamentDeveloperGate\Http\Middleware\DeveloperGateMiddleware::class,
        ]);
}

Set the password in .env and clear config:

php artisan config:clear

DEVELOPER_GATE_PASSWORD=your_secure_password_here

Verify the install — v5 ships a test suite and an install command, so the fastest sanity check is running the package's own tests or hitting the panel and confirming you get the gate page rather than the dashboard.

Implementation Patterns

Workflows

Gate a whole panel, not individual routes. The package is designed to sit in the panel middleware stack. Adding it to routes/web.php groups manually fights Filament's routing and usually ends up double-registering auth.
Gate only non-production environments. The common day-to-day use is a client-facing/staging site where anyone with the URL shouldn't reach /admin:
```
// AdminPanelProvider
->middleware(
    app()->environment('production')
        ? []
        : [\TomatoPHP\FilamentDeveloperGate\Http\Middleware\DeveloperGateMiddleware::class]
)
```
Or drive it from the package config's enabled flag and keep the provider static.
Redirect behaviour (v5). The unlock flow now falls back to the configured redirect when there's no previous page — i.e. a developer who hits /admin directly in a fresh session lands on the configured URL instead of a blank/intended-URL miss. If your config still points at the old wrong key from a pre-5 config file, republish or manually align the key, otherwise your redirect silently goes to the default.
Deep-link friendly testing. Because the intended URL is preserved and only falls back when absent, you can hand a developer a deep link (e.g. /admin/resources/orders/42/edit) and the gate will return them there after unlocking. Test both cases: direct hit on /admin (fallback path) and deep link (intended path).
Logout action. v5's test suite covers the logout action — use it rather than back-buttoning or clearing cookies. It's the reliable way to re-lock the gate when demoing or handing a laptop back.
Custom gate page. Publish views and override the gate Blade view; keep it free of any panel-authenticated component calls, since the gate renders before panel auth.

Combine with real auth, not instead of it. The developer gate is a front door, not an authorisation layer:

->middleware([
    \TomatoPHP\FilamentDeveloperGate\Http\Middleware\DeveloperGateMiddleware::class,
])
->authMiddleware([
    // your normal Filament auth middleware stays here
])

Gotchas and Tips

Pitfalls

Version mismatch is the #1 failure. Installing v5 on Filament v4 (or the reverse) will produce composer conflicts or runtime errors against Filament internals. Confirm filament/filament and laravel/framework constraints before bumping. The v4 branch is the supported home for Filament v4 projects — don't expect v5 fixes backported.
Stale published config after upgrading. The redirect fix in v5 references the correct config key. A config file published under v4 keeps the old shape. Diff your published config against the package's config/filament-developer-gate.php after upgrading, or republish and re-apply your customisations. Then php artisan config:clear.
Middleware order. The gate must run after session middleware and before panel auth middleware that assumes a logged-in user:
```
->middleware([\TomatoPHP\FilamentDeveloperGate\Http\Middleware\DeveloperGateMiddleware::class]) // correct placement
```
Putting it after authMiddleware means users hit a login screen they can't pass before ever seeing the gate.
Password in .env only. Never commit the gate password, and never let it equal a real user password. Rotate it after any screen-share or contractor session — the gate is shared-secret by design.
Route/config cache. After changing middleware or config in a cached deployment:
```
php artisan optimize:clear
```
Middleware list changes are especially easy to miss when route:cache is active.
Don't confuse the gate redirect with Filament's ->login() redirect. They serve different flows; the gate redirect only applies to the unlock step. If your unlock lands somewhere unexpected, check both.
Don't build authorisation on top of it. Anyone with the gate password is "a developer". Per-user permissions still belong in Filament policies.

Debugging

Upgrade to v5 before debugging redirects. The "wrong config key" bug and the missing-previous-page fallback are both fixed in v5 — if you're chasing a redirect that goes nowhere on v4, upgrading is the fix, not a workaround.
Gate page not appearing at all. Confirm the middleware is actually in the panel's middleware array (php artisan about / dump the panel config), and that you're not being short-circuited by an earlier auth redirect.
Unlock succeeds but you bounce back to the gate. Usually session/cookie domain mismatch, or the intended URL pointing at a route the gate itself protects. Check storage/logs/laravel.log and the session driver.
Run the shipped tests. v5 includes coverage for the gate page, middleware, logout action and install command — a good baseline to confirm your environment isn't the problem before filing anything.

Extension Points

Wrap the middleware for time-boxed or team-based access rather than editing vendor code:

// app/Http/Middleware/DemoGate.php
public function handle($request, Closure $next)
{
    if (now()->isAfter(config('demo.gate_expires_at'))) {
        abort(403);
    }
    return app(\TomatoPHP\FilamentDeveloperGate\Http\Middleware\DeveloperGateMiddleware::class)
        ->handle($request, $next);
}

Layer MFA in front of the gate when the panel is internet-facing — Fortify/verified before the gate, gate before panel auth.
Environment-scoped enabling via the package config keeps the panel provider clean and lets ops flip the gate per environment without a deploy.
Custom redirect targets are config-driven; point them at an onboarding page or a "you're in demo mode" notice instead of the dashboard if developers need context on entry.

Filament Developer Gate Laravel Package