How to Add User Impersonation to a PHPRunner Application

PHPRunner’s Security API lets an administrator switch to another application user without knowing that user’s password. This is useful when an administrator needs to reproduce a problem using the same pages, permissions, and data access as the user.

In this tutorial we will add an impersonation button to the login table, switch accounts with Security::loginAs(), display a warning banner while impersonation is active, and provide a link that restores the original administrator session.

We will cover:

1. Preparing the login table and administrator group
2. Adding an impersonation button to the List page
3. Showing the button only to administrators
4. Switching to the selected user
5. Redirecting after impersonation
6. Adding an impersonation banner
7. Styling the banner
8. Returning to the administrator session

1. Preparing the login table and administrator group

This tutorial assumes that database authentication and user group permissions are already configured in PHPRunner. The table used for authentication must also be included in the project and have a List page that administrators can open.

The sample project uses first_name as the username field. Replace first_name in the code below if your login table uses another field.

We will also use Administrators as the administrator group name. Replace it with the group name used in your project.

2. Adding the impersonation button to the List page

Open the login table’s List page in Page Designer and switch to Advanced Grid. Select a grid cell, then use Insert → Custom button → New button.

Set the button label to ‘Login as this user’ and place it inside the grid row. Select the button and set its Item ID to:
‘login_as_user’

The Item ID is important. It is the value used by hideItem() in the next step. You can select the button in Page Designer and find its Item ID in the properties panel on the right.

3. Showing the button only to administrators

Open Events → login table → List page → After record processed and add the following PHP code:

if (
    Security::getUserGroup() != $_SESSION["AdminGroupName"]
    || $data["first_name"] == Security::getUserName()
) {
    $pageObject->hideItem("login_as_user", $recordId);
}

The second argument of hideItem() is required because the button is located inside a List page grid row. The code hides the button from non-administrators and also hides it on the administrator’s own record.

4. Switching to the selected user

Open the custom button code and select its Server tab. Add the following PHP code:

if (Security::getUserGroup() != $_SESSION["AdminGroupName"]) {
    $result["success"] = false;
    return;
}

$record = $button->getCurrentRecord();

$_SESSION["impersonation_admin"] = Security::getUserName();

Security::loginAs($record["first_name"]);

$result["success"] = true;

The group is checked again on the server so that hiding the button is not the only protection. The original administrator username is saved before Security::loginAs() replaces the current login session.

5. Redirecting after impersonation

In the same custom button, open the Client After tab and add this JavaScript code:

if (result["success"]) {
    window.location.href = "menu.php";
}

The redirect reloads the application menu using the impersonated user’s permissions.

6. Adding the impersonation banner

Proceed to Style Editor → Templates → header.htm. Add the following code to the common project header:

<?php
if (
    Security::isLoggedIn()
    && !empty($_SESSION["impersonation_admin"])
) {
    $adminUsername = htmlspecialchars(
        $_SESSION["impersonation_admin"],
        ENT_QUOTES,
        "UTF-8"
    );

    $currentUsername = htmlspecialchars(
        Security::getUserName(),
        ENT_QUOTES,
        "UTF-8"
    );
?>
<div id="impersonation-banner">
    <span>
        <strong>Impersonation mode:</strong>
        Admin <strong><?php echo $adminUsername; ?></strong>
        is browsing as
        <strong><?php echo $currentUsername; ?></strong>.
    </span>

    <a href="menu.php?return_admin=1">
        Return to admin session
    </a>
</div>

<script>
(function () {
    var banner = document.getElementById("impersonation-banner");

    if (!banner || !document.body) {
        return;
    }

    document.body.insertBefore(banner, document.body.firstChild);
    document.body.classList.add("impersonation-active");
})();
</script>
<?php
}
?>

The banner appears on every generated page while an administrator is impersonating another logged-in user. The usernames are escaped before they are inserted into the page.

7. Styling the banner

Open Style Editor → Modify CSS and add the following project-level Custom CSS:

:root {
    --impersonation-banner-height: 40px;
}

#impersonation-banner {
    position: sticky !important;
    top: 0 !important;
    z-index: 1000000 !important;
    width: 100% !important;
    max-width: none !important;
    height: var(--impersonation-banner-height);
    box-sizing: border-box;
    margin: 0 !important;
    padding: 0 16px;
    display: flex;
    align-items: center;
    justify-content: center;
    gap: 18px;
    background: #fff3cd;
    border-bottom: 1px solid #e0bd64;
    color: #664d03;
    font-size: 14px;
    line-height: 20px;
    text-align: center;
    white-space: nowrap;
}

#impersonation-banner a {
    color: #664d03;
    font-weight: 600;
    text-decoration: underline;
}

body.impersonation-active .r-topheader[data-fixed] {
    top: var(--impersonation-banner-height) !important;
}

body.impersonation-active .r-left[data-fixed] {
    top: var(--impersonation-banner-height) !important;
    height: calc(100vh - var(--impersonation-banner-height)) !important;
}

body.impersonation-active > .r-vbar-page,
body.impersonation-active > .r-topbar-page {
    min-height: calc(100vh - var(--impersonation-banner-height));
}

@media print {
    #impersonation-banner {
        display: none !important;
    }

    body.impersonation-active .r-topheader[data-fixed],
    body.impersonation-active .r-left[data-fixed] {
        top: 0 !important;
    }
}

Besides styling the warning, this CSS moves PHPRunner’s fixed navigation elements below the banner.

8. Returning to the administrator session

Open Events → Global events → After App Init and add the following PHP code:

$_SESSION["AdminGroupName"] = "Administrators";

if (
    isset($_GET["return_admin"])
    && !empty($_SESSION["impersonation_admin"])
) {
    $adminUsername = $_SESSION["impersonation_admin"];

    unset($_SESSION["impersonation_admin"]);

    Security::loginAs($adminUsername);

    header("Location: menu.php");
    exit();
}

The event defines the administrator group used by the other events. When the return link is clicked, it restores the saved administrator username, removes the impersonation marker, and redirects back to the menu.

After rebuilding the project, log in as an administrator and open the login table’s List page. Click ‘Login as this user’ beside another account. PHPRunner will apply that user’s identity and permissions, display the impersonation banner, and allow you to return to the original administrator session.