Laravel Impersonate Laravel Package

Getting Started

• Confirm compatibility before upgrading: v5 requires PHP 8.2+ and Laravel 12.x / 13.x. If the app is on an older Laravel version, either stay on v4.x or plan the framework upgrade first.
• After upgrading, update both .env and any published config:
  • IMPERSONATE_ENABLED → IMPERSONATE_UI_ENABLED
  • IMPERSONATE_WIDTH → IMPERSONATE_UI_WIDTH
  • IMPERSONATE_DELAY → IMPERSONATE_UI_DEBOUNCE
  • impersonate.enabled → impersonate.interface.enabled
• Add the HasImpersonation trait to the model that should be impersonatable. v5 provides usable defaults: display text is $this->name and search field is ['name'], so basic usage needs no trait overrides.
• Define scopeImpersonatable() on that model. This is now the required place to enforce who can be searched and impersonated at the database level:

public function scopeImpersonatable($query)
{
    return $query->where('is_active', true);
}

• First use case: enable the UI with IMPERSONATE_UI_ENABLED=true, define the impersonation scope, then use the widget to search within the scoped user set. For backend/admin flows, use the fluent shortcut:

Impersonate::loginAs($user);

• Look first at the package config’s interface block, the HasImpersonation trait, the model’s scopeImpersonatable() method, and the /_impersonate/users and /_impersonate/login endpoint authorization behavior.

Implementation Patterns

• Scope-first authorization: Treat scopeImpersonatable() as the primary guardrail for search results and impersonation eligibility. Use it for tenant boundaries, active flags, role checks, or organization constraints rather than filtering in PHP after the query.
• Pagination-safe filtering: Because v5 applies impersonation filtering as a query scope, paginated results and .total() values stay accurate. Avoid reintroducing in-memory filtering around package queries.
• Trait defaults with targeted overrides: Basic models can rely on the default display and search fields. Override getImpersonateDisplayText() or getImpersonateSearchField() only where the UI should show or search different columns.
• Laravel 11+ scope style: Use either traditional scopeImpersonatable() methods or Laravel’s #[Scope] attribute convention, depending on the model’s existing style.
• Backend impersonation workflows: Use Impersonate::loginAs($user) when an admin action, console command, or internal tool needs to impersonate without explicitly resolving/passing the impersonator. Keep the surrounding controller/action authorized as you would any sensitive admin operation.
• UI integration: v5 is vanilla JS/CSS only. If the app previously customized Select2/jQuery behavior or styled table-based markup, move those customizations to the new flexbox-based widget and plain JS/CSS hooks.
• Endpoint security: The API endpoints now return 403 Forbidden for unauthorized access. Ensure your normal auth middleware and app-level authorization policies still wrap or complement these routes as needed.

Gotchas and Tips

• Breaking config/env renames: Upgrading without renaming env keys can leave the UI disabled or using stale settings. Also update published config files if impersonate.enabled was moved under impersonate.interface.enabled.
• In-memory filtering is removed: v4-style ImpersonateCollection filtering no longer happens after query execution. If scopeImpersonatable() is missing or too broad, the searchable/impersonatable set may be broader than intended.
• Minimum requirements are hard breaks: PHP below 8.2 or Laravel below 12.x will not work with v5. Check CI and production runtime versions before merging the upgrade.
• Clear config cache after changes: Run php artisan config:clear after updating .env or config files, especially when debugging why IMPERSONATE_UI_* settings are not taking effect.
• UI debounce rename: IMPERSONATE_DELAY is now IMPERSONATE_UI_DEBOUNCE; do not assume the old delay key still controls search debounce behavior.
• Custom UI assets may need rework: Removing jQuery and Select2 is good for footprint but can break local overrides that relied on those libraries or on the old table layout.
• Error handling is cleaner, not silent: Repository queries now wrap structural failures in ImpersonateException. If you customize endpoints or repositories, catch/report that exception rather than expecting raw database errors.
• Extension points to lean on: model scope for eligibility, trait methods for display/search behavior, config under impersonate.interface for UI state, and Impersonate::loginAs() for controlled backend impersonation.