1 files changed, 59 insertions, 92 deletions

diff --git a/modules/user/user.api.php b/modules/user/user.api.php
index 82895e182..aca316ac2 100644
--- a/modules/user/user.api.php
+++ b/modules/user/user.api.php
@@ -179,28 +179,6 @@ function hook_user_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
@@ -218,7 +196,36 @@ function hook_user_categories() {
 }
 
 /**
- * The user account is being added.
+ * 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
+ * user account object is loaded, and the module needs to prepare the stored
+ * data in some way.
+ * 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.
+ *
+ * @see hook_user_insert()
+ * @see hook_user_update()
+ */
+function hook_user_presave(&$edit, $account, $category) {
+  // Make sure that our form value 'mymodule_foo' is stored as 'mymodule_bar'.
+  if (isset($edit['mymodule_foo'])) {
+    $edit['mymodule_bar'] = $edit['mymodule_foo'];
+    // Inform user_save() to ignore the value of our property.
+    $edit['mymodule_foo'] = NULL;
+  }
+}
+
+/**
+ * A user account was created.
  *
  * The module should save its custom additions to the user object into the
  * database and set the saved fields to NULL in $edit.
@@ -229,6 +236,9 @@ function hook_user_categories() {
  *   The user object on which the operation is being performed.
  * @param $category
  *   The active category of user information being edited.
+ *
+ * @see hook_user_presave()
+ * @see hook_user_update()
  */
 function hook_user_insert(&$edit, $account, $category) {
   db_insert('mytable')
@@ -237,10 +247,36 @@ function hook_user_insert(&$edit, $account, $category) {
       'uid' => $account->uid,
     ))
     ->execute();
+  // Inform user_save() to ignore the value of our property.
   $edit['myfield'] = NULL;
 }
 
 /**
+ * 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.
+ *
+ * @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.
+ *
+ * @see hook_user_presave()
+ * @see hook_user_insert()
+ */
+function hook_user_update(&$edit, $account, $category) {
+  db_insert('user_changes')
+    ->fields(array(
+      'uid' => $account->uid,
+      'changed' => time(),
+    ))
+    ->execute();
+}
+
+/**
  * The user just logged in.
  *
  * @param &$edit
@@ -271,75 +307,6 @@ function hook_user_logout($account) {
 }
 
 /**
- * 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