Programmatically add user to User Group and Role

I am trying to programmatically add a user to an User Group and Role.

For example, a user fills out a form, and based on the successful processing of the form (e.g. skills test) they are added to a Group and Role. (group and role embedded in form, user does not have access).

I have looked at every Extra and throughout the forums, but I don’t see anything that will accomplish this.

There are some, like DefaultUserGroup and Subscribe that will set the group when creating a new user, but none, as far as I can tell, that can be configured to update a given existing user.

Does anyone have a technique, code or a tip to accomplish this?


I found this article by Bob Ray (Thanks Bob!) which gets me pretty close to what I want.

If there are any php coders who want a couple hour project to make this a robust generic addUserToUserGroup snippet or plugin to contribute to the repository I am happy to pay the going rate.

It seems to me, that it is not worth creating a generic snippet for a functionality, that is basically just a call to the joinGroup function of the current user.

In your case, if you are using FormIt, you probably want to include this call in a custom hook snippet after some checking that the user passed the test.

Also, when you embed group and role in the form on the frontend, the user has always access.

Thank you Harry. You nudged me in the right direction. I found the Modx documentation which is closer to what I need.

I am looking to add groups and roles by name.

I am still willing to engage an admin/programmer who has knowledge of this area, since errors in assigning permissions could be consequential. Also I am looking to create an installable package and put it in the repository.

My contact info is on my web site.

This was also helpful:

Class-based Processors

I got a rudimentary version working, thanks for the comments here and the eternal work of Bob Ray and Susan Ottwell and several others that were helpful to reference on background.

Still looking for a more skilled collaborator (paid) to add some sophistication and package it up.


// setUserGroup snippet
// assigns the current user (session this page is called from) to a given User Group and Role.
// Need logic on page to see if this has already run for this user.
// Set UserGroupName is hard coded only as primitive example. If parameters,
//will need to add code to ensure that it can’t be made to set a random user to Administrator, etc.
// Note that Group or Role could be Group ID instead of name. If so, use an int cast or may fail
// Thanks Bob Ray!
// $modx->user->joinGroupjoinGroup( (int) $groupId, (int) $roleId);
// Of course, change Group1 and Role1 to desired values before using as test code.
// (Group and Role must exist)
$UserGroupName = ‘Group1’;

// Set Role Name
$RoleName = ‘Role1’;

// Get modUser object
$user = $modx->getObject(‘modUser’, array(‘username’ => $username));

// Check to see if user is already in group
if(!($modx->user->isMember($UserGroupName))) {

// Assign current user to User Group and Role

return true;
// Should return actual status based on success or failure
// Should log failure
// Consider refactoring as Class-based Processor

if(!($modx->user->isMember($UserGroupName))) {

The function joinGroup() already checks, whether the user is in the group and just returns true, if that’s the case. The function also checks, if the group and the role exist.

$user = $modx->getObject('modUser', array('username' => $username));

This line is not needed. The current user is already available under $modx->user.

Here is a more elaborated version:

$UserGroupName = $modx->getOption('group',$scriptProperties,'');
$RoleName = $modx->getOption('role',$scriptProperties,'');
$context = $modx->getOption('context',$scriptProperties,$modx->context->get('key'));

//check if user is logged in
if (!$modx->user->hasSessionContext($context)){
    $modx->log(modX::LOG_LEVEL_ERROR,'user not logged in');
    return 'user not logged in';

//check if properties are missing
if (empty($UserGroupName)) {
    $modx->log(modX::LOG_LEVEL_ERROR,'group missing');
    return 'group missing';

if (empty($RoleName)) {
    $modx->log(modX::LOG_LEVEL_ERROR,'role missing');
    return 'role missing';

//ensure that it can’t be made to set a random user to Administrator
//would probably be safer to have lists with allowed groups and roles
$prohibited_groups = array('administrator', 'another_prohibited_group');
if (in_array(strtolower(trim($UserGroupName)), $prohibited_groups)) {
    $modx->log(modX::LOG_LEVEL_ERROR,'group not allowed');
    return 'group not allowed';

$prohibited_roles = array('super user', 'another_prohibited_role');
if (in_array(strtolower(trim($RoleName)), $prohibited_roles)) {
    $modx->log(modX::LOG_LEVEL_ERROR,'role not allowed');
    return 'role not allowed';

// Assign current user to User Group and Role
if ($modx->user->joinGroup($UserGroupName,$RoleName)){
    return '';
} else {
    $modx->log(modX::LOG_LEVEL_ERROR,'joinGroup failed');
    return 'joinGroup failed';

Snippet call:

[[!setUserGroup? &group=`Members` &role=`Member`]]

Thank you very much, Harry.

Do you have a tip jar somewhere?