Adding and Updating Users

Edit

Improvements?

Let us know by posting here.

While most development tasks involving users in Concrete CMS will likely center around reading data from them or determining whether someone is logged in, occasionally you may need to do something more advanced, like programmatically adding or updating a user (or their attributes.) Fortunately, this is easy to do.

Adding a User Programmatically.

Simply call the static add() method on the global UserInfo class, and pass it an array of parameters.

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

The $data array can contain the following

  • uName - Username (no spaces allowed, typically this is what users will use to login.)
  • uEmail - Email address
  • uPassword - A password for the user.
  • uDefaultLanguage - an ISO language code for the user's default language (you can usually leave this blank.)
  • uIsValidated - whether the user is validated. This typically doesn't matter, but if you are creating a community website and you want to know that the user has validated their email address, you can use this setting. Valid values are 1 for validated, 0 for definitely unvalidated, and -1 for unknown (which is the default on sites that don't employ user validation.)

Example

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

This will return a Concrete\Core\User\UserInfo object.

Updating a User Programmatically

Once you have a UserInfo object, updating it is easy.The update method on the Concrete\Core\User\UserInfo class takes care of updating many properties of a UserInfo object, based on what array keys are passed to its first (and only) argument.

First, get a UserInfo object.

$user = \UserInfo::getByID(50);

Next, call update with one or more key/value pairs in its array. This updates the email address.

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

Here's how to update the username:

$user->update(array(
    'uName' => 'aembler'
));

Or maybe do them both together, along with another parameter:

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

The following array keys are checked in the update function:

  • Username (uName)
  • Email Address (uEmail)
  • Timezone (uTimezone)
  • Does the user have an avatar? (true/false) (uHasAvatar)
  • Default Language (uDefaultLanguage)
  • Password (uPassword/uPasswordConfirm - see below)

Setting Custom Attributes

Let's say we want to set the value of "Send Me Private Messages" for a particular user to true. "Send Me Private Messages" is a boolean attribute with the handle "profile_private_messages_notification_enabled".

Retrieve the user you want:

$user = \UserInfo::getByEmail('andrew@concretecms.org');

Then set the attribute

$user->setAttribute('profile_private_messages_notification_enabled', true);

That's it! More complex attribute types may take more complex values in the second argument. For example, if you have an address attribute for a particular page and you want to set it programmatically, the Address attribute type expects its value to be an array with keys that match the properties of the Concrete\Attribute\Address\Value object:

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

Got a custom user attribute that's an Image/File attribute? That requires a file object. Let's say you uploaded a new file into the file manager through a custom file import routine. That would give you a Concrete\Core\File\Version object. From there, here's how you'd set that file attribute on your user.

$file = $version->getFile(); // Retrieves the outer File object from the version that was passed to you from the import routine.
$user->setAttribute('custom_user_image', $file);

That's it!

Changing Passwords

Changing passwords on a user is similar to the update routine above, with a slight difference: you have to pass in the same password as both the uPassword and uPasswordConfirm keys in the data array.

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

Needless to say, they must match.