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

equal deleted inserted replaced

-:3d4e9c994f10
+:a86126ab1dd4
 	 * @var int
 	 */
 	public $ID = 0;
 	/**
-	 * The individual capabilities the user has been given.
+	 * Capabilities that the individual user has been granted outside of those inherited from their role.
 	 *
 	 * @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 $caps = array();
 	/**
 	 * User metadata option name.
 	/**
 	 * The roles the user is part of.
 	 *
 	 * @since 2.0.0
-	 * @var array
+	 * @var string[]
 	 */
 	public $roles = array();
 	/**
 	 * All capabilities the user has, including individual and role based.
 	 *
 	 * @since 2.0.0
-	 * @var bool[] Array of key/value pairs where keys represent a capability name and boolean values
+	 * @var bool[] Array of key/value pairs where keys represent a capability name
-	 *             represent whether the user has that capability.
+	 *             and boolean values represent whether the user has that capability.
 	 */
 	public $allcaps = array();
 	/**
 	 * The filter context applied to user data fields.
 	 *
 	 * Retrieves the userdata and passes it to WP_User::init().
 	 *
 	 * @since 2.0.0
 	 *
-	 * @param int|string|stdClass|WP_User $id User's ID, a WP_User object, or a user object from the DB.
+	 * @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 string                      $name    Optional. User's username
-	 * @param int $site_id Optional Site ID, defaults to current site.
+	 * @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;
 			self::$back_compat_keys = array(
 	}
 	/**
 	 * Sets up object properties, including capabilities.
 	 *
-	 * @since  3.3.0
+	 * @since 3.3.0
 	 *
 	 * @param object $data    User DB row object.
 	 * @param int    $site_id Optional. The site ID to initialize for.
 	 */
 	public function init( $data, $site_id = '' ) {
 	 * @since 3.3.0
 	 * @since 4.4.0 Added 'ID' as an alias of 'id' for the `$field` parameter.
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @param string $field The field to query against: 'id', 'ID', 'slug', 'email' or 'login'.
+	 * @param string     $field The field to query against: 'id', 'ID', 'slug', 'email' or 'login'.
 	 * @param string|int $value The field value
 	 * @return object|false Raw user object
 	 */
 	public static function get_data_by( $field, $value ) {
 		global $wpdb;
 		// 'ID' is an alias of 'id'.
 		if ( 'ID' === $field ) {
 			$field = 'id';
 		}
-		if ( 'id' == $field ) {
+		if ( 'id' === $field ) {
 			// Make sure the value is numeric to avoid casting objects, for example,
 			// to int 1.
 			if ( ! is_numeric( $value ) ) {
 				return false;
 			}
 			default:
 				return false;
 		}
 		if ( false !== $user_id ) {
-			if ( $user = wp_cache_get( $user_id, 'users' ) ) {
+			$user = wp_cache_get( $user_id, 'users' );
+			if ( $user ) {
 				return $user;
 			}
 		}
-		if ( ! $user = $wpdb->get_row(
+		$user = $wpdb->get_row(
 			$wpdb->prepare(
 				"SELECT * FROM $wpdb->users WHERE $db_field = %s LIMIT 1",
 				$value
 			)
-		) ) {
+		);
+		if ( ! $user ) {
 			return false;
 		}
 		update_user_caches( $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 ) {
+		if ( 'id' === $key ) {
 			_deprecated_argument(
 				'WP_User->id',
 				'2.1.0',
 				sprintf(
 					/* translators: %s: WP_User->ID */
 	 *
 	 * @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 ) {
+		if ( 'id' === $key ) {
 			_deprecated_argument(
 				'WP_User->id',
 				'2.1.0',
 				sprintf(
 					/* translators: %s: WP_User->ID */
 	 *
 	 * @param string $key   User meta key.
 	 * @param mixed  $value User meta value.
 	 */
 	public function __set( $key, $value ) {
-		if ( 'id' == $key ) {
+		if ( 'id' === $key ) {
 			_deprecated_argument(
 				'WP_User->id',
 				'2.1.0',
 				sprintf(
 					/* translators: %s: WP_User->ID */
 	 * @since 4.4.0
 	 *
 	 * @param string $key User meta key to unset.
 	 */
 	public function __unset( $key ) {
-		if ( 'id' == $key ) {
+		if ( 'id' === $key ) {
 			_deprecated_argument(
 				'WP_User->id',
 				'2.1.0',
 				sprintf(
 					/* translators: %s: WP_User->ID */
 	/**
 	 * Makes private/protected methods readable for backward compatibility.
 	 *
 	 * @since 4.3.0
 	 *
-	 * @param string   $name      Method to call.
+	 * @param string $name      Method to call.
-	 * @param array    $arguments Arguments to pass when calling.
+	 * @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 ) {
-			return call_user_func_array( array( $this, $name ), $arguments );
+			return $this->_init_caps( ...$arguments );
 		}
 		return false;
 	}
 	/**
 		$this->get_role_caps();
 	}
 	/**
-	 * Retrieves all of the capabilities of the roles of the user, and merges them with individual user capabilities.
+	 * Retrieves all of the capabilities of the user's roles, and merges them with
-	 *
+	 * individual user capabilities.
-	 * All of the capabilities of the roles of the user are merged with the user's individual capabilities. This means
+	 *
-	 * that the user can be denied specific capabilities that their role might have, but the user is specifically denied.
+	 * All of the capabilities of the user's roles are merged with the user's individual
-	 *
+	 * capabilities. This means that the user can be denied specific capabilities that
-	 * @since 2.0.0
+	 * their role might have, but the user is specifically denied.
 	 *
-	 * @return bool[] Array of key/value pairs where keys represent a capability name and boolean values
+	 * @since 2.0.0
-	 *                represent whether the user has that capability.
+	 *
+	 * @return bool[] Array of key/value pairs where keys represent a capability name
+	 *                and boolean values represent whether the user has that capability.
 	 */
 	public function get_role_caps() {
 		$switch_site = false;
-		if ( is_multisite() && $this->site_id != get_current_blog_id() ) {
+		if ( is_multisite() && get_current_blog_id() != $this->site_id ) {
 			$switch_site = true;
 			switch_to_blog( $this->site_id );
 		}
 	 * @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, true ) ) {
 			return;
 		}
 		unset( $this->caps[ $role ] );
 		update_user_meta( $this->ID, $this->cap_key, $this->caps );
 		$this->get_role_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 ) && current( $this->roles ) == $role ) {
 			return;
 		}
 		foreach ( (array) $this->roles as $oldrole ) {
 			unset( $this->caps[ $oldrole ] );
 	 * then the capability 'level_10' will exist and the user will get that
 	 * value.
 	 *
 	 * @since 2.0.0
 	 *
-	 * @param int $max Max level of user.
+	 * @param int    $max  Max level of user.
 	 * @param string $item Level capability name.
 	 * @return int Max Level.
 	 */
 	public function level_reduction( $max, $item ) {
 		if ( preg_match( '/^level_(10|[0-9])$/i', $item, $matches ) ) {
 	/**
 	 * Add capability and grant or deny access to capability.
 	 *
 	 * @since 2.0.0
 	 *
-	 * @param string $cap Capability name.
+	 * @param string $cap   Capability name.
-	 * @param bool $grant Whether to grant capability to user.
+	 * @param bool   $grant Whether to grant capability to user.
 	 */
 	public function add_cap( $cap, $grant = true ) {
 		$this->caps[ $cap ] = $grant;
 		update_user_meta( $this->ID, $this->cap_key, $this->caps );
 		$this->get_role_caps();
 		delete_user_meta( $this->ID, $wpdb->get_blog_prefix() . 'user_level' );
 		$this->get_role_caps();
 	}
 	/**
-	 * Whether the user has a specific capability.
+	 * Returns whether the user has the specified capability.
+	 *
+	 * This function also accepts an ID of an object to check against if the capability is a meta capability. Meta
+	 * capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to
+	 * map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`.
+	 *
+	 * Example usage:
+	 *
+	 *     $user->has_cap( 'edit_posts' );
+	 *     $user->has_cap( 'edit_post', $post->ID );
+	 *     $user->has_cap( 'edit_post_meta', $post->ID, $meta_key );
 	 *
 	 * While checking against a role in place of a capability is supported in part, this practice is discouraged as it
 	 * may produce unreliable results.
 	 *
 	 * @since 2.0.0
+	 * @since 5.3.0 Formalized the existing and already documented `...$args` parameter
+	 *              by adding it to the function signature.
 	 *
 	 * @see map_meta_cap()
 	 *
-	 * @param string $cap           Capability name.
+	 * @param string $cap     Capability name.
-	 * @param int    $object_id,... Optional. ID of a specific object to check against if `$cap` is a "meta" capability.
+	 * @param mixed  ...$args Optional further parameters, typically starting with an object ID.
-	 *                              Meta capabilities such as `edit_post` and `edit_user` are capabilities used by
+	 * @return bool Whether the user has the given capability, or, if an object ID is passed, whether the user has
-	 *                              by the `map_meta_cap()` function to map to primitive capabilities that a user or
-	 *                              role has, such as `edit_posts` and `edit_others_posts`.
-	 * @return bool Whether the user has the given capability, or, if `$object_id` is passed, whether the user has
 	 *              the given capability for that object.
 	 */
-	public function has_cap( $cap ) {
+	public function has_cap( $cap, ...$args ) {
 		if ( is_numeric( $cap ) ) {
 			_deprecated_argument( __FUNCTION__, '2.0.0', __( 'Usage of user levels is deprecated. Use capabilities instead.' ) );
 			$cap = $this->translate_level_to_cap( $cap );
 		}
-		$args = array_slice( func_get_args(), 1 );
+		$caps = map_meta_cap( $cap, $this->ID, ...$args );
-		$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, true ) ) {
 				return false;
 			}
 			return true;
 		}
+		// Maintain BC for the argument passed to the "user_has_cap" filter.
+		$args = array_merge( array( $cap, $this->ID ), $args );
 		/**
 		 * Dynamically filter a user's capabilities.
 		 *
 		 * @since 2.0.0
 		 * @since 3.7.0 Added the `$user` parameter.
 		 *
-		 * @param bool[]   $allcaps Array of key/value pairs where keys represent a capability name and boolean values
+		 * @param bool[]   $allcaps Array of key/value pairs where keys represent a capability name
-		 *                          represent whether the user has that capability.
+		 *                          and boolean values represent whether the user has that capability.
 		 * @param string[] $caps    Required primitive capabilities for the requested capability.
 		 * @param array    $args {
 		 *     Arguments that accompany the requested capability check.
 		 *
 		 *     @type string    $0 Requested capability.
 	/**
 	 * Gets the available user capabilities data.
 	 *
 	 * @since 4.9.0
 	 *
-	 * @return array User capabilities array.
+	 * @return bool[] List of capabilities keyed by the capability name,
+	 *                e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
 	 */
 	private function get_caps_data() {
 		$caps = get_user_meta( $this->ID, $this->cap_key, true );
 		if ( ! is_array( $caps ) ) {

changeset 16	a86126ab1dd4
parent 9	177826044cd9
child 18	be944660c56a