- Patch #491972 by Berdir, webchick: clean-up of user/profile related hooks and APIs.

1 files changed, 231 insertions, 73 deletions

diff --git a/modules/user/user.api.php b/modules/user/user.api.php
index 7e8396eca..8c0da7568 100644
--- a/modules/user/user.api.php
+++ b/modules/user/user.api.php
@@ -12,79 +12,6 @@
  */
 
 /**
- * Act on user account actions.
- *
- * This hook allows modules to react when operations are performed on user
- * accounts.
- *
- * @param $op
- *   What kind of action is being performed. Possible values (in alphabetical order):
- *   - "after_update": The user object has been updated and changed. Use this if
- *     (probably along with 'insert') if you want to reuse some information from
- *     the user object.
- *   - "categories": A set of user information categories is requested.
- *   - "form": The user account edit form is about to be displayed. The module
- *     should present the form elements it wishes to inject into the form.
- *   - "insert": The user account is being added. The module should save its
- *     custom additions to the user object into the database and set the saved
- *     fields to NULL in $edit.
- *   - "load": The user account is being loaded. The module may respond to this
- *     and insert additional information into the user object.
- *   - "login": The user just logged in.
- *   - "logout": The user just logged out.
- *   - "register": The user account registration form is about to be displayed.
- *     The module should present the form elements it wishes to inject into the
- *     form.
- *   - "submit": Modify the account before it gets saved.
- *   - "update": The user account is being changed. The module should save its
- *     custom additions to the user object into the database and set the saved
- *     fields to NULL in $edit.
- *   - "validate": The user account is about to be modified. The module should
- *     validate its custom additions to the user object, registering errors as
- *     necessary.
- *   - "view": 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 &$edit
- *   The array of form values submitted by the user.
- * @param &$account
- *   The user object on which the operation is being performed.
- * @param $category
- *   The active category of user information being edited.
- * @return
- *   This varies depending on the operation.
- *   - "categories": A linear array of associative arrays. These arrays have
- *     keys:
- *     - "name": The internal name of the category.
- *     - "title": The human-readable, localized name of the category.
- *     - "weight": An integer specifying the category's sort ordering.
- *   - "delete": None.
- *   - "form", "register": A $form array containing the form elements to display.
- *   - "insert": None.
- *   - "load": None.
- *   - "login": None.
- *   - "logout": None.
- *   - "submit": None:
- *   - "update": None.
- *   - "validate": None.
- *   - "view": None. For an example see: user_user().
- */
-function hook_user($op, &$edit, &$account, $category = NULL) {
-  if ($op == 'form' && $category == 'account') {
-    $form['comment_settings'] = array(
-      '#type' => 'fieldset',
-      '#title' => t('Comment settings'),
-      '#collapsible' => TRUE,
-      '#weight' => 4);
-    $form['comment_settings']['signature'] = array(
-      '#type' => 'textarea',
-      '#title' => t('Signature'),
-      '#default_value' => $edit['signature'],
-      '#description' => t('Your signature will be publicly displayed at the end of your comments.'));
-    return $form;
-  }
-}
-/**
  * Act on user objects when loaded from the database.
  *
  * Due to the static cache in user_load_multiple() you should not use this
@@ -251,9 +178,36 @@ function hook_user_operations() {
   return $operations;
 }
 
+/**
+ * The user object has been updated and changed.
+ *
+ * Use this if (probably along with 'insert') if you want to reuse some
+ * information from the user object.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param $account
+ *   The user object on which the operation is performed.
+ * @param $category
+ *   The active category of user information being edited.
+ */
+function hook_user_after_update(&$edit, $account, $category) {
+  db_insert('user_changes')
+    ->fields(array(
+      'uid' => $account->uid,
+      'changed' => time(),
+    ))
+    ->execute();
+}
 
 /**
  * Retrieve a list of all user setting/information categories.
+ *
+ * @return
+ *   A linear array of associative arrays. These arrays have keys:
+ *   - "name": The internal name of the category.
+ *   - "title": The human-readable, localized name of the category.
+ *   - "weight": An integer specifying the category's sort ordering.
  */
 function hook_user_categories() {
   return array(array(
@@ -263,6 +217,210 @@ function hook_user_categories() {
   ));
 }
 
+/**
+ * The user account edit form is about to be displayed.
+ *
+ * The module should present the form elements it wishes to inject
+ * into the form.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param $account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   A $form array containing the form elements to display.
+ */
+function hook_user_form(&$edit, $account, $category = NULL) {
+  if ($category == 'account') {
+    $form['comment_settings'] = array(
+      '#type' => 'fieldset',
+      '#title' => t('Comment settings'),
+      '#collapsible' => TRUE,
+      '#weight' => 4);
+    $form['comment_settings']['signature'] = array(
+      '#type' => 'textarea',
+      '#title' => t('Signature'),
+      '#default_value' => $edit['signature'],
+      '#description' => t('Your signature will be publicly displayed at the end of your comments.'));
+    return $form;
+  }
+}
+
+
+/**
+ * The user account is being added.
+ *
+ * The module should save its custom additions to the user object into the
+ * database and set the saved fields to NULL in $edit.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param $account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ */
+function hook_user_insert(&$edit, $account, $category) {
+  db_insert('mytable')
+    ->fields(array(
+      'myfield' => $edit['myfield'],
+      'uid' => $account->uid,
+    ))
+    ->execute();
+  $edit['myfield'] = NULL;
+}
+
+/**
+ * The user just logged in.
+ *
+ * @param &$edit
+ *   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.
+  if (!$user->timezone && variable_get('configurable_timezones', 1) && variable_get('empty_timezone_message', 0)) {
+    drupal_set_message(t('Please configure your <a href="@user-edit">account time zone setting</a>.', array('@user-edit' => url("user/$user->uid/edit", array('query' => drupal_get_destination(), 'fragment' => 'edit-timezone')))));
+  }
+}
+
+/**
+ * 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 account registration form is about to be displayed.
+ *
+ * The module should present the form elements it wishes to inject into the
+ * form.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param $account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ * @return
+ *   A $form array containing the form elements to display.
+ */
+function hook_user_register(&$edit, $account, $category) {
+  if (variable_get('configurable_timezones', 1)) {
+    $form = array();
+    if (variable_get('user_default_timezone', DRUPAL_USER_TIMEZONE_DEFAULT) == DRUPAL_USER_TIMEZONE_SELECT) {
+      system_user_timezone($edit, $form);
+    }
+    else {
+      $form['timezone'] = array(
+        '#type' => 'hidden',
+        '#value' => variable_get('user_default_timezone', DRUPAL_USER_TIMEZONE_DEFAULT) ? '' : variable_get('date_default_timezone', ''),
+      );
+    }
+    return $form;
+  }
+}
+
+/**
+ * Modify the account before it gets saved.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param $account
+ *   The user object on which the operation is performed.
+ * @param $category
+ *   The active category of user information being edited.
+ */
+function hook_user_submit(&$edit, $account, $category) {
+  if ($category == 'account') {
+    if (!empty($edit['picture_upload'])) {
+      $edit['picture'] = $edit['picture_upload'];
+    }
+    // Delete picture if requested, and if no replacement picture was given.
+    elseif (!empty($edit['picture_delete'])) {
+      $edit['picture'] = NULL;
+    }
+    // Remove these values so they don't end up serialized in the data field.
+    $edit['picture_upload'] = NULL;
+    $edit['picture_delete'] = NULL;
+
+    if (isset($edit['roles'])) {
+      $edit['roles'] = array_filter($edit['roles']);
+    }
+  }
+}
+
+/**
+ * The user account is being changed.
+ *
+ * The module should save its custom additions to the user object into the
+ * database and set the saved fields to NULL in $edit.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param $account
+ *   The user object on which the operation is performed.
+ * @param $category
+ *   The active category of user information being edited.
+ */
+function hook_user_update(&$edit, $account, $category) {
+  db_update('mytable')
+    ->fields(array('myfield' => $edit['myfield']))
+    ->condition('uid', $account->uid)
+    ->execute();
+  $edit['myfield'] = NULL;
+}
+
+/**
+ * The user account is about to be modified.
+ *
+ * The module should validate its custom additions to the user object,
+ * registering errors as necessary.
+ *
+ * @param &$edit
+ *   The array of form values submitted by the user.
+ * @param $account
+ *   The user object on which the operation is being performed.
+ * @param $category
+ *   The active category of user information being edited.
+ */
+function hook_user_validate(&$edit, $account, $category) {
+  if ($category == 'mymodule' && empty($edit['myfield'])) {
+    form_set_error('myfield', t('Myfield is required.'));
+  }
+}
+
+/**
+ * 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.
+ */
+function hook_user_view($account) {
+  if (user_access('create blog content', $account)) {
+    $account->content['summary']['blog'] =  array(
+      '#type' => 'user_profile_item',
+      '#title' => t('Blog'),
+      '#markup' => l(t('View recent blog entries'), "blog/$account->uid", array('attributes' => array('title' => t("Read !username's latest blog entries.", array('!username' => $account->name))))),
+      '#attributes' => array('class' => 'blog'),
+    );
+  }
+}
 
 /**
  * @} End of "addtogroup hooks".