Users

Edit

Overview

Concrete CMS features an extensive user management system:

Secure user model with encrypted password
Attribute system integration for custom data on user accounts
User grouping for permissions and organizational needs
Group Sets, Combination Groups, Hierarchical Groups
Pluggable authentication layers for services like Twitter, Facebook, Google Authenticator, etc.

User authentication, verification, and management in Concrete is straightforward.

User vs. UserInfo

In Concrete CMS, you'll encounter two primary user-related objects:

User

Located at Concrete\Core\User\User

UserInfo

Located at Concrete\Core\User\UserInfo

Distinction

The User object focuses on authentication and login status. It's administrative and lightweight for frequent use. The UserInfo object contains detailed information about a user, including core properties and custom attributes.

Usage Guide

Use the User object for login checks, user authentication, and group membership queries.
Use the UserInfo object to access custom attributes and core user details beyond the name and user ID.

Reading Data from Existing Users

Retrieve the Logged-In User's Object

To check if the current user is logged in within a block or page template, use the Concrete\Core\User\User object:

use Concrete\Core\User\User;

$u = new User(); // Instantiate for the current user

User API Examples

Check if the user is logged in:

if ($u->isRegistered()) {
  print 'User is logged in.';
}

Check if the user is a super user:

if ($u->isSuperUser()) {
  print 'Yes, they are!';
}

Retrieve the user's ID:
```
print $u->getUserID();
```

Get the user's groups:

$groups = $u->getUserGroups();
foreach($groups as $groupID) {
  $group = \Concrete\Core\User\Group\Group::getByID($groupID);
  print $group->getGroupName();
}

Retrieve a User Object by ID

To get a User object using a user ID:

$user = User::getByUserID(3);
$groups = $user->getUserGroups();

To log in a user by ID:

User::getByUserID(3, true); // Logs in user with ID 3

Retrieve UserInfo Object by ID

To access custom attributes or detailed user info, use the UserInfo object:

use Concrete\Core\User\UserInfo;

$ui = UserInfo::getByID(3); // Retrieve by ID
$andrew = UserInfo::getByName('andrew');
$jane = UserInfo::getByEmail('jane@concretecms.org');

UserInfo API Examples

Get the user's last IP address:
```
print $ui->getLastIPAddress();
```
Get the number of logins:
```
print $ui->getNumLogins();
```

Get user's email and name:

print $ui->getUserEmail();
print $ui->getUserName();

Custom Attributes

To access a user's custom attributes:

$response = $ui->getAttribute('profile_private_messages_enabled'); // Boolean response
$response = $ui->getAttribute('contact_address'); // Custom object
print $response->getAddress1();
print $response->getCity();

To return data for presentation:

$response = $ui->getAttribute('contact_address', 'display');

User Attribute Magic Methods

Magic methods for attributes:

$address = $ui->getUserContactAddress(); // Equivalent to $ui->getAttribute('contact_address')

Adding and Updating Users

Adding a User Programmatically

Use UserInfo::add($data) to add users:

$user = \UserInfo::add($data);

$data array includes:

uName - Username
uEmail - Email address
uPassword - User's password
uDefaultLanguage - User's default language (ISO code)
uIsValidated - User validation status (1 for validated, 0 for unvalidated, -1 for unknown)

Example

$user = \UserInfo::add(['uName' => 'andrew', 'uEmail' => 'andrew@concretecms.org', 'uPassword' => 'kittens']);

Updating a User Programmatically

Update a UserInfo object using the update method:

Get a UserInfo object:
```
$user = \UserInfo::getByID(50);
```

Update using key/value pairs:

$user->update(['uEmail' => 'new@email.com']);

Update multiple fields:

$user->update([
  'uName' => 'aembler',
  'uEmail' => 'new@email.com',
  'uTimezone' => 'America/Los_Angeles'
]);

Keys include uName, uEmail, uTimezone, uHasAvatar, uDefaultLanguage, uPassword.

Setting Custom Attributes

Set a boolean attribute:

$user = \UserInfo::getByEmail('andrew@concretecms.org');
$user->setAttribute('profile_private_messages_notification_enabled', true);

Set an address attribute:

$address = [
  'address1' => '123 SW Test',
  'address2' => 'Suite 100',
  'city' => 'Portland',
  'state_province' => 'OR',
  'postal_code' => '99999'
];
$user->setAttribute('contact_address', $address);

Set an Image/File attribute:

$file = $version->getFile();
$user->setAttribute('custom_user_image', $file);

Changing Passwords

Change passwords with uPassword and uPasswordConfirm keys:

$user->update(['uPassword' => 'newpass', 'uPasswordConfirm' => 'newpass']);

Searching and Sorting Users with the UserList Object

Concrete CMS's Concrete\Core\User\UserList object enables developers to query users based on different criteria.

Fetching Users

To get all users:

$list = new \Concrete\Core\User\UserList();
$users = $list->getResults();

Basic Filtering Examples

Filtering by Keywords

Simple keyword filter:
```
$list->filterByKeywords('andrew');
```

Advanced FULLTEXT search:

$list->filterByFulltextKeywords('foobar');

Filtering by Username

Exact username match:
```
$list->filterByUsername('foobar');
```

Substring search in usernames:

$list->filterByFuzzyUsername('foobar');

Filter By Groups

Filter by group name:

$list->filterByGroup('Administrators');

Using a group object:

$group = \Group::getByName('Administrators');
$list->filterByGroup($group);

Exclude a specific group:
```
$list->filterByGroup($group, false);
```

Filter by Attribute

Filter using attribute handles:

$list->filterByProfilePrivateMessagesEnabled(true);

Sorting

Sort by date added:

$list->sortByDateAdded();
$users = $list->getResults();

Sort by username:
```
$list->sortByUserName();
```

Pagination

Basic pagination setup:

$list = new \Concrete\Core\User\UserList();
$pagination = $list->getPagination();
$pagination->setMaxPerPage(10)->setCurrentPage(2);
$results = $pagination->getCurrentPageResults();

Advanced Functions

The UserList includes advanced pagination and functions similar to those in the PageList documentation.

Working with User Avatars

User accounts in Concrete can have a profile picture or "User Avatar," settable via the Dashboard.

Upload an image to display as your user avatar across public profiles and messages.

Displaying User Avatars

To display avatars in PHP:

Retrieve and get the avatar from a UserInfo object:
```
$avatar = $ui->getUserAvatar();
```
Output the avatar:
```
print $avatar->output();
```

Getting Avatar Path

To only get the avatar's image path:

<img class="custom-avatar" src="<?=$avatar->getPath()?>">

Avatar Existence Check

if ($user->hasAvatar()) {
    print 'User has avatar.';
}

Updating User Avatars Programmatically

Setting or Changing the Image

Load the image into Imagine:

$image = \Image::open($_FILES['avatar']['tmp_name']);

Resize the image:

$image = $image->thumbnail(new \Imagine\Image\Box(\Config::get('concrete.icons.user_avatar.width'), \Config::get('concrete.icons.user_avatar.height')));

Update the avatar:
```
$user->updateUserAvatar($image);
```

Removing the Avatar

Remove a user avatar:

$user->update(array('uHasAvatar' => 0));

Creating an Alternate Avatar Service

For custom avatar delivery:

Create a service conforming to Concrete\Core\User\Avatar\AvatarServiceInterface with methods:

public function userHasAvatar(UserInfo $ui);
public function getAvatar(UserInfo $ui);
public function removeAvatar(UserInfo $ui);

getAvatar should return an instance of Concrete\Core\User\Avatar\AvatarInterface:
```
public function getPath();
public function output();
```

Implement the service in Concrete:

\Core::bindShared('user/avatar', function() {
   return \Core::make('My\Custom\AvatarService');
});

where My\Custom\AvatarService implements AvatarServiceInterface.