user.api.php 13.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
<?php

/**
 * @file
 * Hooks provided by the User module.
 */

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

13 14 15 16 17 18 19 20 21 22 23 24 25 26
/**
 * 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) {
27
  $result = db_query('SELECT uid, foo FROM {my_table} WHERE uid IN (:uids)', array(':uids' => array_keys($users)));
28
  foreach ($result as $record) {
29
    $users[$record->uid]->foo = $record->foo;
30 31
  }
}
32

33
/**
34
 * Act before user deletion.
35
 *
36 37 38
 * This hook is invoked from user_delete_multiple() before
 * field_attach_delete() is called and before the user is actually removed from
 * the database.
39
 *
40 41 42
 * Modules should additionally implement hook_user_cancel() to process stored
 * user data for other account cancellation methods.
 *
43
 * @param $account
44
 *   The account that is about to be deleted.
45
 *
46
 * @see hook_user_delete()
47 48
 * @see user_delete_multiple()
 */
49
function hook_user_predelete($account) {
50 51 52 53 54
  db_delete('mytable')
    ->condition('uid', $account->uid)
    ->execute();
}

55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
/**
 * 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) {
  drupal_set_message(t('User: @name has been deleted.', array('@name' => $account->name)));
}

74 75 76
/**
 * Act on user account cancellations.
 *
77 78 79 80 81 82 83
 * 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
84 85
 * method. To react to that method, implement hook_user_predelete() or
 * hook_user_delete() instead.
86
 *
87 88
 * Expensive operations should be added to the global account cancellation batch
 * by using batch_set().
89
 *
90
 * @param $edit
91
 *   The array of form values submitted by the user.
92
 * @param $account
93 94 95 96 97 98 99
 *   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()
 */
100
function hook_user_cancel($edit, $account, $method) {
101 102 103 104
  switch ($method) {
    case 'user_cancel_block_unpublish':
      // Unpublish nodes (current revisions).
      module_load_include('inc', 'node', 'node.admin');
105 106 107 108 109
      $nodes = db_select('node', 'n')
        ->fields('n', array('nid'))
        ->condition('uid', $account->uid)
        ->execute()
        ->fetchCol();
110 111 112 113 114 115
      node_mass_update($nodes, array('status' => 0));
      break;

    case 'user_cancel_reassign':
      // Anonymize nodes (current revisions).
      module_load_include('inc', 'node', 'node.admin');
116 117 118 119 120
      $nodes = db_select('node', 'n')
        ->fields('n', array('nid'))
        ->condition('uid', $account->uid)
        ->execute()
        ->fetchCol();
121 122
      node_mass_update($nodes, array('uid' => 0));
      // Anonymize old revisions.
123 124 125 126
      db_update('node_revision')
        ->fields(array('uid' => 0))
        ->condition('uid', $account->uid)
        ->execute();
127
      // Clean history.
128 129 130
      db_delete('history')
        ->condition('uid', $account->uid)
        ->execute();
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
      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
 *   a method. If #access is defined, the method cannot be configured as default
 *   method.
 *
151
 * @param $methods
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
 *   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'),
  );
}

173 174 175 176
/**
 * Add mass user operations.
 *
 * This hook enables modules to inject custom operations into the mass operations
177
 * dropdown found at admin/people, by associating a callback function with
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
 * the operation, which is called when the form is submitted. The callback function
 * receives one initial argument, which is an array of the checked users.
 *
 * @return
 *   An array of operations. Each operation is an associative array that may
 *   contain the following key-value pairs:
 *   - "label": Required. The label for the operation, displayed in the dropdown menu.
 *   - "callback": Required. The function to call for the operation.
 *   - "callback arguments": Optional. An array of additional arguments to pass to
 *     the callback function.
 *
 */
function hook_user_operations() {
  $operations = array(
    'unblock' => array(
      'label' => t('Unblock the selected users'),
      'callback' => 'user_user_operations_unblock',
    ),
    'block' => array(
      'label' => t('Block the selected users'),
      'callback' => 'user_user_operations_block',
    ),
200 201
    'cancel' => array(
      'label' => t('Cancel the selected user accounts'),
202 203 204 205 206
    ),
  );
  return $operations;
}

207
/**
208 209 210 211
 * A user account is about to be created or updated.
 *
 * This hook is primarily intended for modules that want to store properties in
 * the serialized {users}.data column, which is automatically loaded whenever a
212 213
 * user account object is loaded, modules may add to $edit['data'] in order
 * to have their data serialized on save.
214
 *
215
 * @param $edit
216 217 218 219 220 221 222
 *   The array of form values submitted by the user.
 * @param $account
 *   The user object on which the operation is performed.
 *
 * @see hook_user_insert()
 * @see hook_user_update()
 */
223
function hook_user_presave(&$edit, $account) {
224 225
  // Make sure that our form value 'mymodule_foo' is stored as 'mymodule_bar'.
  if (isset($edit['mymodule_foo'])) {
226
    $edit['data']['my_module_foo'] = $edit['my_module_foo'];
227 228 229 230 231
  }
}

/**
 * A user account was created.
232 233
 *
 * The module should save its custom additions to the user object into the
234
 * database.
235
 *
236
 * @param $edit
237 238 239
 *   The array of form values submitted by the user.
 * @param $account
 *   The user object on which the operation is being performed.
240 241 242
 *
 * @see hook_user_presave()
 * @see hook_user_update()
243
 */
244
function hook_user_insert(&$edit, $account) {
245 246 247 248 249 250 251 252
  db_insert('mytable')
    ->fields(array(
      'myfield' => $edit['myfield'],
      'uid' => $account->uid,
    ))
    ->execute();
}

253 254 255 256 257 258
/**
 * A user account was updated.
 *
 * Modules may use this hook to update their user data in a custom storage
 * after a user account has been updated.
 *
259
 * @param $edit
260 261 262 263 264 265 266
 *   The array of form values submitted by the user.
 * @param $account
 *   The user object on which the operation is performed.
 *
 * @see hook_user_presave()
 * @see hook_user_insert()
 */
267
function hook_user_update(&$edit, $account) {
268 269 270 271 272 273 274 275
  db_insert('user_changes')
    ->fields(array(
      'uid' => $account->uid,
      'changed' => time(),
    ))
    ->execute();
}

276 277 278
/**
 * The user just logged in.
 *
279
 * @param $edit
280 281 282 283 284 285
 *   The array of form values submitted by the user.
 * @param $account
 *   The user object on which the operation was just performed.
 */
function hook_user_login(&$edit, $account) {
  // If the user has a NULL time zone, notify them to set a time zone.
286 287
  if (!$account->timezone && variable_get('configurable_timezones', 1) && variable_get('empty_timezone_message', 0)) {
    drupal_set_message(t('Configure your <a href="@user-edit">account time zone setting</a>.', array('@user-edit' => url("user/$account->uid/edit", array('query' => drupal_get_destination(), 'fragment' => 'edit-timezone')))));
288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313
  }
}

/**
 * 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(
      'uid' => $account->uid,
      '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.
 *
 * @param $account
 *   The user object on which the operation is being performed.
314 315
 * @param $view_mode
 *   View mode, e.g. 'full'.
316 317
 * @param $langcode
 *   The language code used for rendering.
318 319 320
 *
 * @see hook_user_view_alter()
 * @see hook_entity_view()
321
 */
322
function hook_user_view($account, $view_mode, $langcode) {
323 324 325 326
  $account->content['user_picture'] = array(
    '#markup' => theme('user_picture', array('account' => $account)),
    '#weight' => -10,
  );
327 328
  $account->content['member_for'] = array(
    '#type' => 'item',
329 330 331
    '#title' => t('Member for'),
    '#markup' => format_interval(REQUEST_TIME - $account->created),
  );
332
}
333

334 335 336 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.
 * Alternatively, it could also implement hook_preprocess_user_profile(). See
 * drupal_render() and theme() documentation respectively for details.
 *
 * @param $build
 *   A renderable array representing the user.
 *
349
 * @see user_view()
350
 * @see hook_entity_view_alter()
351
 */
352
function hook_user_view_alter(&$build) {
353 354 355 356 357 358 359 360 361 362
  // 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';
}

363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381
/**
 * 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();
  }
}

382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427
/**
 * 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(
      'rid' => $role->rid,
      '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')
    ->key(array('rid' => $role->rid))
    ->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.
428
 * If your module stores references to roles, it's recommended that you
429 430 431 432 433 434 435 436 437 438 439 440 441
 * 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')
    ->condition('rid', $role->rid)
    ->execute();
}

442 443 444
/**
 * @} End of "addtogroup hooks".
 */