User Plugin Laravel Package

Getting Started

composer require rainlab/user-plugin
php artisan october:up   # runs the new migration automatically

The v3.7 migration is applied on upgrade with no manual steps, and both new activation policies default to off, so an existing site behaves exactly as before until you opt in.

Where to look first:

1. Settings area — the two new independent checkboxes: require email confirmation and require admin approval. They can be combined.
2. Users page → new "Manage" toolbar — import/export live here.
3. User preview page — per-user approve action; bulk approve is on the list view.
4. Plugin documentation → "Action Manager" page — full method reference for the headless API.

First use case — a headless registration endpoint: enable require admin approval, then replace a form handler with ActionManager:

use RainLab\User\Classes\ActionManager; // verify exact namespace in the plugin's classes/ dir

$user = ActionManager::instance()->registerUser([
    'first_name' => 'Some',
    'email'      => '[email protected]',
    'password'   => 'ChangeMe888',
]);

The user lands in the pending state, the normal rainlab.user.register event fires, and an admin approves from the backend — no component logic duplicated in your API layer.

Implementation Patterns

ActionManager as the single workflow entry point. Every user flow (registration, sign-in, password recovery, profile update) is exposed, so a REST/GraphQL controller becomes a thin translation layer:

public function store(Request $request)
{
    try {
        $user = ActionManager::instance()->registerUser($request->only([
            'first_name', 'last_name', 'email', 'password',
        ]));

        return response()->json(['id' => $user->id], 201);
    } catch (ValidationException $e) {
        return response()->json(['errors' => $e->errors()], 422);
    }
}

Because policies are enforced at sign-in, the same rules cover browser logins and API logins — you do not need a separate approval check in your controller.

Pending-state UX via the redirect property. The redirect property is back on the Authentication and Registration components. Use it to send pending users to a "your account is awaiting approval" page instead of leaving them on a generic error, and to post-login route API-driven users to the right place.

External app URLs for recovery/verification. Point password-reset and email-verification links at your SPA or mobile deep link. All customary events keep firing, so existing listeners for rainlab.user.register, activation, and password reset continue to work.

Import/export as an onboarding tool. Import supports email matching to update existing users, automatic group creation, and group assignment — useful for migrating from another platform or bulk-provisioning a client's team. Export deliberately omits password hashes and secrets, so it is safe to hand to a client (still review for PII/compliance).

Presence via rainlab.user.seen. New event for "came online". Use a queued listener to flip an is_online flag or push to a dashboard rather than doing synchronous writes in the request cycle.

Tailor fields. Custom user fields now honor tab and span, so you can group profile fields into logical tabs in the backend form without a custom form definition.

Gotchas and Tips

• Enabling a policy later locks out existing users. Both default off, so upgrading is safe — but the moment you tick "require email confirmation", every already-registered, unverified user is blocked at sign-in. Backfill email_verified_at (or run a one-off verification) before flipping the switch.
• Email verification is a side effect of password reset now. Completing a reset from an email link verifies the address. That is usually desirable, but it means a user can become "verified" through recovery without ever clicking a verification link — account for this if verification gates anything.
• Bulk approve is irreversible from the UI. Filter the list carefully before using it; there is no bulk "un-approve".
• Import is destructive by design when matching on email. Test with a 2–3 row file first, and confirm what "automatic group creation" does with near-duplicate group names.
• ActionManager::instance() is a singleton. Treat it as stateless per request; don't stash component or request state on it between calls.
• Validation failures throw. Wrap every ActionManager call in try/catch and map ValidationException to 422 — otherwise headless clients get a 500.
• redirect returning can surprise you. An empty or malformed value may fall back to the default landing page; set it explicitly per component instance rather than globally.
• rainlab.user.seen fires per online transition, which on a busy site is frequent. Throttle or queue the listener; avoid heavy queries there.
• Debugging: log inside an event listener first (all workflows still fire events) before reaching for ActionManager internals; check storage/logs and run php artisan october:up after deployment to confirm the migration.
• Tailor tab/span affect backend form layout only — they do not change frontend rendering or validation.