annotate core/modules/user/user.api.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 /**
Chris@0 4 * @file
Chris@0 5 * Hooks provided by the User module.
Chris@0 6 */
Chris@0 7
Chris@17 8 use Drupal\Core\Session\AccountInterface;
Chris@17 9 use Drupal\user\UserInterface;
Chris@17 10
Chris@0 11 /**
Chris@0 12 * @addtogroup hooks
Chris@0 13 * @{
Chris@0 14 */
Chris@0 15
Chris@0 16 /**
Chris@0 17 * Act on user account cancellations.
Chris@0 18 *
Chris@0 19 * This hook is invoked from user_cancel() before a user account is canceled.
Chris@0 20 * Depending on the account cancellation method, the module should either do
Chris@0 21 * nothing, unpublish content, or anonymize content. See user_cancel_methods()
Chris@0 22 * for the list of default account cancellation methods provided by User module.
Chris@0 23 * Modules may add further methods via hook_user_cancel_methods_alter().
Chris@0 24 *
Chris@0 25 * This hook is NOT invoked for the 'user_cancel_delete' account cancellation
Chris@0 26 * method. To react to that method, implement hook_ENTITY_TYPE_predelete() or
Chris@0 27 * hook_ENTITY_TYPE_delete() for user entities instead.
Chris@0 28 *
Chris@0 29 * Expensive operations should be added to the global account cancellation batch
Chris@0 30 * by using batch_set().
Chris@0 31 *
Chris@0 32 * @param array $edit
Chris@0 33 * The array of form values submitted by the user.
Chris@17 34 * @param \Drupal\user\UserInterface $account
Chris@0 35 * The user object on which the operation is being performed.
Chris@0 36 * @param string $method
Chris@0 37 * The account cancellation method.
Chris@0 38 *
Chris@0 39 * @see user_cancel_methods()
Chris@0 40 * @see hook_user_cancel_methods_alter()
Chris@0 41 */
Chris@17 42 function hook_user_cancel($edit, UserInterface $account, $method) {
Chris@0 43 switch ($method) {
Chris@0 44 case 'user_cancel_block_unpublish':
Chris@0 45 // Unpublish nodes (current revisions).
Chris@0 46 module_load_include('inc', 'node', 'node.admin');
Chris@0 47 $nodes = \Drupal::entityQuery('node')
Chris@0 48 ->condition('uid', $account->id())
Chris@0 49 ->execute();
Chris@0 50 node_mass_update($nodes, ['status' => 0], NULL, TRUE);
Chris@0 51 break;
Chris@0 52
Chris@0 53 case 'user_cancel_reassign':
Chris@0 54 // Anonymize nodes (current revisions).
Chris@0 55 module_load_include('inc', 'node', 'node.admin');
Chris@0 56 $nodes = \Drupal::entityQuery('node')
Chris@0 57 ->condition('uid', $account->id())
Chris@0 58 ->execute();
Chris@0 59 node_mass_update($nodes, ['uid' => 0], NULL, TRUE);
Chris@0 60 // Anonymize old revisions.
Chris@18 61 \Drupal::database()->update('node_field_revision')
Chris@0 62 ->fields(['uid' => 0])
Chris@0 63 ->condition('uid', $account->id())
Chris@0 64 ->execute();
Chris@0 65 break;
Chris@0 66 }
Chris@0 67 }
Chris@0 68
Chris@0 69 /**
Chris@0 70 * Modify account cancellation methods.
Chris@0 71 *
Chris@0 72 * By implementing this hook, modules are able to add, customize, or remove
Chris@0 73 * account cancellation methods. All defined methods are turned into radio
Chris@0 74 * button form elements by user_cancel_methods() after this hook is invoked.
Chris@0 75 * The following properties can be defined for each method:
Chris@0 76 * - title: The radio button's title.
Chris@0 77 * - description: (optional) A description to display on the confirmation form
Chris@0 78 * if the user is not allowed to select the account cancellation method. The
Chris@0 79 * description is NOT used for the radio button, but instead should provide
Chris@0 80 * additional explanation to the user seeking to cancel their account.
Chris@0 81 * - access: (optional) A boolean value indicating whether the user can access
Chris@0 82 * a method. If 'access' is defined, the method cannot be configured as
Chris@0 83 * default method.
Chris@0 84 *
Chris@0 85 * @param array $methods
Chris@0 86 * An array containing user account cancellation methods, keyed by method id.
Chris@0 87 *
Chris@0 88 * @see user_cancel_methods()
Chris@0 89 * @see \Drupal\user\Form\UserCancelForm
Chris@0 90 */
Chris@0 91 function hook_user_cancel_methods_alter(&$methods) {
Chris@0 92 $account = \Drupal::currentUser();
Chris@0 93 // Limit access to disable account and unpublish content method.
Chris@0 94 $methods['user_cancel_block_unpublish']['access'] = $account->hasPermission('administer site configuration');
Chris@0 95
Chris@0 96 // Remove the content re-assigning method.
Chris@0 97 unset($methods['user_cancel_reassign']);
Chris@0 98
Chris@0 99 // Add a custom zero-out method.
Chris@0 100 $methods['mymodule_zero_out'] = [
Chris@0 101 'title' => t('Delete the account and remove all content.'),
Chris@0 102 'description' => t('All your content will be replaced by empty strings.'),
Chris@0 103 // access should be used for administrative methods only.
Chris@0 104 'access' => $account->hasPermission('access zero-out account cancellation method'),
Chris@0 105 ];
Chris@0 106 }
Chris@0 107
Chris@0 108 /**
Chris@0 109 * Alter the username that is displayed for a user.
Chris@0 110 *
Chris@0 111 * Called by $account->getDisplayName() to allow modules to alter the username
Chris@0 112 * that is displayed. Can be used to ensure user privacy in situations where
Chris@17 113 * $account->getDisplayName() is too revealing. This hook is invoked both for
Chris@17 114 * user entities and the anonymous user session object.
Chris@0 115 *
Chris@0 116 * @param string|Drupal\Component\Render\MarkupInterface $name
Chris@0 117 * The username that is displayed for a user. If a hook implementation changes
Chris@0 118 * this to an object implementing MarkupInterface it is the responsibility of
Chris@0 119 * the implementation to ensure the user's name is escaped properly. String
Chris@0 120 * values will be autoescaped.
Chris@0 121 * @param \Drupal\Core\Session\AccountInterface $account
Chris@17 122 * The object on which the operation is being performed. This object may be a
Chris@17 123 * user entity. If the object is an implementation of UserInterface you can
Chris@17 124 * use instanceof operator before accessing user entity methods. For example:
Chris@17 125 * @code
Chris@17 126 * if ($account instanceof UserInterface) {
Chris@17 127 * // Access user entity methods.
Chris@17 128 * }
Chris@17 129 * @endcode
Chris@0 130 *
Chris@0 131 * @see \Drupal\Core\Session\AccountInterface::getDisplayName()
Chris@0 132 * @see sanitization
Chris@0 133 */
Chris@17 134 function hook_user_format_name_alter(&$name, AccountInterface $account) {
Chris@0 135 // Display the user's uid instead of name.
Chris@0 136 if ($account->id()) {
Chris@0 137 $name = t('User @uid', ['@uid' => $account->id()]);
Chris@0 138 }
Chris@0 139 }
Chris@0 140
Chris@0 141 /**
Chris@0 142 * The user just logged in.
Chris@0 143 *
Chris@17 144 * @param \Drupal\user\UserInterface $account
Chris@0 145 * The user object on which the operation was just performed.
Chris@0 146 */
Chris@17 147 function hook_user_login(UserInterface $account) {
Chris@0 148 $config = \Drupal::config('system.date');
Chris@0 149 // If the user has a NULL time zone, notify them to set a time zone.
Chris@0 150 if (!$account->getTimezone() && $config->get('timezone.user.configurable') && $config->get('timezone.user.warn')) {
Chris@17 151 \Drupal::messenger()
Chris@17 152 ->addStatus(t('Configure your <a href=":user-edit">account time zone setting</a>.', [
Chris@18 153 ':user-edit' => $account->toUrl('edit-form', [
Chris@17 154 'query' => \Drupal::destination()
Chris@17 155 ->getAsArray(),
Chris@17 156 'fragment' => 'edit-timezone',
Chris@18 157 ])->toString(),
Chris@17 158 ]));
Chris@0 159 }
Chris@0 160 }
Chris@0 161
Chris@0 162 /**
Chris@0 163 * The user just logged out.
Chris@0 164 *
Chris@17 165 * @param \Drupal\Core\Session\AccountInterface $account
Chris@0 166 * The user object on which the operation was just performed.
Chris@0 167 */
Chris@17 168 function hook_user_logout(AccountInterface $account) {
Chris@18 169 \Drupal::database()->insert('logouts')
Chris@0 170 ->fields([
Chris@0 171 'uid' => $account->id(),
Chris@0 172 'time' => time(),
Chris@0 173 ])
Chris@0 174 ->execute();
Chris@0 175 }
Chris@0 176
Chris@0 177 /**
Chris@0 178 * @} End of "addtogroup hooks".
Chris@0 179 */