Escalated Filament Laravel Package

Getting Started

1. Upgrade escalated-laravel first. This plugin release requires escalated-dev/escalated-laravel ^1.9.0; follow that package's upgrading notes (frontend 0.12, migrations, private attachments, verified guest access, requester-only inbound email replies, tenant staff seats) before touching the panel package.
2. Update the panel package to v1.4.0 and clear caches (php artisan optimize:clear).
3. Define the gates before deploying. By default the panel checks escalated-agent and escalated-admin. If you use custom names, pass them to the plugin; otherwise define the defaults in a service provider and grant them to your support staff.
4. Look first at the README "Access control" section and Support\PanelAccess / Support\StaffSeat — they are the authoritative answer to "why can't this user see the panel?"
5. First use case: an agent signs in, sees Tickets, Canned Responses and the Support Dashboard; an admin additionally sees webhooks, API tokens, roles, automations, macros, skills, custom fields, KB articles, newsletters, reports and settings.

Minimal gate wiring:

// AuthServiceProvider::boot()
Gate::define('escalated-agent', fn (User $user) => $user->hasRole('support'));
Gate::define('escalated-admin', fn (User $user) => $user->hasRole('support-admin'));

// Panel provider
->plugin(
    EscalatedPlugin::make()
        ->agentGate('escalated-agent')
        ->adminGate('escalated-admin')
)

Implementation Patterns

Grant through your existing role/permission system. Keep the gate names thin and delegate to whatever you already use (Spatie permissions, Bouncer, custom flags) so the panel and the rest of your app stay in sync.

Treat the two gates as tiers. Agent gate covers tickets, canned responses and the support dashboard; admin gate covers everything else. A user with only the agent gate should never be given admin-gate roles "just in case" — they will see no admin navigation and get 403s on direct URLs.

Layer policies on top, not instead of. Existing escalated-laravel model policies still apply on top of the gates. Use policies for per-record rules (for example, an agent may only edit their own canned responses), and the gates for coarser "can this person be in the panel at all" decisions.

Tenant mode requires a seat in the current account. With escalated-laravel tenancy enabled, passing the global gate is not enough: StaffAccess checks the host gate plus TenantResolver::isAgent/isAdmin for the current tenant. Make sure your tenant provisioning flow creates a staff seat, otherwise users silently disappear from the API token owner picker and skill agent picker.

Test access the same way your users hit it. Use actingAs($agent)->get(TicketResource::getUrl()) and assert 200/403, plus assertDontSee for the navigation. Exercise Gate::forUser($user)->allows('escalated-admin') in isolation before blaming the panel.

Audit before you deploy. Iterate over every user who can currently sign in to the panel and log which gate they pass. Anyone passing neither will lose access at upgrade time — this is the single most important pre-flight check.

Customise by extension, not by editing vendor code. Override resources/pages in your app namespace, keep gate names configurable at the plugin level, and bind or decorate StaffAccess if your tenancy model differs.

Gotchas and Tips

• The gates were documented but never read before v1.4.0. Anything without an escalated-laravel model policy was effectively open to any authenticated panel user. Assume your current access control is weaker than you think and audit it.
• This is a silent breaking change, not a warning. Users without either gate get a 403 and lose all Escalated navigation immediately after deploy. Roll out gate assignments first, package update second, or do both in the same window with a tested rollback.
• Watch out for Gate::before super-admin bypasses. A global Gate::before returning true for super admins will happily grant both escalated gates and defeat the point — confirm that is intentional.
• Custom gate names must match in both places. If you pass names to the plugin, define exactly those names; a typo produces a 403 that looks like a role problem. Support\PanelAccess resolves the names — check it when debugging.
• Tenant mode fails closed on the seat, not the gate. A user with the global flag but no seat in the current account is refused and omitted from pickers. This is by design; fix provisioning, not the gate.
• Existing policies still run after the gates. A passing gate plus a false policy is still a denial. Debug both layers separately.
• Order of upgrades matters. Installing the panel package before finishing the escalated-laravel 1.9 upgrade (migrations, private attachments disk/visibility, frontend 0.12) will leave you with a broken or half-migrated panel.
• Private attachments may need a disk and authorization changes — verify file downloads as an agent and as an outsider after upgrading.
• Test suite on Filament 5.7 / Livewire 4.4: the vendor patch script for Livewire's ViewErrorBag now matches 4.4 as well as 4.3. If tests fail unexpectedly after a dependency bump, re-run the patch script before debugging your own code.
• Navigation hiding is not authorization. Direct URLs are now gated too — do not rely on menu visibility in your own custom pages; add explicit gate checks.