annotate core/lib/Drupal/Core/Session/AccountInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\Session;
Chris@0 4
Chris@0 5 /**
Chris@0 6 * Defines an account interface which represents the current user.
Chris@0 7 *
Chris@0 8 * Defines an object that has a user id, roles and can have session data. The
Chris@0 9 * interface is implemented both by the global session and the user entity.
Chris@0 10 *
Chris@0 11 * @ingroup user_api
Chris@0 12 */
Chris@0 13 interface AccountInterface {
Chris@0 14
Chris@0 15 /**
Chris@0 16 * Role ID for anonymous users.
Chris@0 17 */
Chris@0 18 const ANONYMOUS_ROLE = 'anonymous';
Chris@0 19
Chris@0 20 /**
Chris@0 21 * Role ID for authenticated users.
Chris@0 22 */
Chris@0 23 const AUTHENTICATED_ROLE = 'authenticated';
Chris@0 24
Chris@0 25 /**
Chris@0 26 * Returns the user ID or 0 for anonymous.
Chris@0 27 *
Chris@0 28 * @return int
Chris@0 29 * The user ID.
Chris@0 30 */
Chris@0 31 public function id();
Chris@0 32
Chris@0 33 /**
Chris@0 34 * Returns a list of roles.
Chris@0 35 *
Chris@0 36 * @param bool $exclude_locked_roles
Chris@0 37 * (optional) If TRUE, locked roles (anonymous/authenticated) are not returned.
Chris@0 38 *
Chris@0 39 * @return array
Chris@0 40 * List of role IDs.
Chris@0 41 */
Chris@0 42 public function getRoles($exclude_locked_roles = FALSE);
Chris@0 43
Chris@0 44 /**
Chris@0 45 * Checks whether a user has a certain permission.
Chris@0 46 *
Chris@0 47 * @param string $permission
Chris@0 48 * The permission string to check.
Chris@0 49 *
Chris@0 50 * @return bool
Chris@0 51 * TRUE if the user has the permission, FALSE otherwise.
Chris@0 52 */
Chris@0 53 public function hasPermission($permission);
Chris@0 54
Chris@0 55 /**
Chris@0 56 * Returns TRUE if the account is authenticated.
Chris@0 57 *
Chris@0 58 * @return bool
Chris@0 59 * TRUE if the account is authenticated.
Chris@0 60 */
Chris@0 61 public function isAuthenticated();
Chris@0 62
Chris@0 63 /**
Chris@0 64 * Returns TRUE if the account is anonymous.
Chris@0 65 *
Chris@0 66 * @return bool
Chris@0 67 * TRUE if the account is anonymous.
Chris@0 68 */
Chris@0 69 public function isAnonymous();
Chris@0 70
Chris@0 71 /**
Chris@0 72 * Returns the preferred language code of the account.
Chris@0 73 *
Chris@0 74 * @param bool $fallback_to_default
Chris@0 75 * (optional) Whether the return value will fall back to the site default
Chris@0 76 * language if the user has no language preference.
Chris@0 77 *
Chris@0 78 * @return string
Chris@17 79 * Returned language code depends upon following:
Chris@17 80 * - The user preferred language code is returned if set in the account.
Chris@17 81 * - If the user has no preferred language and $fallback_to_default is TRUE
Chris@17 82 * then the site default language code is returned.
Chris@17 83 * - If the user has no preferred language and $fallback_to_default is FALSE
Chris@17 84 * then empty string is returned.
Chris@0 85 */
Chris@0 86 public function getPreferredLangcode($fallback_to_default = TRUE);
Chris@0 87
Chris@0 88 /**
Chris@0 89 * Returns the preferred administrative language code of the account.
Chris@0 90 *
Chris@0 91 * Defines which language is used on administrative pages.
Chris@0 92 *
Chris@0 93 * @param bool $fallback_to_default
Chris@0 94 * (optional) Whether the return value will fall back to the site default
Chris@0 95 * language if the user has no administration language preference.
Chris@0 96 *
Chris@0 97 * @return string
Chris@0 98 * The language code that is preferred by the account for administration
Chris@0 99 * pages. If the preferred language is not set or is a language not
Chris@0 100 * configured anymore on the site, the site default is returned or an empty
Chris@0 101 * string is returned (if $fallback_to_default is FALSE).
Chris@0 102 */
Chris@0 103 public function getPreferredAdminLangcode($fallback_to_default = TRUE);
Chris@0 104
Chris@0 105 /**
Chris@0 106 * Returns the unaltered login name of this account.
Chris@0 107 *
Chris@0 108 * @return string
Chris@0 109 * An unsanitized plain-text string with the name of this account that is
Chris@0 110 * used to log in. Only display this name to admins and to the user who owns
Chris@0 111 * this account, and only in the context of the name used to log in. For
Chris@0 112 * any other display purposes, use
Chris@0 113 * \Drupal\Core\Session\AccountInterface::getDisplayName() instead.
Chris@0 114 *
Chris@0 115 * @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
Chris@0 116 * Use \Drupal\Core\Session\AccountInterface::getAccountName() or
Chris@0 117 * \Drupal\user\UserInterface::getDisplayName() instead.
Chris@17 118 *
Chris@17 119 * @see https://www.drupal.org/node/2572493
Chris@0 120 */
Chris@0 121 public function getUsername();
Chris@0 122
Chris@0 123 /**
Chris@0 124 * Returns the unaltered login name of this account.
Chris@0 125 *
Chris@0 126 * @return string
Chris@0 127 * An unsanitized plain-text string with the name of this account that is
Chris@0 128 * used to log in. Only display this name to admins and to the user who owns
Chris@0 129 * this account, and only in the context of the name used to login. For
Chris@0 130 * any other display purposes, use
Chris@0 131 * \Drupal\Core\Session\AccountInterface::getDisplayName() instead.
Chris@0 132 */
Chris@0 133 public function getAccountName();
Chris@0 134
Chris@0 135 /**
Chris@0 136 * Returns the display name of this account.
Chris@0 137 *
Chris@0 138 * By default, the passed-in object's 'name' property is used if it exists, or
Chris@0 139 * else, the site-defined value for the 'anonymous' variable. However, a
Chris@0 140 * module may override this by implementing
Chris@0 141 * hook_user_format_name_alter(&$name, $account).
Chris@0 142 *
Chris@0 143 * @see hook_user_format_name_alter()
Chris@0 144 *
Chris@0 145 * @return string|\Drupal\Component\Render\MarkupInterface
Chris@0 146 * Either a string that will be auto-escaped on output or a
Chris@0 147 * MarkupInterface object that is already HTML escaped. Either is safe
Chris@0 148 * to be printed within HTML fragments.
Chris@0 149 */
Chris@0 150 public function getDisplayName();
Chris@0 151
Chris@0 152 /**
Chris@0 153 * Returns the email address of this account.
Chris@0 154 *
Chris@14 155 * @return string|null
Chris@14 156 * The email address, or NULL if the account is anonymous or the user does
Chris@14 157 * not have an email address.
Chris@0 158 */
Chris@0 159 public function getEmail();
Chris@0 160
Chris@0 161 /**
Chris@0 162 * Returns the timezone of this account.
Chris@0 163 *
Chris@0 164 * @return string
Chris@0 165 * Name of the timezone.
Chris@0 166 */
Chris@0 167 public function getTimeZone();
Chris@0 168
Chris@0 169 /**
Chris@0 170 * The timestamp when the account last accessed the site.
Chris@0 171 *
Chris@0 172 * A value of 0 means the user has never accessed the site.
Chris@0 173 *
Chris@0 174 * @return int
Chris@0 175 * Timestamp of the last access.
Chris@0 176 */
Chris@0 177 public function getLastAccessedTime();
Chris@0 178
Chris@0 179 }