user.api.php 14.6 KB
Newer Older
1 2
<?php

3
use Drupal\Core\Entity\EntityInterface;
4

5 6 7 8 9 10 11 12 13 14
/**
 * @file
 * Hooks provided by the User module.
 */

/**
 * @addtogroup hooks
 * @{
 */

15 16 17 18 19 20
/**
 * Act on a newly created user.
 *
 * This hook runs after a new user object has just been instantiated. It can be
 * used to set initial values, e.g. to provide defaults.
 *
21
 * @param \Drupal\user\UserInterface $user
22 23 24 25 26 27 28 29
 *   The user object.
 */
function hook_user_create(\Drupal\user\Plugin\Core\Entity\User $user) {
  if (!isset($user->foo)) {
    $user->foo = 'some_initial_value';
  }
}

30 31 32 33 34 35 36 37 38 39 40 41 42 43
/**
 * Act on user objects when loaded from the database.
 *
 * Due to the static cache in user_load_multiple() you should not use this
 * hook to modify the user properties returned by the {users} table itself
 * since this may result in unreliable results when loading from cache.
 *
 * @param $users
 *   An array of user objects, indexed by uid.
 *
 * @see user_load_multiple()
 * @see profile_user_load()
 */
function hook_user_load($users) {
44
  $result = db_query('SELECT uid, foo FROM {my_table} WHERE uid IN (:uids)', array(':uids' => array_keys($users)));
45
  foreach ($result as $record) {
46
    $users[$record->uid]->foo = $record->foo;
47 48
  }
}
49

50
/**
51
 * Act before user deletion.
52
 *
53 54 55
 * This hook is invoked from user_delete_multiple() before
 * field_attach_delete() is called and before the user is actually removed from
 * the database.
56
 *
57 58 59
 * Modules should additionally implement hook_user_cancel() to process stored
 * user data for other account cancellation methods.
 *
60
 * @param $account
61
 *   The account that is about to be deleted.
62
 *
63
 * @see hook_user_delete()
64 65
 * @see user_delete_multiple()
 */
66
function hook_user_predelete($account) {
67
  db_delete('mytable')
68
    ->condition('uid', $account->id())
69 70 71
    ->execute();
}

72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
/**
 * Respond to user deletion.
 *
 * This hook is invoked from user_delete_multiple() after field_attach_delete()
 * has been called and after the user has been removed from the database.
 *
 * Modules should additionally implement hook_user_cancel() to process stored
 * user data for other account cancellation methods.
 *
 * @param $account
 *   The account that has been deleted.
 *
 * @see hook_user_predelete()
 * @see user_delete_multiple()
 */
function hook_user_delete($account) {
88
  drupal_set_message(t('User: @name has been deleted.', array('@name' => $account->getUsername())));
89 90
}

91 92 93
/**
 * Act on user account cancellations.
 *
94 95 96 97 98 99 100
 * This hook is invoked from user_cancel() before a user account is canceled.
 * Depending on the account cancellation method, the module should either do
 * nothing, unpublish content, or anonymize content. See user_cancel_methods()
 * for the list of default account cancellation methods provided by User module.
 * Modules may add further methods via hook_user_cancel_methods_alter().
 *
 * This hook is NOT invoked for the 'user_cancel_delete' account cancellation
101 102
 * method. To react to that method, implement hook_user_predelete() or
 * hook_user_delete() instead.
103
 *
104 105
 * Expensive operations should be added to the global account cancellation batch
 * by using batch_set().
106
 *
107
 * @param $edit
108
 *   The array of form values submitted by the user.
109
 * @param $account
110 111 112 113 114 115 116
 *   The user object on which the operation is being performed.
 * @param $method
 *   The account cancellation method.
 *
 * @see user_cancel_methods()
 * @see hook_user_cancel_methods_alter()
 */
117
function hook_user_cancel($edit, $account, $method) {
118 119 120 121
  switch ($method) {
    case 'user_cancel_block_unpublish':
      // Unpublish nodes (current revisions).
      module_load_include('inc', 'node', 'node.admin');
122
      $nodes = db_select('node_field_data', 'n')
123
        ->fields('n', array('nid'))
124
        ->condition('uid', $account->id())
125 126
        ->execute()
        ->fetchCol();
127
      node_mass_update($nodes, array('status' => 0), NULL, TRUE);
128 129 130 131 132
      break;

    case 'user_cancel_reassign':
      // Anonymize nodes (current revisions).
      module_load_include('inc', 'node', 'node.admin');
133
      $nodes = db_select('node_field_data', 'n')
134
        ->fields('n', array('nid'))
135
        ->condition('uid', $account->id())
136 137
        ->execute()
        ->fetchCol();
138
      node_mass_update($nodes, array('uid' => 0), NULL, TRUE);
139
      // Anonymize old revisions.
140
      db_update('node_field_revision')
141
        ->fields(array('uid' => 0))
142
        ->condition('uid', $account->id())
143
        ->execute();
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160
      break;
  }
}

/**
 * Modify account cancellation methods.
 *
 * By implementing this hook, modules are able to add, customize, or remove
 * account cancellation methods. All defined methods are turned into radio
 * button form elements by user_cancel_methods() after this hook is invoked.
 * The following properties can be defined for each method:
 * - title: The radio button's title.
 * - description: (optional) A description to display on the confirmation form
 *   if the user is not allowed to select the account cancellation method. The
 *   description is NOT used for the radio button, but instead should provide
 *   additional explanation to the user seeking to cancel their account.
 * - access: (optional) A boolean value indicating whether the user can access
161 162
 *   a method. If 'access' is defined, the method cannot be configured as
 *   default method.
163
 *
164
 * @param $methods
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
 *   An array containing user account cancellation methods, keyed by method id.
 *
 * @see user_cancel_methods()
 * @see user_cancel_confirm_form()
 */
function hook_user_cancel_methods_alter(&$methods) {
  // Limit access to disable account and unpublish content method.
  $methods['user_cancel_block_unpublish']['access'] = user_access('administer site configuration');

  // Remove the content re-assigning method.
  unset($methods['user_cancel_reassign']);

  // Add a custom zero-out method.
  $methods['mymodule_zero_out'] = array(
    'title' => t('Delete the account and remove all content.'),
    'description' => t('All your content will be replaced by empty strings.'),
    // access should be used for administrative methods only.
    'access' => user_access('access zero-out account cancellation method'),
  );
}

186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
/**
 * Alter the username that is displayed for a user.
 *
 * Called by user_format_name() to allow modules to alter the username that's
 * displayed. Can be used to ensure user privacy in situations where
 * $account->name is too revealing.
 *
 * @param $name
 *   The string that user_format_name() will return.
 *
 * @param $account
 *   The account object passed to user_format_name().
 *
 * @see user_format_name()
 */
function hook_user_format_name_alter(&$name, $account) {
  // Display the user's uid instead of name.
203 204
  if ($account->id()) {
    $name = t('User !uid', array('!uid' => $account->id()));
205 206 207
  }
}

208
/**
209
 * Act on a user account being inserted or updated.
210
 *
211 212
 * This hook is invoked before the user account is saved to the database.
 *
213
 * @param $account
214
 *   The user account object.
215 216 217 218
 *
 * @see hook_user_insert()
 * @see hook_user_update()
 */
219
function hook_user_presave($account) {
220
  // Ensure that our value is an array.
221
  if (isset($account->mymodule_foo)) {
222
    $account->mymodule_foo = (array) $account->mymodule_foo;
223 224 225 226
  }
}

/**
227
 * Respond to creation of a new user account.
228
 *
229 230
 * Note that when this hook is invoked, the changes have not yet been written to
 * the database, because a database transaction is still in progress. The
231 232 233 234 235 236
 * transaction is not finalized until the insert operation is entirely completed
 * and \Drupal\user\DataStorageController::save() goes out of scope. You should
 * not rely on data in the database at this time as it is not updated yet. You
 * should also note that any write/update database queries executed from this hook
 * are also not committed immediately. Check \Drupal\user\DataStorageController::save()
 * and db_transaction() for more info.
237
 *
238
 * @param $account
239
 *   The user account object.
240 241 242
 *
 * @see hook_user_presave()
 * @see hook_user_update()
243
 */
244 245
function hook_user_insert($account) {
  db_insert('user_changes')
246
    ->fields(array(
247
      'uid' => $account->id(),
248
      'created' => time(),
249 250 251 252
    ))
    ->execute();
}

253
/**
254
 * Respond to updates to a user account.
255
 *
256 257
 * Note that when this hook is invoked, the changes have not yet been written to
 * the database, because a database transaction is still in progress. The
258 259 260 261 262 263
 * transaction is not finalized until the update operation is entirely completed
 * and \Drupal\user\DataStorageController::save() goes out of scope. You should not
 * rely on data in the database at this time as it is not updated yet. You should
 * also note that any write/update database queries executed from this hook are
 * also not committed immediately. Check \Drupal\user\DataStorageController::save()
 * and db_transaction() for more info.
264
 *
265
 * @param $account
266
 *   The user account object.
267 268 269 270
 *
 * @see hook_user_presave()
 * @see hook_user_insert()
 */
271
function hook_user_update($account) {
272 273
  db_insert('user_changes')
    ->fields(array(
274
      'uid' => $account->id(),
275 276 277 278 279
      'changed' => time(),
    ))
    ->execute();
}

280 281 282 283 284 285
/**
 * The user just logged in.
 *
 * @param $account
 *   The user object on which the operation was just performed.
 */
286
function hook_user_login($account) {
287
  $config = Drupal::config('system.date');
288
  // If the user has a NULL time zone, notify them to set a time zone.
289
  if (!$account->getTimezone() && $config->get('timezone.user.configurable') && $config->get('timezone.user.warn')) {
290
    drupal_set_message(t('Configure your <a href="@user-edit">account time zone setting</a>.', array('@user-edit' => url("user/" . $account->id() . "/edit", array('query' => drupal_get_destination(), 'fragment' => 'edit-timezone')))));
291 292 293 294 295 296 297 298 299 300 301 302
  }
}

/**
 * The user just logged out.
 *
 * @param $account
 *   The user object on which the operation was just performed.
 */
function hook_user_logout($account) {
  db_insert('logouts')
    ->fields(array(
303
      'uid' => $account->id(),
304 305 306 307 308 309 310 311 312 313 314
      'time' => time(),
    ))
    ->execute();
}

/**
 * The user's account information is being displayed.
 *
 * The module should format its custom additions for display and add them to the
 * $account->content array.
 *
315
 * @param \Drupal\user\UserInterface $account
316
 *   The user object on which the operation is being performed.
317 318 319
 * @param \Drupal\entity\Plugin\Core\Entity\EntityDisplay $display
 *   The entity_display object holding the display options configured for the
 *   user components.
320 321
 * @param $view_mode
 *   View mode, e.g. 'full'.
322 323
 * @param $langcode
 *   The language code used for rendering.
324 325 326
 *
 * @see hook_user_view_alter()
 * @see hook_entity_view()
327
 */
328
function hook_user_view(\Drupal\user\UserInterface $account, \Drupal\entity\Plugin\Core\Entity\EntityDisplay $display, $view_mode, $langcode) {
329 330 331 332 333 334 335 336
  // Only do the extra work if the component is configured to be displayed.
  // This assumes a 'mymodule_addition' extra field has been defined for the
  // user entity type in hook_field_extra_fields().
  if ($display->getComponent('mymodule_addition')) {
    $account->content['mymodule_addition'] = array(
      '#markup' => mymodule_addition($account),
      '#theme' => 'mymodule_my_additional_field',
    );
337
  }
338
}
339

340 341 342 343 344 345 346 347 348
/**
 * The user was built; the module may modify the structured content.
 *
 * This hook is called after the content has been assembled in a structured array
 * and may be used for doing processing which requires that the complete user
 * content structure has been built.
 *
 * If the module wishes to act on the rendered HTML of the user rather than the
 * structured content array, it may use this hook to add a #post_render callback.
349
 * Alternatively, it could also implement hook_preprocess_HOOK() for
350
 * user.tpl.php. See drupal_render() and theme() documentation
351
 * respectively for details.
352 353 354
 *
 * @param $build
 *   A renderable array representing the user.
355
 * @param \Drupal\user\UserInterface $account
356
 *   The user account being rendered.
357 358 359
 * @param \Drupal\entity\Plugin\Core\Entity\EntityDisplay $display
 *   The entity_display object holding the display options configured for the
 *   user components.
360
 *
361
 * @see user_view()
362
 * @see hook_entity_view_alter()
363
 */
364
function hook_user_view_alter(&$build, \Drupal\user\UserInterface $account, \Drupal\entity\Plugin\Core\Entity\EntityDisplay $display) {
365 366 367 368 369 370 371 372 373 374
  // Check for the existence of a field added by another module.
  if (isset($build['an_additional_field'])) {
    // Change its weight.
    $build['an_additional_field']['#weight'] = -10;
  }

  // Add a #post_render callback to act on the rendered HTML of the user.
  $build['#post_render'][] = 'my_module_user_post_render';
}

375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393
/**
 * Inform other modules that a user role is about to be saved.
 *
 * Modules implementing this hook can act on the user role object before
 * it has been saved to the database.
 *
 * @param $role
 *   A user role object.
 *
 * @see hook_user_role_insert()
 * @see hook_user_role_update()
 */
function hook_user_role_presave($role) {
  // Set a UUID for the user role if it doesn't already exist
  if (empty($role->uuid)) {
    $role->uuid = uuid_uuid();
  }
}

394 395 396 397 398 399 400 401 402 403 404 405 406 407 408
/**
 * Inform other modules that a user role has been added.
 *
 * Modules implementing this hook can act on the user role object when saved to
 * the database. It's recommended that you implement this hook if your module
 * adds additional data to user roles object. The module should save its custom
 * additions to the database.
 *
 * @param $role
 *   A user role object.
 */
function hook_user_role_insert($role) {
  // Save extra fields provided by the module to user roles.
  db_insert('my_module_table')
    ->fields(array(
409
      'rid' => $role->id(),
410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428
      'role_description' => $role->description,
    ))
    ->execute();
}

/**
 * Inform other modules that a user role has been updated.
 *
 * Modules implementing this hook can act on the user role object when updated.
 * It's recommended that you implement this hook if your module adds additional
 * data to user roles object. The module should save its custom additions to
 * the database.
 *
 * @param $role
 *   A user role object.
 */
function hook_user_role_update($role) {
  // Save extra fields provided by the module to user roles.
  db_merge('my_module_table')
429
    ->key(array('rid' => $role->id()))
430 431 432 433 434 435 436 437 438 439
    ->fields(array(
      'role_description' => $role->description
    ))
    ->execute();
}

/**
 * Inform other modules that a user role has been deleted.
 *
 * This hook allows you act when a user role has been deleted.
440
 * If your module stores references to roles, it's recommended that you
441 442 443 444 445 446 447 448 449
 * implement this hook and delete existing instances of the deleted role
 * in your module database tables.
 *
 * @param $role
 *   The $role object being deleted.
 */
function hook_user_role_delete($role) {
  // Delete existing instances of the deleted role.
  db_delete('my_module_table')
450
    ->condition('rid', $role->id())
451 452 453
    ->execute();
}

454 455 456
/**
 * @} End of "addtogroup hooks".
 */