Nova Impersonating Banner Laravel Package

Getting Started

• Install the release that matches your stack. v3.2.0 is the first line with Laravel 12 support, so it is the version to require on a Laravel 12 / Nova 5 app:

  composer require rhyslees/nova-impersonating-banner:^3.2
  

  On Laravel 10/11 you can stay on ^3.1 until you upgrade; v3.2.0 is additive (framework support), so it is a safe drop-in either way.
• Register the tool with Nova. The package is a Nova tool, so the first place to look is app/Providers/NovaServiceProvider.php — add it to tools() if your Nova version requires explicit registration, then check nova-components assets are published (php artisan vendor:publish --tag=nova-impersonating-banner or nova:publish) and run php artisan optimize:clear.
• First use case: impersonate a user in Nova (via Nova's impersonation action or your impersonation driver), confirm the banner renders at the top of the Nova layout, and click through to stop impersonating. That single loop — impersonate, see banner, stop — is the whole value proposition; verify it on a staging user before shipping to the team.
• Read first: README.md for the publish tags/config keys, src/ for the tool class and service provider (that's where banner visibility is decided), and resources/js for the Vue banner component. If the banner is conditional, the condition lives in the service provider or the tool's render/boot path, not in the Vue file.

Implementation Patterns

• Provider-level registration is the standard pattern. Register the tool once in NovaServiceProvider::tools(); do not render the banner manually in layout.blade.php. Keeping it as a Nova tool means it survives Nova upgrades and gets picked up by Nova's asset pipeline automatically.
• Customise the banner copy in one place. Most teams override the banner text (e.g. "You are impersonating :name — Stop") and the colour (warning/red) rather than accept the default. Put the override behind a published config or a small Blade/Vue partial so an upgrade of the package does not clobber it. Add translations via lang/vendor/... if you support more than one locale.
• Pair it with your impersonation entry point. If impersonation is triggered from a custom Nova action or a "Login as user" button, make the two share a single source of truth (the session key / impersonator ID). The banner is only as reliable as the flag it reads.
• Use it as the guardrail in support workflows. The practical pattern is: support staff impersonate → banner is always visible → "Stop impersonating" returns them to their own admin session. Document that flow in your runbook so nobody accidentally demos a customer's account and forgets they are still impersonating.
• CI matrix. With v3.2.0 in play, add Laravel 12 / Nova 5 to your test matrix and keep a job on Laravel 11 / Nova 4 while you migrate. If you extend the tool with your own assertions, test that the banner appears only when an impersonation flag is set — a missing banner is a silent security/UX failure, not a loud one.
• Keep it out of API-only contexts. The package is Nova-UI-only; it will do nothing for impersonation performed through web routes outside Nova. If you also impersonate from a non-Nova admin panel, you need a separate banner there.

Gotchas and Tips

• Version pinning during the Laravel 12 upgrade. The failure mode people hit is Composer resolving an older 3.x that does not declare Laravel 12 support. Require ^3.2 explicitly, and run composer why-not rhyslees/nova-impersonating-banner if the install blocks.
• Stale published assets. After upgrading, run php artisan nova:publish and clear compiled views/config (optimize:clear). A banner that "disappeared" after a version bump is very often a cached manifest or an unpublished JS bundle, not a code regression.
• Custom Nova layouts. If you have overridden Nova's layout Blade file, the tool may be registered but never rendered. Check whether your layout still includes the tool/banner slot.
• Guard and session mismatches. The banner reads the impersonation state from the session and the active guard. Impersonating across guards (e.g. web admin impersonating an api/tenant user) or with different session drivers per environment is the usual cause of "works locally, not in staging."
• Logout/impersonation-stop redirect. Verify where "Stop impersonating" lands after the upgrade — a redirect that assumes nova.login or a hard-coded route will break if you've customised Nova's path or added a tenancy prefix.
• Debugging order: (1) php artisan about to confirm Laravel/Nova versions, (2) confirm the tool is in NovaServiceProvider::tools() and appears under Nova's tools list, (3) check the browser network tab for the tool's JS asset 404, (4) only then dig into the session flag.
• Extension points are limited by design — treat the Vue component and the Blade/config overrides as the supported surface. If you need extra behaviour (audit logging of impersonation start/stop, an impersonation expiry), hook it in your own action/middleware rather than forking the package; a fork will bite you on the next Laravel major.