Overview

Edit

Improvements?

Let us know by posting here.

There are several reasons why you might want to place your Concrete CMS website's users into various groups.

  1. Groups can be added to permissions, so you can place users in groups if you want them to be able to view or edit specific things.
  2. Groups can be use to categorize and organize users
  3. Users can be added to and removed from groups programmatically – which might be useful for certain websites.

Most websites will work with users and groups simply via the Dashboard user interface, which lets administrators add groups to user accounts. However, if you're building a custom web application with Concrete or an advanced add-on, you might need to interact with groups programmatically.

Retrieving a Group Object

It's easy to get a group object (which you'll need for any of the other examples in this document):

By ID

// Version 9
$repository = $this->app->make(\Concrete\Core\User\Group\GroupRepository::class);
$group = $repository->getGroupByID(3);

// Version 8
$group = \Concrete\Core\User\Group\Group::getByID(3);

Retrieves the group with ID of 3 (which is usually the administrators group.)

By Name

// Version 9
$repository = $this->app->make(\Concrete\Core\User\Group\GroupRepository::class);
$group = $repository->getGroupByName('Administrators');

// Version 8
$group = \Concrete\Core\User\Group\Group::getByName('Administrators');

Working with Groups

Once you have a group object, you'll be able to access all of its API methods

print $group->getGroupDisplayName(); // "Administrators"
print $group->getGroupID();

Some of the more common things you'll do with groups include

Retrieve a List of all Users in Group

$users = $group->getGroupMembers();

This returns an array of \Concrete\Core\User\UserInfo objects.

Adding a New Group

It's easy to add a new group to Concrete.

// Version 9
$command = new \Concrete\Core\User\Group\Command\AddGroupCommand();
$command->setName('Group Name');
$command->setDescription('Group Description');
$group = $this->app->executeCommand($command);

// Version 8
$group = \Group::add('Group Name', 'Group Description');

Need to add a group that's part of a package?

// Version 9
$pkg = $this->app->make(\Concrete\Core\Package\PackageService::class)->getByHandle('my_package');
$command = new \Concrete\Core\User\Group\Command\AddGroupCommand();
$command->setName('Group Name');
$command->setDescription('Group Description);
$command->setPackageID($pkg->getPackageID());
$group = $this->app->executeCommand($command);

// Version 8
$pkg = \Package::getByHandle('my_package');
$group = \Group::add('Group', false, false, $pkg);

Hierarchical Groups

Groups can be added hierarchically as well. Any user that's within a group that falls beneath another group is considered part of all the groups that lead up to the group. Lets say we have group setup like the following

  • Affiliates
    • My Affiliate

Want to add an "Editors" group beneath "My Affiliate" ? First, retrieve the affiliate group:

// Version 9
$repository = $this->app->make(\Concrete\Core\User\Group\GroupRepository::class);
$group = $repository->getGroupByPath('/Affiliates');

// Version 8
$group = \Concrete\Core\User\Group\Group::getByPath('/Affiliates');

Next, add a group, and pass the parent group in as the third parameter:

// Version 9
$groupNode = \Concrete\Core\Tree\Node\Type\Group::getTreeNodeByGroupID($group->getGroupID());
$command = new \Concrete\Core\User\Group\Command\AddGroupCommand();
$command->setName('My Affiliate');
$command->setParentNodeID($groupNode->getTreeNodeID());
$group = $this->app->executeCommand($command);

// Version 8
$editors = \Group::add('My Affiliate', null, $group);

Updating a Group

It's easy to update certain group properties using the Group object:

// Version 9
$repository = $this->app->make(\Concrete\Core\User\Group\GroupRepository::class);
$group = $repository->getGroupByName('Administrators');
$group->update('System Administrators', 'My New Description');

// Version 8
$group = \Group::getByName("Administrators");
$group->update('System Administrators', 'My New Description');

Deleting a group is easy as well:

// Version 9
$command = new \Concrete\Core\User\Group\Command\DeleteGroupCommand($group->getGroupID());
$this->app->executeCommand($command);

// Version 8
$group->delete();

Users and Groups

Many user and group operations require the \Concrete\Core\User\User object (as opposed to UserInfo.) If you have a UserInfo object, you'll need to get a User object from it.

$user = $userInfo->getUserObject();

Once you have the object, you can do a number of things:

Retrieve a List of all Groups a Single User Belongs To

$groups = $user->getUserGroups();

This returns an associative array with the keys consisting of group IDs, and the values consisting of group names. Getting full objects from this is easy.

$groups = array();
$ids = array_keys($user->getUserGroups());
foreach($ids as $id) {
    $group = \Group::getByID($id);
    if (is_object($group)) {
        $groups[] = $group;
    }
}

Adding a User to a Group

Adding a user to a group requires the \Concrete\Core\User\User object (as opposed to UserInfo.) If you have a UserInfo object, you'll need to get a User object from it.

if (!$user->inGroup($group)) {
    $user->enterGroup($group);
}

This is pretty straightforward: we retrieve a User object from our UserInfo object, then we check to see if the user is already in the group. If the user isn't, we add them to the group with enterGroup.

Removing a User from a Group

Remove a user from a group with exitGroup.

if ($user->inGroup($group)) {
    $user->exitGroup($group);
}

Listing, Sorting and Filtering Groups

Need a list of all the user groups? Use the \Concrete\Core\User\Group\GroupList class:

$list = new \Concrete\Core\User\Group\GroupList();

A number of methods are available to the GroupList, including

  • includeAllGroups() (Calling this makes it so that the system groups "Guests" and "Registered Users" are included in the results.)
  • filterByKeywords($keywords) (Filters groups based on keywords in their name and description)
  • filterByExpirable() (Calling this makes it so that only groups that users can "expire from" are included.)
  • filterByAssignable() (Calling this returns groups that the current user has permissions to assign to other users.)

As with other database item lists, retrieving the results is a matter of using getResults() or working with a pagination object

$pagination = $list->getPagination();
$pagination->setMaxPerPage(10)->setCurrentPage(1);
$results = $pagination->getCurrentPageResults();