Nova Actor Laravel Package

Getting Started

visanduma/nova-actor is a Nova tool that lets you swap the authenticated user from within the Nova UI — meant for local/staging work, not production. It saves you from logging out and back in (or juggling password managers) while you click through role-specific screens.

Minimal setup:

composer require visanduma/nova-actor --dev

Then register the tool in app/Providers/NovaServiceProvider.php:

public function tools()
{
    return [
        new \Visanduma\NovaActor\NovaActor(),
    ];
}

If the package ships a config file, publish and read it first:

php artisan vendor:publish --provider="Visanduma\NovaActor\NovaActorServiceProvider"

Where to look first:

1. vendor/visanduma/nova-actor/src/ — the tool class and any config. Confirm exactly which model/guard it switches (usually config('auth.providers.users.model') and the default guard) before wiring anything else.
2. config/nova-actor.php (if published) — the user model, search columns, and any environment allow-list.
3. php artisan route:list | grep -i actor — confirms the switch endpoint is registered and under which middleware.

First use case: seed a handful of dev users with distinct roles (admin, editor, viewer, plus one "empty state" user), then flip between them from the Nova navbar to verify each role sees the right resources, fields, and policies. Keep those users in a dedicated DevUserSeeder so every teammate gets the same shortcut.

Implementation Patterns

A dedicated dev-user seeder as the contract. The tool is only as useful as the users it can list. Treat the seeder as part of your onboarding:

// database/seeders/DevUserSeeder.php
User::firstOrCreate(['email' => '[email protected]'], [
    'name' => 'Dev Admin',
    'password' => Hash::make('password'),
])->assignRole('admin');

Role matrix, not ad-hoc switching. The highest-value workflow is QA: switch to each role in order and confirm the resource index, form, and action buttons change correctly. This catches policy/Nova::resources()-level regressions that unit tests miss.

Environment gate as a hard requirement. Wrap registration so it can't sneak into production:

public function tools()
{
    return array_filter([
        app()->environment(['local', 'staging'])
            ? new \Visanduma\NovaActor\NovaActor()
            : null,
    ]);
}

Pair that with composer require --dev so the package isn't even installed in prod builds.

Combine with factories for state, not just identity. Switching users changes who you are; it doesn't change what exists. Seed each dev user with representative data (0 records, 1 record, 500 records) so you test pagination and empty states along the way.

Use it as a debugging aid for "works for admin, breaks for member" bugs. When a report says "the button is missing for regular users," switch, reproduce, and inspect the policy output in the same session — faster than logging out and losing your place.

Keep the list short. If the tool auto-lists all users, it will be unusable once your DB has thousands. Prefer an explicit list (env var of emails, or a is_dev_user flag) so the dropdown stays focused.

Gotchas and Tips

• It almost certainly bypasses passwords. That's the point, but it means a misconfiguration in production is an account-takeover primitive. Verify the middleware/route guard and the environment check; don't rely on one alone.
• Guard mismatch is the classic failure. If your Nova guard or provider differs from web/default, the switch may log you in on the wrong guard and nothing appears to change. Confirm the guard the tool uses matches config('nova.guard').
• Policies and cached permission state. If you use spatie/permission or a cached policy registrar, a switch within the same process may show stale abilities. Clear the cache or ensure the tool regenerates the session on switch.
• Session regeneration. A proper switch should regenerate the session ID (like a fresh login). If your app stores "current org" or "impersonator" in the session, clear those keys or you'll carry state from the previous user.
• Remember-me tokens and 2FA are not modeled. A user with 2FA enabled won't be challenged, and the "remember" cookie won't be set. Don't use this to validate your auth flow — only to validate authorization and UI per role.
• It won't help with API/Sanctum testing. Tokens are separate from the session-based switch. For API work, issue a token for the target user instead.
• Extension point: if the dropdown lists the wrong set or the wrong model, that's usually the one knob worth overriding — a config array of allowed user IDs/emails, or a small subclass that overrides the query. Check the tool class for a users()/options() method before forking.
• Debugging "tool doesn't appear": run php artisan nova:publish if assets are involved, check Nova::tools() actually returns it (dd the array), and confirm you're on a Nova version the package supports — with 0 dependents and a sparse repo, compatibility with Nova 4/5 is the first thing to verify by reading composer.json in the package.
• Abandonment risk. Zero stars/dependents means no community safety net. Read the whole src/ (~a few files) before adopting; if it's more than ~150 lines, consider reimplementing the switch endpoint yourself as a Nova tool — it's a small, well-understood surface and you'll own the security boundary.