user.api.php 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507
  1. <?php
  2. /**
  3. * @file
  4. * Hooks provided by the User module.
  5. */
  6. /**
  7. * @addtogroup hooks
  8. * @{
  9. */
  10. /**
  11. * Act on user objects when loaded from the database.
  12. *
  13. * Due to the static cache in user_load_multiple() you should not use this
  14. * hook to modify the user properties returned by the {users} table itself
  15. * since this may result in unreliable results when loading from cache.
  16. *
  17. * @param $users
  18. * An array of user objects, indexed by uid.
  19. *
  20. * @see user_load_multiple()
  21. * @see profile_user_load()
  22. */
  23. function hook_user_load($users) {
  24. $result = db_query('SELECT uid, foo FROM {my_table} WHERE uid IN (:uids)', array(':uids' => array_keys($users)));
  25. foreach ($result as $record) {
  26. $users[$record->uid]->foo = $record->foo;
  27. }
  28. }
  29. /**
  30. * Respond to user deletion.
  31. *
  32. * This hook is invoked from user_delete_multiple() before field_attach_delete()
  33. * is called and before users are actually removed from the database.
  34. *
  35. * Modules should additionally implement hook_user_cancel() to process stored
  36. * user data for other account cancellation methods.
  37. *
  38. * @param $account
  39. * The account that is being deleted.
  40. *
  41. * @see user_delete_multiple()
  42. */
  43. function hook_user_delete($account) {
  44. db_delete('mytable')
  45. ->condition('uid', $account->uid)
  46. ->execute();
  47. }
  48. /**
  49. * Act on user account cancellations.
  50. *
  51. * This hook is invoked from user_cancel() before a user account is canceled.
  52. * Depending on the account cancellation method, the module should either do
  53. * nothing, unpublish content, or anonymize content. See user_cancel_methods()
  54. * for the list of default account cancellation methods provided by User module.
  55. * Modules may add further methods via hook_user_cancel_methods_alter().
  56. *
  57. * This hook is NOT invoked for the 'user_cancel_delete' account cancellation
  58. * method. To react on this method, implement hook_user_delete() instead.
  59. *
  60. * Expensive operations should be added to the global account cancellation batch
  61. * by using batch_set().
  62. *
  63. * @param $edit
  64. * The array of form values submitted by the user.
  65. * @param $account
  66. * The user object on which the operation is being performed.
  67. * @param $method
  68. * The account cancellation method.
  69. *
  70. * @see user_cancel_methods()
  71. * @see hook_user_cancel_methods_alter()
  72. */
  73. function hook_user_cancel($edit, $account, $method) {
  74. switch ($method) {
  75. case 'user_cancel_block_unpublish':
  76. // Unpublish nodes (current revisions).
  77. module_load_include('inc', 'node', 'node.admin');
  78. $nodes = db_select('node', 'n')
  79. ->fields('n', array('nid'))
  80. ->condition('uid', $account->uid)
  81. ->execute()
  82. ->fetchCol();
  83. node_mass_update($nodes, array('status' => 0));
  84. break;
  85. case 'user_cancel_reassign':
  86. // Anonymize nodes (current revisions).
  87. module_load_include('inc', 'node', 'node.admin');
  88. $nodes = db_select('node', 'n')
  89. ->fields('n', array('nid'))
  90. ->condition('uid', $account->uid)
  91. ->execute()
  92. ->fetchCol();
  93. node_mass_update($nodes, array('uid' => 0));
  94. // Anonymize old revisions.
  95. db_update('node_revision')
  96. ->fields(array('uid' => 0))
  97. ->condition('uid', $account->uid)
  98. ->execute();
  99. // Clean history.
  100. db_delete('history')
  101. ->condition('uid', $account->uid)
  102. ->execute();
  103. break;
  104. }
  105. }
  106. /**
  107. * Modify account cancellation methods.
  108. *
  109. * By implementing this hook, modules are able to add, customize, or remove
  110. * account cancellation methods. All defined methods are turned into radio
  111. * button form elements by user_cancel_methods() after this hook is invoked.
  112. * The following properties can be defined for each method:
  113. * - title: The radio button's title.
  114. * - description: (optional) A description to display on the confirmation form
  115. * if the user is not allowed to select the account cancellation method. The
  116. * description is NOT used for the radio button, but instead should provide
  117. * additional explanation to the user seeking to cancel their account.
  118. * - access: (optional) A boolean value indicating whether the user can access
  119. * a method. If access is defined, the method cannot be configured as the
  120. * default method.
  121. *
  122. * @param $methods
  123. * An array containing user account cancellation methods, keyed by method id.
  124. *
  125. * @see user_cancel_methods()
  126. * @see user_cancel_confirm_form()
  127. */
  128. function hook_user_cancel_methods_alter(&$methods) {
  129. // Limit access to disable account and unpublish content method.
  130. $methods['user_cancel_block_unpublish']['access'] = user_access('administer site configuration');
  131. // Remove the content re-assigning method.
  132. unset($methods['user_cancel_reassign']);
  133. // Add a custom zero-out method.
  134. $methods['mymodule_zero_out'] = array(
  135. 'title' => t('Delete the account and remove all content.'),
  136. 'description' => t('All your content will be replaced by empty strings.'),
  137. // access should be used for administrative methods only.
  138. 'access' => user_access('access zero-out account cancellation method'),
  139. );
  140. }
  141. /**
  142. * Add mass user operations.
  143. *
  144. * This hook enables modules to inject custom operations into the mass operations
  145. * dropdown found at admin/people, by associating a callback function with
  146. * the operation, which is called when the form is submitted. The callback function
  147. * receives one initial argument, which is an array of the checked users.
  148. *
  149. * @return
  150. * An array of operations. Each operation is an associative array that may
  151. * contain the following key-value pairs:
  152. * - "label": Required. The label for the operation, displayed in the dropdown menu.
  153. * - "callback": Required. The function to call for the operation.
  154. * - "callback arguments": Optional. An array of additional arguments to pass to
  155. * the callback function.
  156. *
  157. */
  158. function hook_user_operations() {
  159. $operations = array(
  160. 'unblock' => array(
  161. 'label' => t('Unblock the selected users'),
  162. 'callback' => 'user_user_operations_unblock',
  163. ),
  164. 'block' => array(
  165. 'label' => t('Block the selected users'),
  166. 'callback' => 'user_user_operations_block',
  167. ),
  168. 'cancel' => array(
  169. 'label' => t('Cancel the selected user accounts'),
  170. ),
  171. );
  172. return $operations;
  173. }
  174. /**
  175. * Define a list of user settings or profile information categories.
  176. *
  177. * There are two steps to using hook_user_categories():
  178. * - Create the category with hook_user_categories().
  179. * - Display that category on the form ID of "user_profile_form" with
  180. * hook_form_FORM_ID_alter().
  181. *
  182. * Step one builds out the category but it won't be visible on your form until
  183. * you explicitly tell it to do so.
  184. *
  185. * The function in step two should contain the following code in order to
  186. * display your new category:
  187. * @code
  188. * if ($form['#user_category'] == 'mycategory') {
  189. * // Return your form here.
  190. * }
  191. * @endcode
  192. *
  193. * @return
  194. * An array of associative arrays. Each inner array has elements:
  195. * - "name": The internal name of the category.
  196. * - "title": The human-readable, localized name of the category.
  197. * - "weight": An integer specifying the category's sort ordering.
  198. * - "access callback": Name of the access callback function to use to
  199. * determine whether the user can edit the category. Defaults to using
  200. * user_edit_access(). See hook_menu() for more information on access
  201. * callbacks.
  202. * - "access arguments": Arguments for the access callback function. Defaults
  203. * to array(1).
  204. */
  205. function hook_user_categories() {
  206. return array(array(
  207. 'name' => 'account',
  208. 'title' => t('Account settings'),
  209. 'weight' => 1,
  210. ));
  211. }
  212. /**
  213. * A user account is about to be created or updated.
  214. *
  215. * This hook is primarily intended for modules that want to store properties in
  216. * the serialized {users}.data column, which is automatically loaded whenever a
  217. * user account object is loaded, modules may add to $edit['data'] in order
  218. * to have their data serialized on save.
  219. *
  220. * @param $edit
  221. * The array of form values submitted by the user. Assign values to this
  222. * array to save changes in the database.
  223. * @param $account
  224. * The user object on which the operation is performed. Values assigned in
  225. * this object will not be saved in the database.
  226. * @param $category
  227. * The active category of user information being edited.
  228. *
  229. * @see hook_user_insert()
  230. * @see hook_user_update()
  231. */
  232. function hook_user_presave(&$edit, $account, $category) {
  233. // Make sure that our form value 'mymodule_foo' is stored as
  234. // 'mymodule_bar' in the 'data' (serialized) column.
  235. if (isset($edit['mymodule_foo'])) {
  236. $edit['data']['mymodule_bar'] = $edit['mymodule_foo'];
  237. }
  238. }
  239. /**
  240. * A user account was created.
  241. *
  242. * The module should save its custom additions to the user object into the
  243. * database.
  244. *
  245. * @param $edit
  246. * The array of form values submitted by the user.
  247. * @param $account
  248. * The user object on which the operation is being performed.
  249. * @param $category
  250. * The active category of user information being edited.
  251. *
  252. * @see hook_user_presave()
  253. * @see hook_user_update()
  254. */
  255. function hook_user_insert(&$edit, $account, $category) {
  256. db_insert('mytable')
  257. ->fields(array(
  258. 'myfield' => $edit['myfield'],
  259. 'uid' => $account->uid,
  260. ))
  261. ->execute();
  262. }
  263. /**
  264. * A user account was updated.
  265. *
  266. * Modules may use this hook to update their user data in a custom storage
  267. * after a user account has been updated.
  268. *
  269. * @param $edit
  270. * The array of form values submitted by the user.
  271. * @param $account
  272. * The user object on which the operation is performed.
  273. * @param $category
  274. * The active category of user information being edited.
  275. *
  276. * @see hook_user_presave()
  277. * @see hook_user_insert()
  278. */
  279. function hook_user_update(&$edit, $account, $category) {
  280. db_insert('user_changes')
  281. ->fields(array(
  282. 'uid' => $account->uid,
  283. 'changed' => time(),
  284. ))
  285. ->execute();
  286. }
  287. /**
  288. * The user just logged in.
  289. *
  290. * @param $edit
  291. * The array of form values submitted by the user.
  292. * @param $account
  293. * The user object on which the operation was just performed.
  294. */
  295. function hook_user_login(&$edit, $account) {
  296. // If the user has a NULL time zone, notify them to set a time zone.
  297. if (!$account->timezone && variable_get('configurable_timezones', 1) && variable_get('empty_timezone_message', 0)) {
  298. 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')))));
  299. }
  300. }
  301. /**
  302. * The user just logged out.
  303. *
  304. * Note that when this hook is invoked, the changes have not yet been written to
  305. * the database, because a database transaction is still in progress. The
  306. * transaction is not finalized until the save operation is entirely completed
  307. * and user_save() goes out of scope. You should not rely on data in the
  308. * database at this time as it is not updated yet. You should also note that any
  309. * write/update database queries executed from this hook are also not committed
  310. * immediately. Check user_save() and db_transaction() for more info.
  311. *
  312. * @param $account
  313. * The user object on which the operation was just performed.
  314. */
  315. function hook_user_logout($account) {
  316. db_insert('logouts')
  317. ->fields(array(
  318. 'uid' => $account->uid,
  319. 'time' => time(),
  320. ))
  321. ->execute();
  322. }
  323. /**
  324. * The user's account information is being displayed.
  325. *
  326. * The module should format its custom additions for display and add them to the
  327. * $account->content array.
  328. *
  329. * @param $account
  330. * The user object on which the operation is being performed.
  331. * @param $view_mode
  332. * View mode, e.g. 'full'.
  333. * @param $langcode
  334. * The language code used for rendering.
  335. *
  336. * @see hook_user_view_alter()
  337. * @see hook_entity_view()
  338. */
  339. function hook_user_view($account, $view_mode, $langcode) {
  340. if (user_access('create blog content', $account)) {
  341. $account->content['summary']['blog'] = array(
  342. '#type' => 'user_profile_item',
  343. '#title' => t('Blog'),
  344. '#markup' => l(t('View recent blog entries'), "blog/$account->uid", array('attributes' => array('title' => t("Read !username's latest blog entries.", array('!username' => format_username($account)))))),
  345. '#attributes' => array('class' => array('blog')),
  346. );
  347. }
  348. }
  349. /**
  350. * The user was built; the module may modify the structured content.
  351. *
  352. * This hook is called after the content has been assembled in a structured array
  353. * and may be used for doing processing which requires that the complete user
  354. * content structure has been built.
  355. *
  356. * If the module wishes to act on the rendered HTML of the user rather than the
  357. * structured content array, it may use this hook to add a #post_render callback.
  358. * Alternatively, it could also implement hook_preprocess_user_profile(). See
  359. * drupal_render() and theme() documentation respectively for details.
  360. *
  361. * @param $build
  362. * A renderable array representing the user.
  363. *
  364. * @see user_view()
  365. * @see hook_entity_view_alter()
  366. */
  367. function hook_user_view_alter(&$build) {
  368. // Check for the existence of a field added by another module.
  369. if (isset($build['an_additional_field'])) {
  370. // Change its weight.
  371. $build['an_additional_field']['#weight'] = -10;
  372. }
  373. // Add a #post_render callback to act on the rendered HTML of the user.
  374. $build['#post_render'][] = 'my_module_user_post_render';
  375. }
  376. /**
  377. * Act on a user role being inserted or updated.
  378. *
  379. * Modules implementing this hook can act on the user role object before
  380. * it has been saved to the database.
  381. *
  382. * @param $role
  383. * A user role object.
  384. *
  385. * @see hook_user_role_insert()
  386. * @see hook_user_role_update()
  387. */
  388. function hook_user_role_presave($role) {
  389. // Set a UUID for the user role if it doesn't already exist
  390. if (empty($role->uuid)) {
  391. $role->uuid = uuid_uuid();
  392. }
  393. }
  394. /**
  395. * Respond to creation of a new user role.
  396. *
  397. * Modules implementing this hook can act on the user role object when saved to
  398. * the database. It's recommended that you implement this hook if your module
  399. * adds additional data to user roles object. The module should save its custom
  400. * additions to the database.
  401. *
  402. * @param $role
  403. * A user role object.
  404. */
  405. function hook_user_role_insert($role) {
  406. // Save extra fields provided by the module to user roles.
  407. db_insert('my_module_table')
  408. ->fields(array(
  409. 'rid' => $role->rid,
  410. 'role_description' => $role->description,
  411. ))
  412. ->execute();
  413. }
  414. /**
  415. * Respond to updates to a user role.
  416. *
  417. * Modules implementing this hook can act on the user role object when updated.
  418. * It's recommended that you implement this hook if your module adds additional
  419. * data to user roles object. The module should save its custom additions to
  420. * the database.
  421. *
  422. * @param $role
  423. * A user role object.
  424. */
  425. function hook_user_role_update($role) {
  426. // Save extra fields provided by the module to user roles.
  427. db_merge('my_module_table')
  428. ->key(array('rid' => $role->rid))
  429. ->fields(array(
  430. 'role_description' => $role->description
  431. ))
  432. ->execute();
  433. }
  434. /**
  435. * Respond to user role deletion.
  436. *
  437. * This hook allows you act when a user role has been deleted.
  438. * If your module stores references to roles, it's recommended that you
  439. * implement this hook and delete existing instances of the deleted role
  440. * in your module database tables.
  441. *
  442. * @param $role
  443. * The $role object being deleted.
  444. */
  445. function hook_user_role_delete($role) {
  446. // Delete existing instances of the deleted role.
  447. db_delete('my_module_table')
  448. ->condition('rid', $role->rid)
  449. ->execute();
  450. }
  451. /**
  452. * Respond to user flood control events.
  453. *
  454. * This hook allows you act when an unsuccessful user login has triggered
  455. * flood control. This means that either an IP address or a specific user
  456. * account has been temporarily blocked from logging in.
  457. *
  458. * @param $ip
  459. * The IP address that triggered flood control.
  460. * @param $username
  461. * The username that has been temporarily blocked.
  462. *
  463. * @see user_login_final_validate()
  464. */
  465. function hook_user_flood_control($ip, $username = FALSE) {
  466. if (!empty($username)) {
  467. // Do something with the blocked $username and $ip. For example, send an
  468. // e-mail to the user and/or site administrator.
  469. // Drupal core uses this hook to log the event:
  470. watchdog('user', 'Flood control blocked login attempt for %user from %ip.', array('%user' => $username, '%ip' => $ip));
  471. }
  472. else {
  473. // Do something with the blocked $ip. For example, add it to a block-list.
  474. // Drupal core uses this hook to log the event:
  475. watchdog('user', 'Flood control blocked login attempt from %ip.', array('%ip' => $ip));
  476. }
  477. }
  478. /**
  479. * @} End of "addtogroup hooks".
  480. */