Filament Spotlight Laravel Package

Technical Evaluation

Architecture fit. This is a UI-layer plugin for Filament v5 panels, not a domain package. It adds a command palette (Cmd/Ctrl+K) on top of the existing admin panel by composing pluggable SpotlightSource implementations into a single result set. Architecturally that is a good fit for any Laravel application already standardised on Filament for back-office surfaces: it is additive, sits behind a panel plugin registration, and does not touch models, policies, or routing conventions. If the estate is not on Filament v5 — Blade-only, Inertia/Vue, or an older Filament major — this is effectively out of scope rather than "adaptable," because the palette derives its value from resolving Filament resources, pages, and row actions.

Integration feasibility. Low-to-moderate effort and low blast radius. Installation is a single Composer require plus two publish steps (config and the spotlight_recents migration) and one plugin registration in the panel provider. The extension surface is the strongest part of the release: the SpotlightSource contract and Result DTO give us a clean seam to expose domain commands ("open order #1234", "create invoice", "jump to customer") without forking. The Handler factory with same-origin and scalar-payload validation is a sensible guardrail and materially reduces the usual risk that a palette becomes an ad-hoc XSS or open-redirect vector.

Technical risk. The dominant risk is version posture: v0.1.0 is pre-1.0, so under semver the minor line may carry breaking changes to the SpotlightSource contract, Result DTO, and config schema — exactly the surfaces we would build custom sources against. Second is Filament v5 coupling: we inherit Filament's own release cadence and upgrade windows, and this package will lag. Third is the JavaScript/event handler path (event, callback handlers), which is the least statically verifiable part of the surface and needs a code review plus a CSP review before we allow any handler beyond url. Fourth is that "WCAG 2.1 AA" is a maintainer claim, not an audit; keyboard-first design helps but combobox semantics and focus management need independent verification. Fifth is a single-maintainer bus factor.

Key questions. What PHP and Laravel minimums, and which exact Filament v5 minor, is the package tested against in CI? Is there a published upgrade policy or deprecation window before 1.0? Does FilamentResourceSource reuse Filament's existing global search (and therefore its policy/tenancy scoping), or does it run its own queries? How is permission re-validation on recents implemented — at render time per result, or cached per session? What is the per-keystroke query cost of global search on our largest resource, and is there debouncing or a result cap? Which locales ship, and what is the path to add ours (en + vi only today)? Are callback and event handlers compatible with a strict CSP, and is there an allowlist mechanism? What is the recents retention and eviction policy concretely, and does it hold PII (search terms can contain customer names)?

Integration Approach

Stack fit. Target: Laravel application on Filament v5, PHP version per the package's composer constraints, MySQL/Postgres for the recents table. Do not attempt on Filament v3/v4 panels — the plugin targets v5 panels specifically. Where a team has both an older and a newer panel, treat this as greenfield on the v5 panel only.

Migration path. Purely additive. No changes to existing resources, pages, or policies are required to get the NavigationSource and FilamentResourceSource working. The only schema change is a new spotlight_recents table. Rollback is clean: unregister the plugin, optionally drop the table; no existing behaviour depends on it. Custom sources we write will depend on the contract, so keep them in a separate namespace with their own tests to make a future contract change a contained fix.

Compatibility. Pin the dependency precisely for the pilot (0.1.* or a committed lockfile) rather than floating ^0.1, and gate any Filament upgrade behind a re-run of the palette smoke tests. Verify the spotlight_recents migration against our migration conventions (naming, index strategy on user_id, any tenant column requirement). Confirm the package's config file does not collide with existing config keys and that published config is committed to VCS so drift is visible in review.

Sequencing. (1) Timeboxed spike on a staging panel: install, publish, migrate, register plugin, confirm Cmd/Ctrl+K and accessibility baseline. (2) Security and CSP review of the Handler factory and the event/callback path. (3) Accessibility verification of the combobox pattern with a screen reader and keyboard-only pass, plus mobile bottom-sheet check. (4) Ship NavigationSource alone behind an env/feature flag to a small internal cohort. (5) Enable FilamentResourceSource after measuring search latency against the largest resource and confirming policy scoping. (6) Build one or two custom domain sources as a proof of the extension model. (7) Broad rollout with a documented fallback (flag off) and a user-facing note on the shortcut.

Operational Impact

Maintenance. Budget for ownership, not just adoption: pinning versions, re-testing on every Filament upgrade, and reviewing each pre-1.0 minor for contract changes. Committing the published config and any custom sources to our repo keeps the upgrade surface visible. Confirm whether we are consumers only or will need to carry a fork; assume fork readiness given the single-maintainer profile.

Support. Documentation is README/CHANGELOG-tier with no SLA. Expect no upstream support commitment; the internal owning team is the first line. That is acceptable for an admin-panel affordance, not for a customer-facing surface.

Scaling. Two scaling axes. Data: recents are per-user with LRU eviction, so row growth is bounded by user count × cap — fine, provided user_id is indexed and tenant scoping (if multi-tenant) is enforced on write and read. Query cost: global search fires per keystroke across resources; on large tables this is the most likely performance regression in the whole package. Mitigate with debouncing, a hard result cap, and role-based source limiting so low-privilege users do not fan out across every resource. Mobile bottom-sheet and dark mode are cosmetic from an ops standpoint.

Failure modes. Most likely: migration not run in an environment → palette throws on load, which can degrade the whole panel if not isolated — verify the palette fails soft. A misbehaving custom source throwing an exception could take down the result set; ensure per-source error isolation and a timeout. A stale or over-broad recents entry could surface a resource the user has since lost access to — the release notes claim permission re-validation, so test the exact scenario of a role downgrade mid-session. Event/callback handlers blocked by CSP would silently no-op. Shortcut collision: Cmd/Ctrl+K is browser-intercepted in some browsers, so users may get inconsistent behaviour and need a documented alternative. Finally, stale recents containing customer names or identifiers is a data-retention and privacy question that should be answered before enabling for anyone touching regulated data.

Ramp-up. Very low for developers — one plugin registration and a documented contract; a Filament-fluent engineer is productive in under a day, and writing a first custom source is a few hours. The real ramp-up is change management for admin users: a new keyboard-first interaction model needs a short announcement, a discoverable affordance in the UI, and a feedback loop. Accessibility gains (keyboard-only navigation, labeled controls, screen-reader semantics) partly offset that cost, but only once verified rather than assumed.