automator_user_role_changed

Description

Usage

add_action( 'automator_user_role_changed', 'your_function_name', 10, 3 );

Parameters

$user_id (mixed)

The user ID of the user whose role has been changed.

$role (mixed)

The ID of the user whose role has been changed.

$old_roles (mixed)

This parameter contains the new role assigned to the user.

Examples

// Example: Log the user role change to a custom log file.
add_action( 'automator_user_role_changed', 'log_user_role_change', 10, 3 );

/**
 * Logs changes to user roles.
 *
 * This function is triggered when a user's role is changed. It records the user ID,
 * the new role, and the previous roles to a custom log file for auditing purposes.
 *
 * @param int    $user_id    The ID of the user whose role was changed.
 * @param string $role       The new role assigned to the user.
 * @param array  $old_roles  An array of the user's roles before the change.
 */
function log_user_role_change( $user_id, $role, $old_roles ) {
    $user = get_user_by( 'id', $user_id );
    if ( ! $user ) {
        return;
    }

    $log_message = sprintf(
        'User Role Changed: User ID: %1$d, Username: %2$s, New Role: %3$s, Old Roles: %4$s',
        $user_id,
        $user->user_login,
        $role,
        implode( ', ', $old_roles )
    );

    // In a real-world scenario, you would likely use a more robust logging solution
    // or a dedicated plugin for this. For this example, we'll just write to a file.
    $log_file_path = WP_CONTENT_DIR . '/user-role-changes.log';
    $current_time = current_time( 'mysql' );
    file_put_contents( $log_file_path, "[{$current_time}] {$log_message}n", FILE_APPEND );
}

Placement

This code should be placed in the functions.php file of your active theme, a custom plugin, or using a code snippets plugin.

Source Code

src/integrations/wp/helpers/wp-helpers.php:1049
src/integrations/wp/helpers/wp-helpers.php:1077

public function handle_add_user_role( $user_id, $role ) {
		// If this role was removed earlier in the same request and is now being
		// re-added, the net result is no change. Consume the pending entry and bail.
		// This prevents false positives from plugins that do a remove-then-re-add
		// sync on every profile save (e.g. User Role Editor).
		if ( isset( self::$pending_role_removals[ $user_id ][ $role ] ) ) {
			unset( self::$pending_role_removals[ $user_id ][ $role ] );
			return;
		}

		$user = get_user_by( 'ID', $user_id );
		if ( ! $user ) {
			return;
		}

		// WordPress saves the updated caps before firing this hook, so $user->roles
		// already includes the new role. Reconstruct old_roles by subtracting it.
		$old_roles = array_values( array_diff( $user->roles, array( $role ) ) );

		do_action( 'automator_user_role_changed', $user_id, $role, $old_roles );
	}