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