user.api.php 15 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
21
22
23
24
25
26
27
28
/**
 * 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) {
29
  $result = db_query('SELECT uid, foo FROM {my_table} WHERE uid IN (:uids)', array(':uids' => array_keys($users)));
30
  foreach ($result as $record) {
31
    $users[$record->uid]->foo = $record->foo;
32
33
  }
}
34

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

57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
/**
 * 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)));
}

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

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

175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
/**
 * 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.
  if (isset($account->uid)) {
    $name = t('User !uid', array('!uid' => $account->uid));
  }
}

197
198
199
200
/**
 * Add mass user operations.
 *
 * This hook enables modules to inject custom operations into the mass operations
201
 * dropdown found at admin/people, by associating a callback function with
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 * 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',
    ),
224
225
    'cancel' => array(
      'label' => t('Cancel the selected user accounts'),
226
227
228
229
230
    ),
  );
  return $operations;
}

231
/**
232
 * Act on a user account being inserted or updated.
233
 *
234
235
236
237
238
239
 * This hook is invoked before the user account is saved to the database.
 *
 * Modules that want to store properties in the serialized {users}.data column,
 * which is automatically loaded whenever a user account object is loaded, may
 * add their properties to $account->data in order to have their data serialized
 * on save.
240
241
 *
 * @param $account
242
 *   The user account object.
243
244
245
246
 *
 * @see hook_user_insert()
 * @see hook_user_update()
 */
247
function hook_user_presave($account) {
248
249
  // Make sure that our form value 'mymodule_foo' is stored as
  // 'mymodule_bar' in the 'data' (serialized) column.
250
251
  if (isset($account->mymodule_foo)) {
    $account->data['mymodule_bar'] = $account->mymodule_foo;
252
253
254
255
  }
}

/**
256
 * Respond to creation of a new user account.
257
 *
258
259
260
261
262
263
264
265
 * 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
 * transaction is not finalized until the save operation is entirely completed
 * and user_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 user_save() and db_transaction() for more info.
 *
266
 * @param $account
267
 *   The user account object.
268
269
270
 *
 * @see hook_user_presave()
 * @see hook_user_update()
271
 */
272
273
function hook_user_insert($account) {
  db_insert('user_changes')
274
275
    ->fields(array(
      'uid' => $account->uid,
276
      'created' => time(),
277
278
279
280
    ))
    ->execute();
}

281
/**
282
 * Respond to updates to a user account.
283
 *
284
285
286
287
288
289
290
291
 * 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
 * transaction is not finalized until the save operation is entirely completed
 * and user_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 user_save() and db_transaction() for more info.
 *
292
 * @param $account
293
 *   The user account object.
294
295
296
297
 *
 * @see hook_user_presave()
 * @see hook_user_insert()
 */
298
function hook_user_update($account) {
299
300
301
302
303
304
305
306
  db_insert('user_changes')
    ->fields(array(
      'uid' => $account->uid,
      'changed' => time(),
    ))
    ->execute();
}

307
308
309
/**
 * The user just logged in.
 *
310
 * @param $edit
311
312
313
314
 *   The array of form values submitted by the user.
 * @param $account
 *   The user object on which the operation was just performed.
 */
315
function hook_user_login($edit, $account) {
316
  // If the user has a NULL time zone, notify them to set a time zone.
317
318
  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')))));
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
  }
}

/**
 * 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.
345
346
 * @param $view_mode
 *   View mode, e.g. 'full'.
347
348
 * @param $langcode
 *   The language code used for rendering.
349
350
351
 *
 * @see hook_user_view_alter()
 * @see hook_entity_view()
352
 */
353
function hook_user_view($account, $view_mode, $langcode) {
354
355
356
357
  $account->content['user_picture'] = array(
    '#markup' => theme('user_picture', array('account' => $account)),
    '#weight' => -10,
  );
358
359
  $account->content['member_for'] = array(
    '#type' => 'item',
360
361
362
    '#title' => t('Member for'),
    '#markup' => format_interval(REQUEST_TIME - $account->created),
  );
363
}
364

365
366
367
368
369
370
371
372
373
/**
 * 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.
374
375
376
 * Alternatively, it could also implement hook_preprocess_HOOK() for
 * user-profile.tpl.php. See drupal_render() and theme() documentation
 * respectively for details.
377
378
379
 *
 * @param $build
 *   A renderable array representing the user.
380
381
 * @param Drupal\user\User $account
 *   The user account being rendered.
382
 *
383
 * @see user_view()
384
 * @see hook_entity_view_alter()
385
 */
386
function hook_user_view_alter(&$build, Drupal\user\User $account) {
387
388
389
390
391
392
393
394
395
396
  // 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';
}

397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
/**
 * 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();
  }
}

416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
/**
 * 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.
462
 * If your module stores references to roles, it's recommended that you
463
464
465
466
467
468
469
470
471
472
473
474
475
 * 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();
}

476
477
478
/**
 * @} End of "addtogroup hooks".
 */