Sudo Su Laravel Package

Getting Started

Upgrading or installing 1.1.0 requires one manual step that did not exist before: the package no longer injects its markup and assets into every response. You must render the user selector yourself from your application layout.

1. Require the package and publish its config/assets as usual:

   composer require .../sudosu
   php artisan vendor:publish --tag=sudosu-config
   php artisan vendor:publish --tag=sudosu-assets
   

2. Add the partial to your layout — typically at the end of <body>, after your own scripts:

   @if (env('APP_DEBUG'))
       @include('sudosu::user-selector')
   @endif
   

3. Clear compiled views so the old auto-injected output doesn't linger:

   php artisan view:clear
   

First use case: open any page in your app in local, confirm the selector renders, and switch into another user to reproduce a bug as that account. If the selector is missing after upgrading, the include is almost always the cause (see Gotchas).

Where to look first: the package config (config/sudosu.php) for the authorization callback, route/middleware settings, and any guard restrictions — then resources/views/vendor/sudosu/user-selector.blade.php if you need to restyle it.

Implementation Patterns

Wrap the include, don't trust APP_DEBUG alone. APP_DEBUG is a debugging flag, not an authorization boundary. Use the package's authorization check (or a Gate) so the selector and the impersonation endpoints are both gated:

@can('impersonate-users')
    @if (config('app.debug'))
        @include('sudosu::user-selector')
    @endif
@endcan

Prefer a dedicated layout for internal/staff pages. Including the selector in a single admin layout limits blast radius and avoids shipping the partial into customer-facing or email templates that happen to share a base layout.

Guard against double inclusion. If your layout is composed of components that can each render, wrap the include so assets aren't emitted twice:

@once
    @include('sudosu::user-selector')
@endonce

Keep the partial out of full-page cached responses. If you use response caching or @cache-style Blade directives, exclude the block containing the selector, otherwise a cached page can serve a stale or unauthorized selector to the wrong user.

Pair with a restore path. The day-to-day workflow is impersonate → reproduce/fix → return to your own account. Make sure the package's "exit impersonation" affordance is reachable from the layout you added the selector to; if it lives only in the selector partial, removing the partial (e.g. in a different layout) also removes your way back.

Test the conditional. A cheap feature test asserting the selector is absent on a public page and present on the gated page catches both the "forgot the include" and "leaked to production layout" failure modes.

Gotchas and Tips

The 1.1.0 upgrade is silently breaking. Because the package no longer injects anything, an upgrade produces no error — the selector simply vanishes. Pin the version, upgrade deliberately, and add the include in the same commit. If teammates report "the package is broken," check the layout first.

env('APP_DEBUG') in Blade is a trap. Once you run php artisan config:cache, the .env file is no longer loaded at runtime and env() calls outside config files return null. The release note's snippet will therefore evaluate false in a config-cached environment and hide the selector. Use config('app.debug') instead:

@if (config('app.debug'))
    @include('sudosu::user-selector')
@endif

This is the single most likely source of "it works locally, not on staging."

Assets are no longer global. Anything that relied on the package's previously auto-injected CSS/JS — custom styling, a bespoke button that hooked into its classes, an end-to-end test asserting a DOM node exists on every page — needs updating. The partial is now the sole source of those assets, so any page without the include has no styles.

Stale view cache masks the change. If the selector still appears to be auto-injected (or still absent after adding the include), run php artisan view:clear and, in containerized setups, rebuild rather than relying on a bind-mounted compiled-views directory.

Don't include it in error pages. Exception/error layouts render outside your normal middleware stack; the authorization gate may not have run, so the selector can leak on a 500 page. Keep the include confined to the authenticated layout.

Semver caveat. A behavior removal of this size shipped as 1.1.0 rather than 2.0.0. Treat minor bumps of this package as potentially breaking and read the notes before running composer update.

Extension point. The partial is publishable — override it (resources/views/vendor/sudosu/user-selector.blade.php) to restyle or to attach the impersonation action to your own header component rather than shipping the package's default chrome. Publishing keeps you insulated from future markup changes; the include path stays stable.