enmi-conf.org: comparison wp/wp-includes/class-wp-user.php

equal deleted inserted replaced

-:c7c34916027a
+:177826044cd9
 	/**
 	 * All capabilities the user has, including individual and role based.
 	 *
 	 * @since 2.0.0
-	 * @var array
+	 * @var bool[] Array of key/value pairs where keys represent a capability name and boolean values
+	 *             represent whether the user has that capability.
 	 */
 	public $allcaps = array();
 	/**
 	 * The filter context applied to user data fields.
 	 * @var int
 	 */
 	private $site_id = 0;
 	/**
-	 * @static
 	 * @since 3.3.0
 	 * @var array
 	 */
 	private static $back_compat_keys;
 	 * Constructor.
 	 *
 	 * Retrieves the userdata and passes it to WP_User::init().
 	 *
 	 * @since 2.0.0
-	 *
-	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
 	 * @param int|string|stdClass|WP_User $id User's ID, a WP_User object, or a user object from the DB.
 	 * @param string $name Optional. User's username
 	 * @param int $site_id Optional Site ID, defaults to current site.
 	 */
 	public function __construct( $id = 0, $name = '', $site_id = '' ) {
 		if ( ! isset( self::$back_compat_keys ) ) {
-			$prefix = $GLOBALS['wpdb']->prefix;
+			$prefix                 = $GLOBALS['wpdb']->prefix;
 			self::$back_compat_keys = array(
-				'user_firstname' => 'first_name',
+				'user_firstname'             => 'first_name',
-				'user_lastname' => 'last_name',
+				'user_lastname'              => 'last_name',
-				'user_description' => 'description',
+				'user_description'           => 'description',
-				'user_level' => $prefix . 'user_level',
+				'user_level'                 => $prefix . 'user_level',
-				$prefix . 'usersettings' => $prefix . 'user-settings',
+				$prefix . 'usersettings'     => $prefix . 'user-settings',
 				$prefix . 'usersettingstime' => $prefix . 'user-settings-time',
 			);
 		}
 		if ( $id instanceof WP_User ) {
 			return;
 		}
 		if ( ! empty( $id ) && ! is_numeric( $id ) ) {
 			$name = $id;
-			$id = 0;
+			$id   = 0;
 		}
 		if ( $id ) {
 			$data = self::get_data_by( 'id', $id );
 		} else {
 	 * @param object $data    User DB row object.
 	 * @param int    $site_id Optional. The site ID to initialize for.
 	 */
 	public function init( $data, $site_id = '' ) {
 		$this->data = $data;
-		$this->ID = (int) $data->ID;
+		$this->ID   = (int) $data->ID;
 		$this->for_site( $site_id );
 	}
 	/**
 	 * Return only the main user fields
 	 *
 	 * @since 3.3.0
 	 * @since 4.4.0 Added 'ID' as an alias of 'id' for the `$field` parameter.
-	 *
-	 * @static
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
 	 * @param string $field The field to query against: 'id', 'ID', 'slug', 'email' or 'login'.
 	 * @param string|int $value The field value
 		}
 		if ( 'id' == $field ) {
 			// Make sure the value is numeric to avoid casting objects, for example,
 			// to int 1.
-			if ( ! is_numeric( $value ) )
+			if ( ! is_numeric( $value ) ) {
 				return false;
+			}
 			$value = intval( $value );
-			if ( $value < 1 )
+			if ( $value < 1 ) {
 				return false;
+			}
 		} else {
 			$value = trim( $value );
 		}
-		if ( !$value )
+		if ( ! $value ) {
 			return false;
+		}
 		switch ( $field ) {
 			case 'id':
-				$user_id = $value;
+				$user_id  = $value;
 				$db_field = 'ID';
 				break;
 			case 'slug':
-				$user_id = wp_cache_get($value, 'userslugs');
+				$user_id  = wp_cache_get( $value, 'userslugs' );
 				$db_field = 'user_nicename';
 				break;
 			case 'email':
-				$user_id = wp_cache_get($value, 'useremail');
+				$user_id  = wp_cache_get( $value, 'useremail' );
 				$db_field = 'user_email';
 				break;
 			case 'login':
-				$value = sanitize_user( $value );
+				$value    = sanitize_user( $value );
-				$user_id = wp_cache_get($value, 'userlogins');
+				$user_id  = wp_cache_get( $value, 'userlogins' );
 				$db_field = 'user_login';
 				break;
 			default:
 				return false;
 		}
 		if ( false !== $user_id ) {
-			if ( $user = wp_cache_get( $user_id, 'users' ) )
+			if ( $user = wp_cache_get( $user_id, 'users' ) ) {
 				return $user;
-		}
+			}
+		}
-		if ( !$user = $wpdb->get_row( $wpdb->prepare(
-			"SELECT * FROM $wpdb->users WHERE $db_field = %s", $value
+		if ( ! $user = $wpdb->get_row(
-		) ) )
+			$wpdb->prepare(
+				"SELECT * FROM $wpdb->users WHERE $db_field = %s LIMIT 1",
+				$value
+			)
+		) ) {
 			return false;
+		}
 		update_user_caches( $user );
 		return $user;
 	}
 	 * @param string $key User meta key to check if set.
 	 * @return bool Whether the given user meta key is set.
 	 */
 	public function __isset( $key ) {
 		if ( 'id' == $key ) {
-			_deprecated_argument( 'WP_User->id', '2.1.0',
+			_deprecated_argument(
+				'WP_User->id',
+				'2.1.0',
 				sprintf(
 					/* translators: %s: WP_User->ID */
 					__( 'Use %s instead.' ),
 					'<code>WP_User->ID</code>'
 				)
 			);
 			$key = 'ID';
 		}
-		if ( isset( $this->data->$key ) )
+		if ( isset( $this->data->$key ) ) {
 			return true;
+		}
-		if ( isset( self::$back_compat_keys[ $key ] ) )
+		if ( isset( self::$back_compat_keys[ $key ] ) ) {
 			$key = self::$back_compat_keys[ $key ];
+		}
 		return metadata_exists( 'user', $this->ID, $key );
 	}
 	/**
 	 * @param string $key User meta key to retrieve.
 	 * @return mixed Value of the given user meta key (if set). If `$key` is 'id', the user ID.
 	 */
 	public function __get( $key ) {
 		if ( 'id' == $key ) {
-			_deprecated_argument( 'WP_User->id', '2.1.0',
+			_deprecated_argument(
+				'WP_User->id',
+				'2.1.0',
 				sprintf(
 					/* translators: %s: WP_User->ID */
 					__( 'Use %s instead.' ),
 					'<code>WP_User->ID</code>'
 				)
 		}
 		if ( isset( $this->data->$key ) ) {
 			$value = $this->data->$key;
 		} else {
-			if ( isset( self::$back_compat_keys[ $key ] ) )
+			if ( isset( self::$back_compat_keys[ $key ] ) ) {
 				$key = self::$back_compat_keys[ $key ];
+			}
 			$value = get_user_meta( $this->ID, $key, true );
 		}
 		if ( $this->filter ) {
 			$value = sanitize_user_field( $key, $value, $this->ID, $this->filter );
 	 * @param string $key   User meta key.
 	 * @param mixed  $value User meta value.
 	 */
 	public function __set( $key, $value ) {
 		if ( 'id' == $key ) {
-			_deprecated_argument( 'WP_User->id', '2.1.0',
+			_deprecated_argument(
+				'WP_User->id',
+				'2.1.0',
 				sprintf(
 					/* translators: %s: WP_User->ID */
 					__( 'Use %s instead.' ),
 					'<code>WP_User->ID</code>'
 				)
 	 *
 	 * @param string $key User meta key to unset.
 	 */
 	public function __unset( $key ) {
 		if ( 'id' == $key ) {
-			_deprecated_argument( 'WP_User->id', '2.1.0',
+			_deprecated_argument(
+				'WP_User->id',
+				'2.1.0',
 				sprintf(
 					/* translators: %s: WP_User->ID */
 					__( 'Use %s instead.' ),
 					'<code>WP_User->ID</code>'
 				)
 	/**
 	 * Makes private/protected methods readable for backward compatibility.
 	 *
 	 * @since 4.3.0
 	 *
-	 * @param callable $name      Method to call.
+	 * @param string   $name      Method to call.
 	 * @param array    $arguments Arguments to pass when calling.
 	 * @return mixed|false Return value of the callback, false otherwise.
 	 */
 	public function __call( $name, $arguments ) {
 		if ( '_init_caps' === $name ) {
 		$this->get_role_caps();
 	}
 	/**
-	 * Retrieve all of the role capabilities and merge with individual capabilities.
+	 * Retrieves all of the capabilities of the roles of the user, and merges them with individual user capabilities.
 	 *
-	 * All of the capabilities of the roles the user belongs to are merged with
+	 * All of the capabilities of the roles of the user are merged with the user's individual capabilities. This means
-	 * the users individual roles. This also means that the user can be denied
+	 * that the user can be denied specific capabilities that their role might have, but the user is specifically denied.
-	 * specific roles that their role might have, but the specific user isn't
+	 *
-	 * granted permission to.
+	 * @since 2.0.0
 	 *
-	 * @since 2.0.0
+	 * @return bool[] Array of key/value pairs where keys represent a capability name and boolean values
-	 *
+	 *                represent whether the user has that capability.
-	 * @return array List of all capabilities for the user.
 	 */
 	public function get_role_caps() {
 		$switch_site = false;
 		if ( is_multisite() && $this->site_id != get_current_blog_id() ) {
 			$switch_site = true;
 			switch_to_blog( $this->site_id );
 		}
 		$wp_roles = wp_roles();
-		//Filter out caps that are not role names and assign to $this->roles
+		// Filter out caps that are not role names and assign to $this->roles.
-		if ( is_array( $this->caps ) )
+		if ( is_array( $this->caps ) ) {
 			$this->roles = array_filter( array_keys( $this->caps ), array( $wp_roles, 'is_role' ) );
+		}
-		//Build $allcaps from role caps, overlay user's $caps
+		// Build $allcaps from role caps, overlay user's $caps.
 		$this->allcaps = array();
 		foreach ( (array) $this->roles as $role ) {
-			$the_role = $wp_roles->get_role( $role );
+			$the_role      = $wp_roles->get_role( $role );
 			$this->allcaps = array_merge( (array) $this->allcaps, (array) $the_role->capabilities );
 		}
 		$this->allcaps = array_merge( (array) $this->allcaps, (array) $this->caps );
 		if ( $switch_site ) {
 	public function add_role( $role ) {
 		if ( empty( $role ) ) {
 			return;
 		}
-		$this->caps[$role] = true;
+		$this->caps[ $role ] = true;
 		update_user_meta( $this->ID, $this->cap_key, $this->caps );
 		$this->get_role_caps();
 		$this->update_user_level_from_caps();
 		/**
 	 * @since 2.0.0
 	 *
 	 * @param string $role Role name.
 	 */
 	public function remove_role( $role ) {
-		if ( !in_array($role, $this->roles) )
+		if ( ! in_array( $role, $this->roles ) ) {
 			return;
-		unset( $this->caps[$role] );
+		}
+		unset( $this->caps[ $role ] );
 		update_user_meta( $this->ID, $this->cap_key, $this->caps );
 		$this->get_role_caps();
 		$this->update_user_level_from_caps();
 		/**
 	 * @since 2.0.0
 	 *
 	 * @param string $role Role name.
 	 */
 	public function set_role( $role ) {
-		if ( 1 == count( $this->roles ) && $role == current( $this->roles ) )
+		if ( 1 == count( $this->roles ) && $role == current( $this->roles ) ) {
 			return;
+		}
-		foreach ( (array) $this->roles as $oldrole )
-			unset( $this->caps[$oldrole] );
+		foreach ( (array) $this->roles as $oldrole ) {
+			unset( $this->caps[ $oldrole ] );
+		}
 		$old_roles = $this->roles;
-		if ( !empty( $role ) ) {
+		if ( ! empty( $role ) ) {
-			$this->caps[$role] = true;
+			$this->caps[ $role ] = true;
-			$this->roles = array( $role => true );
+			$this->roles         = array( $role => true );
 		} else {
 			$this->roles = false;
 		}
 		update_user_meta( $this->ID, $this->cap_key, $this->caps );
 		$this->get_role_caps();
 		 * Fires after the user's role has changed.
 		 *
 		 * @since 2.9.0
 		 * @since 3.6.0 Added $old_roles to include an array of the user's previous roles.
 		 *
-		 * @param int    $user_id   The user ID.
+		 * @param int      $user_id   The user ID.
-		 * @param string $role      The new role.
+		 * @param string   $role      The new role.
-		 * @param array  $old_roles An array of the user's previous roles.
+		 * @param string[] $old_roles An array of the user's previous roles.
 		 */
 		do_action( 'set_user_role', $this->ID, $role, $old_roles );
 	}
 	/**
 	 *
 	 * @param string $cap Capability name.
 	 * @param bool $grant Whether to grant capability to user.
 	 */
 	public function add_cap( $cap, $grant = true ) {
-		$this->caps[$cap] = $grant;
+		$this->caps[ $cap ] = $grant;
 		update_user_meta( $this->ID, $this->cap_key, $this->caps );
 		$this->get_role_caps();
 		$this->update_user_level_from_caps();
 	}
 		$args = array_merge( array( $cap, $this->ID ), $args );
 		$caps = call_user_func_array( 'map_meta_cap', $args );
 		// Multisite super admin has all caps by definition, Unless specifically denied.
 		if ( is_multisite() && is_super_admin( $this->ID ) ) {
-			if ( in_array('do_not_allow', $caps) )
+			if ( in_array( 'do_not_allow', $caps ) ) {
 				return false;
+			}
 			return true;
 		}
 		/**
 		 * Dynamically filter a user's capabilities.
 		 *
 		 * @since 2.0.0
-		 * @since 3.7.0 Added the user object.
+		 * @since 3.7.0 Added the `$user` parameter.
 		 *
-		 * @param array   $allcaps An array of all the user's capabilities.
+		 * @param bool[]   $allcaps Array of key/value pairs where keys represent a capability name and boolean values
-		 * @param array   $caps    Actual capabilities for meta capability.
+		 *                          represent whether the user has that capability.
-		 * @param array   $args    Optional parameters passed to has_cap(), typically object ID.
+		 * @param string[] $caps    Required primitive capabilities for the requested capability.
-		 * @param WP_User $user    The user object.
+		 * @param array    $args {
+		 *     Arguments that accompany the requested capability check.
+		 *
+		 *     @type string    $0 Requested capability.
+		 *     @type int       $1 Concerned user ID.
+		 *     @type mixed  ...$2 Optional second and further parameters, typically object ID.
+		 * }
+		 * @param WP_User  $user    The user object.
 		 */
 		$capabilities = apply_filters( 'user_has_cap', $this->allcaps, $caps, $args, $this );
 		// Everyone is allowed to exist.
 		$capabilities['exist'] = true;
 		// Nobody is allowed to do things they are not allowed to do.
 		unset( $capabilities['do_not_allow'] );
 		// Must have ALL requested caps.
 		foreach ( (array) $caps as $cap ) {
-			if ( empty( $capabilities[ $cap ] ) )
+			if ( empty( $capabilities[ $cap ] ) ) {
 				return false;
+			}
 		}
 		return true;
 	}
 	/**
 	 * Set the site to operate on. Defaults to the current site.
 	 *
 	 * @since 3.0.0
 	 * @deprecated 4.9.0 Use WP_User::for_site()
-	 *
-	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
 	 * @param int $blog_id Optional. Site ID, defaults to current site.
 	 */
 	public function for_blog( $blog_id = '' ) {
 		_deprecated_function( __METHOD__, '4.9.0', 'WP_User::for_site()' );

changeset 9	177826044cd9
parent 7	cf61fcea0001
child 16	a86126ab1dd4