Groups

Group Management in Concrete CMS

Concrete CMS lets you organize users into groups for various purposes:

1. Groups link to permissions, controlling access and editing rights.
2. Groups help categorize and organize users.
3. Users can be dynamically added to or removed from groups.

While the Dashboard UI handles group management for most sites, custom web applications or advanced add-ons might need programmatic interaction.

Retrieving a Group Object

To work with groups programmatically, first retrieve a group object:

By ID

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

By Name

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

Working with Groups

With a group object, access various API methods:

print $group->getGroupDisplayName();
print $group->getGroupID();

Retrieve a List of all Users in Group

$users = $group->getGroupMembers();

Adding a New Group

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

Hierarchical Groups

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

Updating a Group

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

Users and Groups

Work with \Concrete\Core\User\User objects for group operations:

$user = $userInfo->getUserObject();

Retrieve a List of all Groups a Single User Belongs To

$groups = $user->getUserGroups();

Adding a User to a Group

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

Removing a User from a Group

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

Listing, Sorting and Filtering Groups

Use \Concrete\Core\User\Group\GroupList for comprehensive group lists:

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

Methods include includeAllGroups(), filterByKeywords($keywords), filterByExpirable(), and filterByAssignable(). Retrieve results with getResults() or pagination:

$pagination = $list->getPagination();
$results = $pagination->getCurrentPageResults();

Creating and Using Badge Groups

Concrete CMS allows marking groups as "Badges," with unique features:

• Badges can carry community point values, awarded to users on application.
• Badges can display a public image.

Adding a Badge Programmatically

To add a badge:

1. Create a group:

   $badge = \Group::add('Sheriff');
   

2. Set badge options (image file ID, description, community points):

   $badge->setBadgeOptions(10, 'The sheriff is cleaning up this town!', 100);
   

To remove badge status:

$badge->clearBadgeOptions();

Getting a User's Badges

Retrieve a user's badges:

$user = \UserInfo::getByName('andrew');
$badges = $user->getUserBadges();

Getting a List of Badges

List all system badges:

$badges = \Group::getBadges();

Automated Groups

Users can automatically enter or exit groups based on specific factors.

Automatic Group Expiration

Create an automated group and define custom properties for auto-removal. For instance, a "Paid Members" group where users are removed after a year:

$members = \Group::add('Paid Members');
$members->setGroupExpirationByInterval(365, 0, 0, 'REMOVE');

Actions for group expiration include REMOVE, DEACTIVATE, or REMOVE_DEACTIVATE. To set a specific expiration date:

$members->setGroupExpirationByDateTime('2016-12-31 11:59:59', 'REMOVE');

To clear expiration settings:

$members->removeGroupExpiration();

Automatic Group Entry

For automatic entry, configure the group with options to check during user registration, login, or job runs:

$checkOnRegister = true;
$checkOnLogin = true;
$checkOnJobRun = true;
$members->setAutomationOptions($checkOnRegister, $checkOnLogin, $checkOnJobRun);

To clear these options:

$group->clearAutomationOptions();

Creating an Automation Controller for Automatic Group Entry

Define a group automation controller in specific locations depending on whether it's a non-packaged or packaged group, with appropriate namespaces.

Non-Packaged Group

Default location: application/src/User/Group/AutomatedGroup/YourGroupName.php Namespace: Application\Src\User\Group\AutomatedGroup

With core extension autoloader mapping enabled, use: Location: application/src/Concrete/User/Group/AutomatedGroup/YourGroupName.php Namespace: Application\User\Group\AutomatedGroup

Packaged Group

Default location: package/your_package/src/User/Group/AutomatedGroup/YourGroupName.php Namespace: Concrete\Package\YourPackage\Src\User\Group\AutomatedGroup

With $pkgAutoloaderMapCoreExtensions set to true: Location: package/your_package/src/Concrete/User/Group/AutomatedGroup/YourGroupName.php Namespace: Concrete\Package\YourPackage\User\Group\AutomatedGroup

Name the class in StudlyCaps based on the group name and extend Concrete\Core\User\Group\GroupAutomationController. Implement a check(\Concrete\Core\User\User $user) method in the class. Return true to add a user to the group, false otherwise.

Example

Creating a group for users with more than 10 pages:

1. Create the group: $editors = \Group::add('Esteemed Editors');
2. Set automation options: $editors->setAutomationOptions(false, false, true);
3. Create the class file application/src/User/Group/AutomatedGroup/EsteemedEditors.php.

Class file contents:

namespace Application\Src\User\Group\AutomatedGroup;
use Concrete\Core\User\User;
use Concrete\Core\User\Group\GroupAutomationController;

class EsteemedEditors extends GroupAutomationController
{
    public function check(User $ux)
    {
        $db = \Database::connection();
        $num = $db->GetOne('select count(uID) from Pages where uID = ?', array($ux->getUserID()));
        if ($num > 9) {
            return true;
        }
        return false;
    }
}

This class adds users who meet the criteria to the group during each job run, applying any associated badges or expiration settings.