diff -r 3d4e9c994f10 -r a86126ab1dd4 wp/wp-includes/class-wp-user.php --- a/wp/wp-includes/class-wp-user.php Tue Oct 22 16:11:46 2019 +0200 +++ b/wp/wp-includes/class-wp-user.php Tue Dec 15 13:49:49 2020 +0100 @@ -53,10 +53,11 @@ 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(); @@ -72,7 +73,7 @@ * The roles the user is part of. * * @since 2.0.0 - * @var array + * @var string[] */ public $roles = array(); @@ -80,8 +81,8 @@ * 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 - * represent whether the user has that capability. + * @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(); @@ -114,9 +115,9 @@ * * @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 string $name Optional. User's username - * @param int $site_id Optional Site ID, defaults to current site. + * @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 ) ) { @@ -160,7 +161,7 @@ /** * 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. @@ -180,7 +181,7 @@ * * @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 */ @@ -192,7 +193,7 @@ $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 ) ) { @@ -233,17 +234,19 @@ } 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; } @@ -261,7 +264,7 @@ * @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', @@ -294,7 +297,7 @@ * @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', @@ -335,7 +338,7 @@ * @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', @@ -360,7 +363,7 @@ * @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', @@ -436,13 +439,13 @@ * * @since 4.3.0 * - * @param string $name Method to call. - * @param array $arguments Arguments to pass when calling. + * @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 ) { - return call_user_func_array( array( $this, $name ), $arguments ); + return $this->_init_caps( ...$arguments ); } return false; } @@ -479,19 +482,21 @@ } /** - * 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 + * their role might have, but the user is specifically denied. * * @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 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 ); @@ -557,7 +562,7 @@ * @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 ] ); @@ -588,7 +593,7 @@ * @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; } @@ -634,7 +639,7 @@ * * @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. */ @@ -669,8 +674,8 @@ * * @since 2.0.0 * - * @param string $cap Capability name. - * @param bool $grant Whether to grant capability to user. + * @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; @@ -712,49 +717,59 @@ } /** - * 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 int $object_id,... Optional. ID of a specific object to check against if `$cap` is a "meta" capability. - * Meta capabilities such as `edit_post` and `edit_user` are capabilities used by - * 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 + * @param string $cap Capability name. + * @param mixed ...$args Optional further parameters, typically starting with an object ID. + * @return bool Whether the user has the given capability, or, if an 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 ); - $args = array_merge( array( $cap, $this->ID ), $args ); - $caps = call_user_func_array( 'map_meta_cap', $args ); + $caps = map_meta_cap( $cap, $this->ID, ...$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 - * represent whether the user has that capability. + * @param bool[] $allcaps Array of key/value pairs where keys represent a capability name + * 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. @@ -852,7 +867,8 @@ * * @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 );