diff --git a/core/modules/user/src/AccountForm.php b/core/modules/user/src/AccountForm.php index 7ed3cbd..bdef4a8 100644 --- a/core/modules/user/src/AccountForm.php +++ b/core/modules/user/src/AccountForm.php @@ -46,7 +46,7 @@ * The entity manager. * @param \Drupal\Core\Language\LanguageManagerInterface $language_manager * The language manager. - * @param \Drupal\Core\Entity\Query\QueryFactory + * @param \Drupal\Core\Entity\Query\QueryFactory $entity_query * The entity query factory. */ public function __construct(EntityManagerInterface $entity_manager, LanguageManagerInterface $language_manager, QueryFactory $entity_query) { diff --git a/core/modules/user/src/Plugin/views/field/Link.php b/core/modules/user/src/Plugin/views/field/Link.php index b62d80e..a83d600 100644 --- a/core/modules/user/src/Plugin/views/field/Link.php +++ b/core/modules/user/src/Plugin/views/field/Link.php @@ -80,6 +80,7 @@ public function render(ResultRow $values) { * Alters the field to render a link. * * @param \Drupal\Core\Entity\EntityInterface $entity + * The entity to render. * @param \Drupal\views\ResultRow $values * The current row of the views result. * diff --git a/core/modules/user/src/Plugin/views/wizard/Users.php b/core/modules/user/src/Plugin/views/wizard/Users.php index 1052476..e1681c9 100644 --- a/core/modules/user/src/Plugin/views/wizard/Users.php +++ b/core/modules/user/src/Plugin/views/wizard/Users.php @@ -10,10 +10,6 @@ use Drupal\views\Plugin\views\wizard\WizardPluginBase; /** - * @todo: replace numbers with constants. - */ - -/** * Tests creating user views with the wizard. * * @ViewsWizard( @@ -21,6 +17,8 @@ * base_table = "users", * title = @Translation("Users") * ) + * + * @todo: replace numbers with constants. */ class Users extends WizardPluginBase { diff --git a/core/modules/user/src/Tests/UserLoginTest.php b/core/modules/user/src/Tests/UserLoginTest.php index 0235983..949ec2e 100644 --- a/core/modules/user/src/Tests/UserLoginTest.php +++ b/core/modules/user/src/Tests/UserLoginTest.php @@ -140,11 +140,14 @@ function testPasswordRehashOnLogin() { /** * Make an unsuccessful login attempt. * - * @param $account + * @param \Drupal\user\Entity\User $account * A user object with name and pass_raw attributes for the login attempt. - * @param $flood_trigger - * Whether or not to expect that the flood control mechanism will be - * triggered. + * @param mixed $flood_trigger + * (optional) Whether or not to expect that the flood control mechanism will + * be triggered. Defaults to NULL. + * - Set to 'user' to expect a 'too many failed logins error. + * - Set to any value to expect an error for too many failed logins per IP. + * - Set to NULL to expect a failed login. */ function assertFailedLogin($account, $flood_trigger = NULL) { $edit = array( diff --git a/core/modules/user/src/UserStorageInterface.php b/core/modules/user/src/UserStorageInterface.php index 104c4ae..afcfcfb 100644 --- a/core/modules/user/src/UserStorageInterface.php +++ b/core/modules/user/src/UserStorageInterface.php @@ -13,12 +13,13 @@ /** * Defines an interface for user entity storage classes. */ -interface UserStorageInterface extends EntityStorageInterface{ +interface UserStorageInterface extends EntityStorageInterface { /** * Update the last login timestamp of the user. * * @param \Drupal\user\UserInterface $account + * User object to change. */ public function updateLastLoginTimestamp(UserInterface $account); diff --git a/core/modules/user/user.api.php b/core/modules/user/user.api.php index 928a56a..48faffb 100644 --- a/core/modules/user/user.api.php +++ b/core/modules/user/user.api.php @@ -28,11 +28,11 @@ * Expensive operations should be added to the global account cancellation batch * by using batch_set(). * - * @param $edit + * @param array $edit * The array of form values submitted by the user. - * @param $account + * @param object $account * The user object on which the operation is being performed. - * @param $method + * @param string $method * The account cancellation method. * * @see user_cancel_methods() @@ -81,7 +81,7 @@ function hook_user_cancel($edit, $account, $method) { * a method. If 'access' is defined, the method cannot be configured as * default method. * - * @param $methods + * @param array $methods * An array containing user account cancellation methods, keyed by method id. * * @see user_cancel_methods() @@ -111,10 +111,10 @@ function hook_user_cancel_methods_alter(&$methods) { * displayed. Can be used to ensure user privacy in situations where * $account->name is too revealing. * - * @param $name + * @param string $name * The string that user_format_name() will return. * - * @param $account + * @param object $account * The account object passed to user_format_name(). * * @see user_format_name() @@ -129,7 +129,7 @@ function hook_user_format_name_alter(&$name, $account) { /** * The user just logged in. * - * @param $account + * @param object $account * The user object on which the operation was just performed. */ function hook_user_login($account) { @@ -143,7 +143,7 @@ function hook_user_login($account) { /** * The user just logged out. * - * @param $account + * @param object $account * The user object on which the operation was just performed. */ function hook_user_logout($account) { diff --git a/core/modules/user/user.module b/core/modules/user/user.module index fa26302..efb43cd 100644 --- a/core/modules/user/user.module +++ b/core/modules/user/user.module @@ -1,5 +1,10 @@ getPreferredLangcode(); return \Drupal::url('user.reset', @@ -673,7 +674,7 @@ function user_pass_reset_url($account, $options = array()) { /** * Generates a URL to confirm an account cancellation request. * - * @param object $account + * @param Drupal\user\UserInterface $account * The user account object, which must contain at least the following * properties: * - uid: The user ID number. @@ -684,14 +685,14 @@ function user_pass_reset_url($account, $options = array()) { * - langcode: A language code to be used when generating locale-sensitive * URLs. If langcode is NULL the users preferred language is used. * - * @return + * @return string * A unique URL that may be used to confirm the cancellation of the user * account. * * @see user_mail_tokens() * @see \Drupal\user\Controller\UserController::confirmCancel() */ -function user_cancel_url($account, $options = array()) { +function user_cancel_url(UserInterface $account, $options = array()) { $timestamp = REQUEST_TIME; $langcode = isset($options['langcode']) ? $options['langcode'] : $account->getPreferredLangcode(); $url_options = array('absolute' => TRUE, 'language' => \Drupal::languageManager()->getLanguage($langcode)); @@ -721,7 +722,7 @@ function user_cancel_url($account, $options = array()) { * @param int $login * The UNIX timestamp of the user's last login. * - * @return + * @return string * A string that is safe for use in URLs and SQL statements. */ function user_pass_rehash($password, $timestamp, $login) { @@ -735,11 +736,11 @@ function user_pass_rehash($password, $timestamp, $login) { * Form API will invoke it, or batch_process() needs to be invoked after calling * this function and should define the path to redirect to. * - * @param $edit + * @param array $edit * An array of submitted form values. - * @param $uid + * @param int $uid * The user ID of the user account to cancel. - * @param $method + * @param string $method * The account cancellation method to use. * * @see _user_cancel() @@ -796,6 +797,13 @@ function user_cancel($edit, $uid, $method) { * Since batch and session API require a valid user account, the actual * cancellation of a user account needs to happen last. * + * @param array $edit + * An array of submitted form values. + * @param Drupal\user\UserInterface $account + * The user ID of the user account to cancel. + * @param string $method + * The account cancellation method to use. + * * @see user_cancel() */ function _user_cancel($edit, $account, $method) { @@ -907,7 +915,7 @@ function user_cancel_methods() { /** * Delete a user. * - * @param $uid + * @param int $uid * A user ID. */ function user_delete($uid) { @@ -917,7 +925,7 @@ function user_delete($uid) { /** * Delete multiple user accounts. * - * @param $uids + * @param int[] $uids * An array of user IDs. * * @see hook_ENTITY_TYPE_predelete() @@ -940,33 +948,33 @@ function user_delete_multiple(array $uids) { * To theme user profiles, copy core/modules/user/templates/user.html.twig * to your theme directory, and edit it as instructed in that file's comments. * - * @param $account + * @param \Drupal\user\UserInterface $account * A user object. - * @param $view_mode + * @param string $view_mode * View mode, e.g. 'full'. - * @param $langcode + * @param string|NULL $langcode * (optional) A language code to use for rendering. Defaults to the global * content language of the current request. * - * @return + * @return array * An array as expected by drupal_render(). */ -function user_view($account, $view_mode = 'full', $langcode = NULL) { +function user_view(UserInterface $account, $view_mode = 'full', $langcode = NULL) { return entity_view($account, $view_mode, $langcode); } /** * Constructs a drupal_render() style array from an array of loaded users. * - * @param $accounts + * @param \Drupal\user\UserInterface[] $account * An array of user accounts as returned by user_load_multiple(). - * @param $view_mode - * (optional) View mode, e.g., 'full', 'teaser'... Defaults to 'teaser.' - * @param $langcode + * @param string $view_mode + * (optional) View mode, e.g., 'full', 'teaser'... Defaults to 'teaser'. + * @param string|NULL $langcode * (optional) A language code to use for rendering. Defaults to the global * content language of the current request. * - * @return + * @return array * An array in the format expected by drupal_render(). */ function user_view_multiple($accounts, $view_mode = 'full', $langcode = NULL) { @@ -1004,17 +1012,18 @@ function user_mail($key, &$message, $params) { * some additional tokens that can be used in email messages generated by * user_mail(). * - * @param $replacements + * @param array $replacements * An associative array variable containing mappings from token names to * values (for use with strtr()). - * @param $data + * @param array $data * An associative array of token replacement values. If the 'user' element * exists, it must contain a user account object with the following * properties: * - login: The UNIX timestamp of the user's last login. * - pass: The hashed account login password. - * @param $options - * Unused parameter required by \Drupal\Core\Utility\Token::replace(). + * @param array $options + * A keyed array of settings and flags to control the token replacement + * process. See \Drupal\Core\Utility\Token::replace(). */ function user_mail_tokens(&$replacements, $data, $options) { if (isset($data['user'])) { @@ -1026,17 +1035,17 @@ function user_mail_tokens(&$replacements, $data, $options) { /*** Administrative features ***********************************************/ /** - * Retrieve an array of roles matching specified conditions. + * Retrieve the names of roles matching specified conditions. * - * @param $membersonly - * Set this to TRUE to exclude the 'anonymous' role. - * @param $permission - * A string containing a permission. If set, only roles containing that - * permission are returned. + * @param bool $membersonly + * (optional) Set this to TRUE to exclude the 'anonymous' role. Defaults to + * FALSE. + * @param string|NULL $permission + * (optional) A string containing a permission. If set, only roles containing + * that permission are returned. Defaults to NULL, which returns all roles. * - * @return - * An associative array with the role id as the key and the role name as - * value. + * @return array + * An array of the names of the roles. */ function user_role_names($membersonly = FALSE, $permission = NULL) { return array_map(function ($item) { @@ -1102,14 +1111,15 @@ function user_user_role_delete(RoleInterface $role) { /** * Retrieve an array of roles matching specified conditions. * - * @param $membersonly - * Set this to TRUE to exclude the 'anonymous' role. - * @param $permission - * A string containing a permission. If set, only roles containing that - * permission are returned. + * @param bool $membersonly + * (optional) Set this to TRUE to exclude the 'anonymous' role. Defaults to + * FALSE. + * @param string|NULL $permission + * (optional) A string containing a permission. If set, only roles containing + * that permission are returned. Defaults to NULL, which returns all roles. * - * @return - * An associative array with the role id as the key and the role object as + * @return array + * An associative array with the role id as the key and the role name as * value. */ function user_roles($membersonly = FALSE, $permission = NULL) { @@ -1145,10 +1155,10 @@ function user_roles($membersonly = FALSE, $permission = NULL) { /** * Fetches a user role by role ID. * - * @param $rid + * @param string $rid * A string representing the role ID. * - * @return + * @return \Drupal\user\RoleInterface|NULL * A fully-loaded role object if a role with the given ID exists, or NULL * otherwise. * @@ -1167,13 +1177,13 @@ function user_role_load($rid) { * role, the form submit handler may directly pass the submitted values for the * checkboxes form element to this function. * - * @param $rid + * @param mixed $rid * The ID of a user role to alter. - * @param $permissions - * An associative array, where the key holds the permission name and the value - * determines whether to grant or revoke that permission. Any value that - * evaluates to TRUE will cause the permission to be granted. Any value that - * evaluates to FALSE will cause the permission to be revoked. + * @param array $permissions + * (optional) An associative array, where the key holds the permission name + * and the value determines whether to grant or revoke that permission. Any + * value that evaluates to TRUE will cause the permission to be granted. Any + * value that evaluates to FALSE will cause the permission to be revoked. * @code * array( * 'administer nodes' => 0, // Revoke 'administer nodes' @@ -1204,10 +1214,10 @@ function user_role_change_permissions($rid, array $permissions = array()) { /** * Grant permissions to a user role. * - * @param $rid + * @param mixed $rid * The ID of a user role to alter. - * @param $permissions - * A list of permission names to grant. + * @param array $permissions + * (optional) A list of permission names to grant. * * @see user_role_change_permissions() * @see user_role_revoke_permissions() @@ -1224,10 +1234,10 @@ function user_role_grant_permissions($rid, array $permissions = array()) { /** * Revoke permissions from a user role. * - * @param $rid + * @param mixed $rid * The ID of a user role to alter. - * @param $permissions - * A list of permission names to revoke. + * @param array $permissions + * (optional) A list of permission names to revoke. * * @see user_role_change_permissions() * @see user_role_grant_permissions() @@ -1245,10 +1255,7 @@ function user_role_revoke_permissions($rid, array $permissions = array()) { * Conditionally create and send a notification email when a certain * operation happens on the given user account. * - * @see user_mail_tokens() - * @see \Drupal\Core\Mail\MailManagerInterface::mail() - * - * @param $op + * @param string $op * The operation being performed on the account. Possible values: * - 'register_admin_created': Welcome message for user created by the admin. * - 'register_no_approval_required': Welcome message when user @@ -1260,19 +1267,20 @@ function user_role_revoke_permissions($rid, array $permissions = array()) { * - 'status_blocked': Account blocked. * - 'cancel_confirm': Account cancellation request. * - 'status_canceled': Account canceled. - * - * @param $account + * @param \Drupal\Core\Session\AccountInterface $account * The user object of the account being notified. Must contain at * least the fields 'uid', 'name', and 'mail'. - * @param $langcode - * Optional language code to use for the notification, overriding account + * @param string $langcode + * (optional) Language code to use for the notification, overriding account * language. * - * @return - * The return value from \Drupal::service('plugin.manager.mail')->mail(), if - * ends up being called. + * @return array + * An array containint various information about the message. + * See \Drupal\Core\Mail\MailManagerInterface::mail() for details. + * + * @see user_mail_tokens() */ -function _user_mail_notify($op, $account, $langcode = NULL) { +function _user_mail_notify($op, AccountInterface $account, $langcode = NULL) { // By default, we always notify except for canceled and blocked. $notify = \Drupal::config('user.settings')->get('notify.' . $op); if ($notify || ($op != 'status_canceled' && $op != 'status_blocked')) { @@ -1382,7 +1390,7 @@ function user_modules_uninstalled($modules) { /** * Saves visitor information as a cookie so it can be reused. * - * @param $values + * @param array $values * An array of key/value pairs to be saved into a cookie. */ function user_cookie_save(array $values) { @@ -1395,7 +1403,7 @@ function user_cookie_save(array $values) { /** * Delete a visitor information cookie. * - * @param $cookie_name + * @param string $cookie_name * A cookie name such as 'homepage'. */ function user_cookie_delete($cookie_name) {