modules/user/user.api.php

<?php
// $Id: user.api.php,v 1.14 2009/10/10 16:48:39 webchick Exp $

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

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

/**
 * 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) {
  $result = db_query('SELECT * FROM {my_table} WHERE uid IN (:uids)', array(':uids' => array_keys($users)));
  foreach ($result as $record) {
    $users[$record->uid]->foo = $result->foo;
  }
}

/**
 * Act on user account cancellations.
 *
 * The user account is being canceled. Depending on the account cancellation
 * method, the module should either do nothing, unpublish content, anonymize
 * content, or delete content and data belonging to the canceled user account.
 *
 * Expensive operations should be added to the global batch with batch_set().
 *
 * @param $edit
 *   The array of form values submitted by the user.
 * @param $account
 *   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()
 * @see user_cancel()
 */
function hook_user_cancel($edit, $account, $method) {
  switch ($method) {
    case 'user_cancel_block_unpublish':
      // Unpublish nodes (current revisions).
      module_load_include('inc', 'node', 'node.admin');
      $nodes = db_select('node', 'n')
        ->fields('n', array('nid'))
        ->condition('uid', $account->uid)
        ->execute()
        ->fetchCol();
      node_mass_update($nodes, array('status' => 0));
      break;

    case 'user_cancel_reassign':
      // Anonymize nodes (current revisions).
      module_load_include('inc', 'node', 'node.admin');
      $nodes = db_select('node', 'n')
        ->fields('n', array('nid'))
        ->condition('uid', $account->uid)
        ->execute()
        ->fetchCol();
      node_mass_update($nodes, array('uid' => 0));
      // Anonymize old revisions.
      db_update('node_revision')
        ->fields(array('uid' => 0))
        ->condition('uid', $account->uid)
        ->execute();
      // Clean history.
      db_delete('history')
        ->condition('uid', $account->uid)
        ->execute();
      break;

    case 'user_cancel_delete':
      // Delete nodes (current revisions).
      $nodes = db_select('node', 'n')
        ->fields('n', array('nid'))
        ->condition('uid', $account->uid)
        ->execute()
        ->fetchCol();
      foreach ($nodes as $nid) {
        node_delete($nid);
      }
      // Delete old revisions.
      db_delete('node_revision')
        ->condition('uid', $account->uid)
        ->execute();
      // Clean history.
      db_delete('history')
        ->condition('uid', $account->uid)
        ->execute();
      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.
 *
 * @param &$methods
 *   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'),
  );
}

/**
 * Add mass user operations.
 *
 * This hook enables modules to inject custom operations into the mass operations
 * dropdown found at admin/people, by associating a callback function with
 * 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',
    ),
    'cancel' => array(
      'label' => t('Cancel the selected user accounts'),
    ),
  );
  return $operations;
}

/**
 * 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(
    'name' => 'account',
    'title' => t('Account settings'),
    'weight' => 1,
  ));
}

/**
 * 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.
 *
 * @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.
 *
 * @see hook_user_presave()
 * @see hook_user_update()
 */
function hook_user_insert(&$edit, $account, $category) {
  db_insert('mytable')
    ->fields(array(
      'myfield' => $edit['myfield'],
      '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
 *   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'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' => format_username($account)))))),
      '#attributes' => array('class' => array('blog')),
    );
  }
}

/**
 * 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.
 * If your module stores references to roles, it's recommended that you 
 * 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();
}

/**
 * @} End of "addtogroup hooks".
 */
1	<?php
2	// $Id: user.api.php,v 1.14 2009/10/10 16:48:39 webchick Exp $
3
4	/**
5	* @file
6	* Hooks provided by the User module.
7	*/
8
9	/**
10	* @addtogroup hooks
11	* @{
12	*/
13
14	/**
15	* Act on user objects when loaded from the database.
16	*
17	* Due to the static cache in user_load_multiple() you should not use this
18	* hook to modify the user properties returned by the {users} table itself
19	* since this may result in unreliable results when loading from cache.
20	*
21	* @param $users
22	* An array of user objects, indexed by uid.
23	*
24	* @see user_load_multiple()
25	* @see profile_user_load()
26	*/
27	function hook_user_load($users) {
28	$result = db_query('SELECT * FROM {my_table} WHERE uid IN (:uids)', array(':uids' => array_keys($users)));
29	foreach ($result as $record) {
30	$users[$record->uid]->foo = $result->foo;
31	}
32	}
33
34	/**
35	* Act on user account cancellations.
36	*
37	* The user account is being canceled. Depending on the account cancellation
38	* method, the module should either do nothing, unpublish content, anonymize
39	* content, or delete content and data belonging to the canceled user account.
40	*
41	* Expensive operations should be added to the global batch with batch_set().
42	*
43	* @param $edit
44	* The array of form values submitted by the user.
45	* @param $account
46	* The user object on which the operation is being performed.
47	* @param $method
48	* The account cancellation method.
49	*
50	* @see user_cancel_methods()
51	* @see hook_user_cancel_methods_alter()
52	* @see user_cancel()
53	*/
54	function hook_user_cancel($edit, $account, $method) {
55	switch ($method) {
56	case 'user_cancel_block_unpublish':
57	// Unpublish nodes (current revisions).
58	module_load_include('inc', 'node', 'node.admin');
59	$nodes = db_select('node', 'n')
60	->fields('n', array('nid'))
61	->condition('uid', $account->uid)
62	->execute()
63	->fetchCol();
64	node_mass_update($nodes, array('status' => 0));
65	break;
66
67	case 'user_cancel_reassign':
68	// Anonymize nodes (current revisions).
69	module_load_include('inc', 'node', 'node.admin');
70	$nodes = db_select('node', 'n')
71	->fields('n', array('nid'))
72	->condition('uid', $account->uid)
73	->execute()
74	->fetchCol();
75	node_mass_update($nodes, array('uid' => 0));
76	// Anonymize old revisions.
77	db_update('node_revision')
78	->fields(array('uid' => 0))
79	->condition('uid', $account->uid)
80	->execute();
81	// Clean history.
82	db_delete('history')
83	->condition('uid', $account->uid)
84	->execute();
85	break;
86
87	case 'user_cancel_delete':
88	// Delete nodes (current revisions).
89	$nodes = db_select('node', 'n')
90	->fields('n', array('nid'))
91	->condition('uid', $account->uid)
92	->execute()
93	->fetchCol();
94	foreach ($nodes as $nid) {
95	node_delete($nid);
96	}
97	// Delete old revisions.
98	db_delete('node_revision')
99	->condition('uid', $account->uid)
100	->execute();
101	// Clean history.
102	db_delete('history')
103	->condition('uid', $account->uid)
104	->execute();
105	break;
106	}
107	}
108
109	/**
110	* Modify account cancellation methods.
111	*
112	* By implementing this hook, modules are able to add, customize, or remove
113	* account cancellation methods. All defined methods are turned into radio
114	* button form elements by user_cancel_methods() after this hook is invoked.
115	* The following properties can be defined for each method:
116	* - title: The radio button's title.
117	* - description: (optional) A description to display on the confirmation form
118	* if the user is not allowed to select the account cancellation method. The
119	* description is NOT used for the radio button, but instead should provide
120	* additional explanation to the user seeking to cancel their account.
121	* - access: (optional) A boolean value indicating whether the user can access
122	* a method. If #access is defined, the method cannot be configured as default
123	* method.
124	*
125	* @param &$methods
126	* An array containing user account cancellation methods, keyed by method id.
127	*
128	* @see user_cancel_methods()
129	* @see user_cancel_confirm_form()
130	*/
131	function hook_user_cancel_methods_alter(&$methods) {
132	// Limit access to disable account and unpublish content method.
133	$methods['user_cancel_block_unpublish']['access'] = user_access('administer site configuration');
134
135	// Remove the content re-assigning method.
136	unset($methods['user_cancel_reassign']);
137
138	// Add a custom zero-out method.
139	$methods['mymodule_zero_out'] = array(
140	'title' => t('Delete the account and remove all content.'),
141	'description' => t('All your content will be replaced by empty strings.'),
142	// access should be used for administrative methods only.
143	'access' => user_access('access zero-out account cancellation method'),
144	);
145	}
146
147	/**
148	* Add mass user operations.
149	*
150	* This hook enables modules to inject custom operations into the mass operations
151	* dropdown found at admin/people, by associating a callback function with
152	* the operation, which is called when the form is submitted. The callback function
153	* receives one initial argument, which is an array of the checked users.
154	*
155	* @return
156	* An array of operations. Each operation is an associative array that may
157	* contain the following key-value pairs:
158	* - "label": Required. The label for the operation, displayed in the dropdown menu.
159	* - "callback": Required. The function to call for the operation.
160	* - "callback arguments": Optional. An array of additional arguments to pass to
161	* the callback function.
162	*
163	*/
164	function hook_user_operations() {
165	$operations = array(
166	'unblock' => array(
167	'label' => t('Unblock the selected users'),
168	'callback' => 'user_user_operations_unblock',
169	),
170	'block' => array(
171	'label' => t('Block the selected users'),
172	'callback' => 'user_user_operations_block',
173	),
174	'cancel' => array(
175	'label' => t('Cancel the selected user accounts'),
176	),
177	);
178	return $operations;
179	}
180
181	/**
182	* Retrieve a list of all user setting/information categories.
183	*
184	* @return
185	* A linear array of associative arrays. These arrays have keys:
186	* - "name": The internal name of the category.
187	* - "title": The human-readable, localized name of the category.
188	* - "weight": An integer specifying the category's sort ordering.
189	*/
190	function hook_user_categories() {
191	return array(array(
192	'name' => 'account',
193	'title' => t('Account settings'),
194	'weight' => 1,
195	));
196	}
197
198	/**
199	* A user account is about to be created or updated.
200	*
201	* This hook is primarily intended for modules that want to store properties in
202	* the serialized {users}.data column, which is automatically loaded whenever a
203	* user account object is loaded, and the module needs to prepare the stored
204	* data in some way.
205	* The module should save its custom additions to the user object into the
206	* database and set the saved fields to NULL in $edit.
207	*
208	* @param &$edit
209	* The array of form values submitted by the user.
210	* @param $account
211	* The user object on which the operation is performed.
212	* @param $category
213	* The active category of user information being edited.
214	*
215	* @see hook_user_insert()
216	* @see hook_user_update()
217	*/
218	function hook_user_presave(&$edit, $account, $category) {
219	// Make sure that our form value 'mymodule_foo' is stored as 'mymodule_bar'.
220	if (isset($edit['mymodule_foo'])) {
221	$edit['mymodule_bar'] = $edit['mymodule_foo'];
222	// Inform user_save() to ignore the value of our property.
223	$edit['mymodule_foo'] = NULL;
224	}
225	}
226
227	/**
228	* A user account was created.
229	*
230	* The module should save its custom additions to the user object into the
231	* database and set the saved fields to NULL in $edit.
232	*
233	* @param &$edit
234	* The array of form values submitted by the user.
235	* @param $account
236	* The user object on which the operation is being performed.
237	* @param $category
238	* The active category of user information being edited.
239	*
240	* @see hook_user_presave()
241	* @see hook_user_update()
242	*/
243	function hook_user_insert(&$edit, $account, $category) {
244	db_insert('mytable')
245	->fields(array(
246	'myfield' => $edit['myfield'],
247	'uid' => $account->uid,
248	))
249	->execute();
250	// Inform user_save() to ignore the value of our property.
251	$edit['myfield'] = NULL;
252	}
253
254	/**
255	* A user account was updated.
256	*
257	* Modules may use this hook to update their user data in a custom storage
258	* after a user account has been updated.
259	*
260	* @param &$edit
261	* The array of form values submitted by the user.
262	* @param $account
263	* The user object on which the operation is performed.
264	* @param $category
265	* The active category of user information being edited.
266	*
267	* @see hook_user_presave()
268	* @see hook_user_insert()
269	*/
270	function hook_user_update(&$edit, $account, $category) {
271	db_insert('user_changes')
272	->fields(array(
273	'uid' => $account->uid,
274	'changed' => time(),
275	))
276	->execute();
277	}
278
279	/**
280	* The user just logged in.
281	*
282	* @param &$edit
283	* The array of form values submitted by the user.
284	* @param $account
285	* The user object on which the operation was just performed.
286	*/
287	function hook_user_login(&$edit, $account) {
288	// If the user has a NULL time zone, notify them to set a time zone.
289	if (!$user->timezone && variable_get('configurable_timezones', 1) && variable_get('empty_timezone_message', 0)) {
290	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')))));
291	}
292	}
293
294	/**
295	* The user just logged out.
296	*
297	* @param $account
298	* The user object on which the operation was just performed.
299	*/
300	function hook_user_logout($account) {
301	db_insert('logouts')
302	->fields(array(
303	'uid' => $account->uid,
304	'time' => time(),
305	))
306	->execute();
307	}
308
309	/**
310	* The user's account information is being displayed.
311	*
312	* The module should format its custom additions for display and add them to the
313	* $account->content array.
314	*
315	* @param $account
316	* The user object on which the operation is being performed.
317	*/
318	function hook_user_view($account) {
319	if (user_access('create blog content', $account)) {
320	$account->content['summary']['blog'] = array(
321	'#type' => 'user_profile_item',
322	'#title' => t('Blog'),
323	'#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)))))),
324	'#attributes' => array('class' => array('blog')),
325	);
326	}
327	}
328
329	/**
330	* Inform other modules that a user role has been added.
331	*
332	* Modules implementing this hook can act on the user role object when saved to
333	* the database. It's recommended that you implement this hook if your module
334	* adds additional data to user roles object. The module should save its custom
335	* additions to the database.
336	*
337	* @param $role
338	* A user role object.
339	*/
340	function hook_user_role_insert($role) {
341	// Save extra fields provided by the module to user roles.
342	db_insert('my_module_table')
343	->fields(array(
344	'rid' => $role->rid,
345	'role_description' => $role->description,
346	))
347	->execute();
348	}
349
350	/**
351	* Inform other modules that a user role has been updated.
352	*
353	* Modules implementing this hook can act on the user role object when updated.
354	* It's recommended that you implement this hook if your module adds additional
355	* data to user roles object. The module should save its custom additions to
356	* the database.
357	*
358	* @param $role
359	* A user role object.
360	*/
361	function hook_user_role_update($role) {
362	// Save extra fields provided by the module to user roles.
363	db_merge('my_module_table')
364	->key(array('rid' => $role->rid))
365	->fields(array(
366	'role_description' => $role->description
367	))
368	->execute();
369	}
370
371	/**
372	* Inform other modules that a user role has been deleted.
373	*
374	* This hook allows you act when a user role has been deleted.
375	* If your module stores references to roles, it's recommended that you
376	* implement this hook and delete existing instances of the deleted role
377	* in your module database tables.
378	*
379	* @param $role
380	* The $role object being deleted.
381	*/
382	function hook_user_role_delete($role) {
383	// Delete existing instances of the deleted role.
384	db_delete('my_module_table')
385	->condition('rid', $role->rid)
386	->execute();
387	}
388
389	/**
390	* @} End of "addtogroup hooks".
391	*/