Download the PHP package cdoebler/doppelganger without Composer

Doppelganger

A WordPress integration for the php-generic-user-switcher package. This plugin allows authorized administrators to instantly switch their session to any other user on the site, which is useful for debugging issues reported by specific users or testing role capabilities.

Features

• Seamless Integration: Works out-of-the-box with WordPress authentication system.
• Configurable: Customize permissions, UI position, and behavior through WordPress filters.
• Environment Control: Restrict user switching to specific environments (e.g., local, development) to prevent accidents in production.
• Cookie-based Impersonation: Securely impersonates users by maintaining the original user's ID in a signed cookie.
• Persistent Authorization: Switcher remains visible when impersonating less-privileged users, allowing easy switching back.

Requirements

• PHP 8.2 or higher
• WordPress 6.8 or higher
• Composer

Installation

Right now, the WordPress plugin is not available on the WordPress plugin repository because of unsupported PHP keywords in the plugin's code but it will be released once the PHP keywords are accepted by WordPress.

You can still install the plugin manually by downloading a zip archive from the Releases page and installing it in the WordPress backend or by using Composer.

Installation via Composer:

Ensure your site is configured to load the vendor/autoload.php file, or activate the plugin if it's placed in wp-content/plugins and installed with dependencies.

Usage

1. Log in as an Administrator. By default, only users with the edit_users capability (typically Administrators) can see and use the switcher.

2. Switch User

   • Look for the "Switch User" toggle in the bottom-right corner of the screen.
   • Click it to open the user list.
   • Click on any user to switch to their account.

3. Impersonation Mode

   • While impersonating, a "Stop Impersonating" banner/button will be visible.
   • You are effectively logged in as that user, with their permissions.
4. Stop Impersonating
   • Click "Stop Impersonating" to return to your original administrative account.

Configuration

The plugin is designed to work out-of-the-box, with three layers of configuration (in order of precedence):

1. Default Behavior - Works immediately after installation
2. wp-config.php Constants - Simple toggles for non-technical users
3. WordPress Filters - Advanced customization for developers

Default Behavior

Out of the box, the plugin:

• Enabled: Yes (active in all environments)
• Environments: All environments (* wildcard)
• Authorization: Users with edit_users capability (typically Administrators)

Simple Configuration (wp-config.php Constants)

For basic on/off toggles and environment control, add constants to your wp-config.php file:

Important: Constants take precedence over filters. If a constant is defined, filters for that setting will be ignored with a warning in debug mode and the WordPress admin dashboard.

⚠️ Development Mode (EXTREMELY DANGEROUS)

🚨 CRITICAL SECURITY WARNING:

When DOPPELGANGER_DEV_MODE is enabled:

• ✅ ALL users can switch to ANY account (including administrators)
• ✅ Even guests (not logged in) can use the switcher
• ✅ Bypasses environment restrictions
• ✅ Bypasses authorization checks
• ✅ Bypasses ALL security measures

This constant is ONLY for:

• Local development and debugging
• Testing user permission flows
• Reproducing user-reported issues

NEVER EVER:

• ❌ Use this in production
• ❌ Use this in staging (unless absolutely necessary and temporarily)
• ❌ Commit this to version control
• ❌ Leave it enabled after debugging

A persistent red warning banner will appear in the WordPress admin dashboard when dev mode is active. If you see this warning in production, disable dev mode immediately by removing the constant from wp-config.php.

Note: The main DOPPELGANGER_ENABLED=false constant still works as an emergency kill switch even when dev mode is active.

Advanced Configuration (WordPress Filters)

For complex logic and dynamic behavior, use WordPress filters in your theme's functions.php or a custom plugin:

Environment Control

Note: This filter is ignored if DOPPELGANGER_ALLOWED_ENVIRONMENTS constant is defined.

Permissions (Authorization)

By default, edit_users capability is required. You can change this logic:

How Authorization Works During Impersonation

Important: When you're impersonating another user, authorization checks are based on the original user (the one who started impersonation), not the currently impersonated user.

This means:

• If an admin switches to a regular user, the switcher widget remains visible
• The admin can continue switching to other users
• Authorization is always checked against the original admin, not the impersonated user

This prevents the common issue where the switcher disappears after switching to an unauthorized user.

Example Scenario:

1. Admin (authorized) logs in → Widget appears ✅
2. Admin switches to Regular User (unauthorized) → Widget still appears ✅
3. Admin can switch back or to other users ✅
4. Regular User logs in directly → Widget does not appear ✅

UI Configuration

Customize the renderer configuration:

Available configuration options:

• position: Widget position on screen (bottom-right, bottom-left, top-right, top-left)
• param_name: URL parameter name for switching (default: doppelganger_switch)
• current_user_id: Current user ID (automatically set, usually don't override)

Database Options (Alternative to Constants)

The plugin also checks a database option for the enabled state. This is useful if you need to toggle the plugin programmatically:

Note: The DOPPELGANGER_ENABLED constant takes precedence over this database option.

Security

• Return Ticket: When switching, a secure cookie is set containing the original admin's ID. This cookie is signed using wp_hash() with a nonce salt to prevent tampering.
• Validation: Authentication cookies are re-issued securely using WordPress core functions.

Development

To run static analysis and code quality checks: