class-wp-user.php 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908
  1. <?php
  2. /**
  3. * User API: WP_User class
  4. *
  5. * @package WordPress
  6. * @subpackage Users
  7. * @since 4.4.0
  8. */
  9. /**
  10. * Core class used to implement the WP_User object.
  11. *
  12. * @since 2.0.0
  13. *
  14. * @property string $nickname
  15. * @property string $description
  16. * @property string $user_description
  17. * @property string $first_name
  18. * @property string $user_firstname
  19. * @property string $last_name
  20. * @property string $user_lastname
  21. * @property string $user_login
  22. * @property string $user_pass
  23. * @property string $user_nicename
  24. * @property string $user_email
  25. * @property string $user_url
  26. * @property string $user_registered
  27. * @property string $user_activation_key
  28. * @property string $user_status
  29. * @property int $user_level
  30. * @property string $display_name
  31. * @property string $spam
  32. * @property string $deleted
  33. * @property string $locale
  34. * @property string $rich_editing
  35. * @property string $syntax_highlighting
  36. * @property string $use_ssl
  37. */
  38. #[AllowDynamicProperties]
  39. class WP_User {
  40. /**
  41. * User data container.
  42. *
  43. * @since 2.0.0
  44. * @var stdClass
  45. */
  46. public $data;
  47. /**
  48. * The user's ID.
  49. *
  50. * @since 2.1.0
  51. * @var int
  52. */
  53. public $ID = 0;
  54. /**
  55. * Capabilities that the individual user has been granted outside of those inherited from their role.
  56. *
  57. * @since 2.0.0
  58. * @var bool[] Array of key/value pairs where keys represent a capability name
  59. * and boolean values represent whether the user has that capability.
  60. */
  61. public $caps = array();
  62. /**
  63. * User metadata option name.
  64. *
  65. * @since 2.0.0
  66. * @var string
  67. */
  68. public $cap_key;
  69. /**
  70. * The roles the user is part of.
  71. *
  72. * @since 2.0.0
  73. * @var string[]
  74. */
  75. public $roles = array();
  76. /**
  77. * All capabilities the user has, including individual and role based.
  78. *
  79. * @since 2.0.0
  80. * @var bool[] Array of key/value pairs where keys represent a capability name
  81. * and boolean values represent whether the user has that capability.
  82. */
  83. public $allcaps = array();
  84. /**
  85. * The filter context applied to user data fields.
  86. *
  87. * @since 2.9.0
  88. * @var string
  89. */
  90. public $filter = null;
  91. /**
  92. * The site ID the capabilities of this user are initialized for.
  93. *
  94. * @since 4.9.0
  95. * @var int
  96. */
  97. private $site_id = 0;
  98. /**
  99. * @since 3.3.0
  100. * @var array
  101. */
  102. private static $back_compat_keys;
  103. /**
  104. * Constructor.
  105. *
  106. * Retrieves the userdata and passes it to WP_User::init().
  107. *
  108. * @since 2.0.0
  109. *
  110. * @param int|string|stdClass|WP_User $id User's ID, a WP_User object, or a user object from the DB.
  111. * @param string $name Optional. User's username
  112. * @param int $site_id Optional Site ID, defaults to current site.
  113. */
  114. public function __construct( $id = 0, $name = '', $site_id = '' ) {
  115. if ( ! isset( self::$back_compat_keys ) ) {
  116. $prefix = $GLOBALS['wpdb']->prefix;
  117. self::$back_compat_keys = array(
  118. 'user_firstname' => 'first_name',
  119. 'user_lastname' => 'last_name',
  120. 'user_description' => 'description',
  121. 'user_level' => $prefix . 'user_level',
  122. $prefix . 'usersettings' => $prefix . 'user-settings',
  123. $prefix . 'usersettingstime' => $prefix . 'user-settings-time',
  124. );
  125. }
  126. if ( $id instanceof WP_User ) {
  127. $this->init( $id->data, $site_id );
  128. return;
  129. } elseif ( is_object( $id ) ) {
  130. $this->init( $id, $site_id );
  131. return;
  132. }
  133. if ( ! empty( $id ) && ! is_numeric( $id ) ) {
  134. $name = $id;
  135. $id = 0;
  136. }
  137. if ( $id ) {
  138. $data = self::get_data_by( 'id', $id );
  139. } else {
  140. $data = self::get_data_by( 'login', $name );
  141. }
  142. if ( $data ) {
  143. $this->init( $data, $site_id );
  144. } else {
  145. $this->data = new stdClass;
  146. }
  147. }
  148. /**
  149. * Sets up object properties, including capabilities.
  150. *
  151. * @since 3.3.0
  152. *
  153. * @param object $data User DB row object.
  154. * @param int $site_id Optional. The site ID to initialize for.
  155. */
  156. public function init( $data, $site_id = '' ) {
  157. if ( ! isset( $data->ID ) ) {
  158. $data->ID = 0;
  159. }
  160. $this->data = $data;
  161. $this->ID = (int) $data->ID;
  162. $this->for_site( $site_id );
  163. }
  164. /**
  165. * Returns only the main user fields.
  166. *
  167. * @since 3.3.0
  168. * @since 4.4.0 Added 'ID' as an alias of 'id' for the `$field` parameter.
  169. *
  170. * @global wpdb $wpdb WordPress database abstraction object.
  171. *
  172. * @param string $field The field to query against: 'id', 'ID', 'slug', 'email' or 'login'.
  173. * @param string|int $value The field value.
  174. * @return object|false Raw user object.
  175. */
  176. public static function get_data_by( $field, $value ) {
  177. global $wpdb;
  178. // 'ID' is an alias of 'id'.
  179. if ( 'ID' === $field ) {
  180. $field = 'id';
  181. }
  182. if ( 'id' === $field ) {
  183. // Make sure the value is numeric to avoid casting objects, for example,
  184. // to int 1.
  185. if ( ! is_numeric( $value ) ) {
  186. return false;
  187. }
  188. $value = (int) $value;
  189. if ( $value < 1 ) {
  190. return false;
  191. }
  192. } else {
  193. $value = trim( $value );
  194. }
  195. if ( ! $value ) {
  196. return false;
  197. }
  198. switch ( $field ) {
  199. case 'id':
  200. $user_id = $value;
  201. $db_field = 'ID';
  202. break;
  203. case 'slug':
  204. $user_id = wp_cache_get( $value, 'userslugs' );
  205. $db_field = 'user_nicename';
  206. break;
  207. case 'email':
  208. $user_id = wp_cache_get( $value, 'useremail' );
  209. $db_field = 'user_email';
  210. break;
  211. case 'login':
  212. $value = sanitize_user( $value );
  213. $user_id = wp_cache_get( $value, 'userlogins' );
  214. $db_field = 'user_login';
  215. break;
  216. default:
  217. return false;
  218. }
  219. if ( false !== $user_id ) {
  220. $user = wp_cache_get( $user_id, 'users' );
  221. if ( $user ) {
  222. return $user;
  223. }
  224. }
  225. $user = $wpdb->get_row(
  226. $wpdb->prepare(
  227. "SELECT * FROM $wpdb->users WHERE $db_field = %s LIMIT 1",
  228. $value
  229. )
  230. );
  231. if ( ! $user ) {
  232. return false;
  233. }
  234. update_user_caches( $user );
  235. return $user;
  236. }
  237. /**
  238. * Magic method for checking the existence of a certain custom field.
  239. *
  240. * @since 3.3.0
  241. *
  242. * @param string $key User meta key to check if set.
  243. * @return bool Whether the given user meta key is set.
  244. */
  245. public function __isset( $key ) {
  246. if ( 'id' === $key ) {
  247. _deprecated_argument(
  248. 'WP_User->id',
  249. '2.1.0',
  250. sprintf(
  251. /* translators: %s: WP_User->ID */
  252. __( 'Use %s instead.' ),
  253. '<code>WP_User->ID</code>'
  254. )
  255. );
  256. $key = 'ID';
  257. }
  258. if ( isset( $this->data->$key ) ) {
  259. return true;
  260. }
  261. if ( isset( self::$back_compat_keys[ $key ] ) ) {
  262. $key = self::$back_compat_keys[ $key ];
  263. }
  264. return metadata_exists( 'user', $this->ID, $key );
  265. }
  266. /**
  267. * Magic method for accessing custom fields.
  268. *
  269. * @since 3.3.0
  270. *
  271. * @param string $key User meta key to retrieve.
  272. * @return mixed Value of the given user meta key (if set). If `$key` is 'id', the user ID.
  273. */
  274. public function __get( $key ) {
  275. if ( 'id' === $key ) {
  276. _deprecated_argument(
  277. 'WP_User->id',
  278. '2.1.0',
  279. sprintf(
  280. /* translators: %s: WP_User->ID */
  281. __( 'Use %s instead.' ),
  282. '<code>WP_User->ID</code>'
  283. )
  284. );
  285. return $this->ID;
  286. }
  287. if ( isset( $this->data->$key ) ) {
  288. $value = $this->data->$key;
  289. } else {
  290. if ( isset( self::$back_compat_keys[ $key ] ) ) {
  291. $key = self::$back_compat_keys[ $key ];
  292. }
  293. $value = get_user_meta( $this->ID, $key, true );
  294. }
  295. if ( $this->filter ) {
  296. $value = sanitize_user_field( $key, $value, $this->ID, $this->filter );
  297. }
  298. return $value;
  299. }
  300. /**
  301. * Magic method for setting custom user fields.
  302. *
  303. * This method does not update custom fields in the database. It only stores
  304. * the value on the WP_User instance.
  305. *
  306. * @since 3.3.0
  307. *
  308. * @param string $key User meta key.
  309. * @param mixed $value User meta value.
  310. */
  311. public function __set( $key, $value ) {
  312. if ( 'id' === $key ) {
  313. _deprecated_argument(
  314. 'WP_User->id',
  315. '2.1.0',
  316. sprintf(
  317. /* translators: %s: WP_User->ID */
  318. __( 'Use %s instead.' ),
  319. '<code>WP_User->ID</code>'
  320. )
  321. );
  322. $this->ID = $value;
  323. return;
  324. }
  325. $this->data->$key = $value;
  326. }
  327. /**
  328. * Magic method for unsetting a certain custom field.
  329. *
  330. * @since 4.4.0
  331. *
  332. * @param string $key User meta key to unset.
  333. */
  334. public function __unset( $key ) {
  335. if ( 'id' === $key ) {
  336. _deprecated_argument(
  337. 'WP_User->id',
  338. '2.1.0',
  339. sprintf(
  340. /* translators: %s: WP_User->ID */
  341. __( 'Use %s instead.' ),
  342. '<code>WP_User->ID</code>'
  343. )
  344. );
  345. }
  346. if ( isset( $this->data->$key ) ) {
  347. unset( $this->data->$key );
  348. }
  349. if ( isset( self::$back_compat_keys[ $key ] ) ) {
  350. unset( self::$back_compat_keys[ $key ] );
  351. }
  352. }
  353. /**
  354. * Determines whether the user exists in the database.
  355. *
  356. * @since 3.4.0
  357. *
  358. * @return bool True if user exists in the database, false if not.
  359. */
  360. public function exists() {
  361. return ! empty( $this->ID );
  362. }
  363. /**
  364. * Retrieves the value of a property or meta key.
  365. *
  366. * Retrieves from the users and usermeta table.
  367. *
  368. * @since 3.3.0
  369. *
  370. * @param string $key Property
  371. * @return mixed
  372. */
  373. public function get( $key ) {
  374. return $this->__get( $key );
  375. }
  376. /**
  377. * Determines whether a property or meta key is set.
  378. *
  379. * Consults the users and usermeta tables.
  380. *
  381. * @since 3.3.0
  382. *
  383. * @param string $key Property.
  384. * @return bool
  385. */
  386. public function has_prop( $key ) {
  387. return $this->__isset( $key );
  388. }
  389. /**
  390. * Returns an array representation.
  391. *
  392. * @since 3.5.0
  393. *
  394. * @return array Array representation.
  395. */
  396. public function to_array() {
  397. return get_object_vars( $this->data );
  398. }
  399. /**
  400. * Makes private/protected methods readable for backward compatibility.
  401. *
  402. * @since 4.3.0
  403. *
  404. * @param string $name Method to call.
  405. * @param array $arguments Arguments to pass when calling.
  406. * @return mixed|false Return value of the callback, false otherwise.
  407. */
  408. public function __call( $name, $arguments ) {
  409. if ( '_init_caps' === $name ) {
  410. return $this->_init_caps( ...$arguments );
  411. }
  412. return false;
  413. }
  414. /**
  415. * Sets up capability object properties.
  416. *
  417. * Will set the value for the 'cap_key' property to current database table
  418. * prefix, followed by 'capabilities'. Will then check to see if the
  419. * property matching the 'cap_key' exists and is an array. If so, it will be
  420. * used.
  421. *
  422. * @since 2.1.0
  423. * @deprecated 4.9.0 Use WP_User::for_site()
  424. *
  425. * @global wpdb $wpdb WordPress database abstraction object.
  426. *
  427. * @param string $cap_key Optional capability key
  428. */
  429. protected function _init_caps( $cap_key = '' ) {
  430. global $wpdb;
  431. _deprecated_function( __METHOD__, '4.9.0', 'WP_User::for_site()' );
  432. if ( empty( $cap_key ) ) {
  433. $this->cap_key = $wpdb->get_blog_prefix( $this->site_id ) . 'capabilities';
  434. } else {
  435. $this->cap_key = $cap_key;
  436. }
  437. $this->caps = $this->get_caps_data();
  438. $this->get_role_caps();
  439. }
  440. /**
  441. * Retrieves all of the capabilities of the user's roles, and merges them with
  442. * individual user capabilities.
  443. *
  444. * All of the capabilities of the user's roles are merged with the user's individual
  445. * capabilities. This means that the user can be denied specific capabilities that
  446. * their role might have, but the user is specifically denied.
  447. *
  448. * @since 2.0.0
  449. *
  450. * @return bool[] Array of key/value pairs where keys represent a capability name
  451. * and boolean values represent whether the user has that capability.
  452. */
  453. public function get_role_caps() {
  454. $switch_site = false;
  455. if ( is_multisite() && get_current_blog_id() != $this->site_id ) {
  456. $switch_site = true;
  457. switch_to_blog( $this->site_id );
  458. }
  459. $wp_roles = wp_roles();
  460. // Filter out caps that are not role names and assign to $this->roles.
  461. if ( is_array( $this->caps ) ) {
  462. $this->roles = array_filter( array_keys( $this->caps ), array( $wp_roles, 'is_role' ) );
  463. }
  464. // Build $allcaps from role caps, overlay user's $caps.
  465. $this->allcaps = array();
  466. foreach ( (array) $this->roles as $role ) {
  467. $the_role = $wp_roles->get_role( $role );
  468. $this->allcaps = array_merge( (array) $this->allcaps, (array) $the_role->capabilities );
  469. }
  470. $this->allcaps = array_merge( (array) $this->allcaps, (array) $this->caps );
  471. if ( $switch_site ) {
  472. restore_current_blog();
  473. }
  474. return $this->allcaps;
  475. }
  476. /**
  477. * Adds role to user.
  478. *
  479. * Updates the user's meta data option with capabilities and roles.
  480. *
  481. * @since 2.0.0
  482. *
  483. * @param string $role Role name.
  484. */
  485. public function add_role( $role ) {
  486. if ( empty( $role ) ) {
  487. return;
  488. }
  489. if ( in_array( $role, $this->roles, true ) ) {
  490. return;
  491. }
  492. $this->caps[ $role ] = true;
  493. update_user_meta( $this->ID, $this->cap_key, $this->caps );
  494. $this->get_role_caps();
  495. $this->update_user_level_from_caps();
  496. /**
  497. * Fires immediately after the user has been given a new role.
  498. *
  499. * @since 4.3.0
  500. *
  501. * @param int $user_id The user ID.
  502. * @param string $role The new role.
  503. */
  504. do_action( 'add_user_role', $this->ID, $role );
  505. }
  506. /**
  507. * Removes role from user.
  508. *
  509. * @since 2.0.0
  510. *
  511. * @param string $role Role name.
  512. */
  513. public function remove_role( $role ) {
  514. if ( ! in_array( $role, $this->roles, true ) ) {
  515. return;
  516. }
  517. unset( $this->caps[ $role ] );
  518. update_user_meta( $this->ID, $this->cap_key, $this->caps );
  519. $this->get_role_caps();
  520. $this->update_user_level_from_caps();
  521. /**
  522. * Fires immediately after a role as been removed from a user.
  523. *
  524. * @since 4.3.0
  525. *
  526. * @param int $user_id The user ID.
  527. * @param string $role The removed role.
  528. */
  529. do_action( 'remove_user_role', $this->ID, $role );
  530. }
  531. /**
  532. * Sets the role of the user.
  533. *
  534. * This will remove the previous roles of the user and assign the user the
  535. * new one. You can set the role to an empty string and it will remove all
  536. * of the roles from the user.
  537. *
  538. * @since 2.0.0
  539. *
  540. * @param string $role Role name.
  541. */
  542. public function set_role( $role ) {
  543. if ( 1 === count( $this->roles ) && current( $this->roles ) == $role ) {
  544. return;
  545. }
  546. foreach ( (array) $this->roles as $oldrole ) {
  547. unset( $this->caps[ $oldrole ] );
  548. }
  549. $old_roles = $this->roles;
  550. if ( ! empty( $role ) ) {
  551. $this->caps[ $role ] = true;
  552. $this->roles = array( $role => true );
  553. } else {
  554. $this->roles = array();
  555. }
  556. update_user_meta( $this->ID, $this->cap_key, $this->caps );
  557. $this->get_role_caps();
  558. $this->update_user_level_from_caps();
  559. foreach ( $old_roles as $old_role ) {
  560. if ( ! $old_role || $old_role === $role ) {
  561. continue;
  562. }
  563. /** This action is documented in wp-includes/class-wp-user.php */
  564. do_action( 'remove_user_role', $this->ID, $old_role );
  565. }
  566. if ( $role && ! in_array( $role, $old_roles, true ) ) {
  567. /** This action is documented in wp-includes/class-wp-user.php */
  568. do_action( 'add_user_role', $this->ID, $role );
  569. }
  570. /**
  571. * Fires after the user's role has changed.
  572. *
  573. * @since 2.9.0
  574. * @since 3.6.0 Added $old_roles to include an array of the user's previous roles.
  575. *
  576. * @param int $user_id The user ID.
  577. * @param string $role The new role.
  578. * @param string[] $old_roles An array of the user's previous roles.
  579. */
  580. do_action( 'set_user_role', $this->ID, $role, $old_roles );
  581. }
  582. /**
  583. * Chooses the maximum level the user has.
  584. *
  585. * Will compare the level from the $item parameter against the $max
  586. * parameter. If the item is incorrect, then just the $max parameter value
  587. * will be returned.
  588. *
  589. * Used to get the max level based on the capabilities the user has. This
  590. * is also based on roles, so if the user is assigned the Administrator role
  591. * then the capability 'level_10' will exist and the user will get that
  592. * value.
  593. *
  594. * @since 2.0.0
  595. *
  596. * @param int $max Max level of user.
  597. * @param string $item Level capability name.
  598. * @return int Max Level.
  599. */
  600. public function level_reduction( $max, $item ) {
  601. if ( preg_match( '/^level_(10|[0-9])$/i', $item, $matches ) ) {
  602. $level = (int) $matches[1];
  603. return max( $max, $level );
  604. } else {
  605. return $max;
  606. }
  607. }
  608. /**
  609. * Updates the maximum user level for the user.
  610. *
  611. * Updates the 'user_level' user metadata (includes prefix that is the
  612. * database table prefix) with the maximum user level. Gets the value from
  613. * the all of the capabilities that the user has.
  614. *
  615. * @since 2.0.0
  616. *
  617. * @global wpdb $wpdb WordPress database abstraction object.
  618. */
  619. public function update_user_level_from_caps() {
  620. global $wpdb;
  621. $this->user_level = array_reduce( array_keys( $this->allcaps ), array( $this, 'level_reduction' ), 0 );
  622. update_user_meta( $this->ID, $wpdb->get_blog_prefix() . 'user_level', $this->user_level );
  623. }
  624. /**
  625. * Adds capability and grant or deny access to capability.
  626. *
  627. * @since 2.0.0
  628. *
  629. * @param string $cap Capability name.
  630. * @param bool $grant Whether to grant capability to user.
  631. */
  632. public function add_cap( $cap, $grant = true ) {
  633. $this->caps[ $cap ] = $grant;
  634. update_user_meta( $this->ID, $this->cap_key, $this->caps );
  635. $this->get_role_caps();
  636. $this->update_user_level_from_caps();
  637. }
  638. /**
  639. * Removes capability from user.
  640. *
  641. * @since 2.0.0
  642. *
  643. * @param string $cap Capability name.
  644. */
  645. public function remove_cap( $cap ) {
  646. if ( ! isset( $this->caps[ $cap ] ) ) {
  647. return;
  648. }
  649. unset( $this->caps[ $cap ] );
  650. update_user_meta( $this->ID, $this->cap_key, $this->caps );
  651. $this->get_role_caps();
  652. $this->update_user_level_from_caps();
  653. }
  654. /**
  655. * Removes all of the capabilities of the user.
  656. *
  657. * @since 2.1.0
  658. *
  659. * @global wpdb $wpdb WordPress database abstraction object.
  660. */
  661. public function remove_all_caps() {
  662. global $wpdb;
  663. $this->caps = array();
  664. delete_user_meta( $this->ID, $this->cap_key );
  665. delete_user_meta( $this->ID, $wpdb->get_blog_prefix() . 'user_level' );
  666. $this->get_role_caps();
  667. }
  668. /**
  669. * Returns whether the user has the specified capability.
  670. *
  671. * This function also accepts an ID of an object to check against if the capability is a meta capability. Meta
  672. * capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to
  673. * map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`.
  674. *
  675. * Example usage:
  676. *
  677. * $user->has_cap( 'edit_posts' );
  678. * $user->has_cap( 'edit_post', $post->ID );
  679. * $user->has_cap( 'edit_post_meta', $post->ID, $meta_key );
  680. *
  681. * While checking against a role in place of a capability is supported in part, this practice is discouraged as it
  682. * may produce unreliable results.
  683. *
  684. * @since 2.0.0
  685. * @since 5.3.0 Formalized the existing and already documented `...$args` parameter
  686. * by adding it to the function signature.
  687. *
  688. * @see map_meta_cap()
  689. *
  690. * @param string $cap Capability name.
  691. * @param mixed ...$args Optional further parameters, typically starting with an object ID.
  692. * @return bool Whether the user has the given capability, or, if an object ID is passed, whether the user has
  693. * the given capability for that object.
  694. */
  695. public function has_cap( $cap, ...$args ) {
  696. if ( is_numeric( $cap ) ) {
  697. _deprecated_argument( __FUNCTION__, '2.0.0', __( 'Usage of user levels is deprecated. Use capabilities instead.' ) );
  698. $cap = $this->translate_level_to_cap( $cap );
  699. }
  700. $caps = map_meta_cap( $cap, $this->ID, ...$args );
  701. // Multisite super admin has all caps by definition, Unless specifically denied.
  702. if ( is_multisite() && is_super_admin( $this->ID ) ) {
  703. if ( in_array( 'do_not_allow', $caps, true ) ) {
  704. return false;
  705. }
  706. return true;
  707. }
  708. // Maintain BC for the argument passed to the "user_has_cap" filter.
  709. $args = array_merge( array( $cap, $this->ID ), $args );
  710. /**
  711. * Dynamically filter a user's capabilities.
  712. *
  713. * @since 2.0.0
  714. * @since 3.7.0 Added the `$user` parameter.
  715. *
  716. * @param bool[] $allcaps Array of key/value pairs where keys represent a capability name
  717. * and boolean values represent whether the user has that capability.
  718. * @param string[] $caps Required primitive capabilities for the requested capability.
  719. * @param array $args {
  720. * Arguments that accompany the requested capability check.
  721. *
  722. * @type string $0 Requested capability.
  723. * @type int $1 Concerned user ID.
  724. * @type mixed ...$2 Optional second and further parameters, typically object ID.
  725. * }
  726. * @param WP_User $user The user object.
  727. */
  728. $capabilities = apply_filters( 'user_has_cap', $this->allcaps, $caps, $args, $this );
  729. // Everyone is allowed to exist.
  730. $capabilities['exist'] = true;
  731. // Nobody is allowed to do things they are not allowed to do.
  732. unset( $capabilities['do_not_allow'] );
  733. // Must have ALL requested caps.
  734. foreach ( (array) $caps as $cap ) {
  735. if ( empty( $capabilities[ $cap ] ) ) {
  736. return false;
  737. }
  738. }
  739. return true;
  740. }
  741. /**
  742. * Converts numeric level to level capability name.
  743. *
  744. * Prepends 'level_' to level number.
  745. *
  746. * @since 2.0.0
  747. *
  748. * @param int $level Level number, 1 to 10.
  749. * @return string
  750. */
  751. public function translate_level_to_cap( $level ) {
  752. return 'level_' . $level;
  753. }
  754. /**
  755. * Sets the site to operate on. Defaults to the current site.
  756. *
  757. * @since 3.0.0
  758. * @deprecated 4.9.0 Use WP_User::for_site()
  759. *
  760. * @param int $blog_id Optional. Site ID, defaults to current site.
  761. */
  762. public function for_blog( $blog_id = '' ) {
  763. _deprecated_function( __METHOD__, '4.9.0', 'WP_User::for_site()' );
  764. $this->for_site( $blog_id );
  765. }
  766. /**
  767. * Sets the site to operate on. Defaults to the current site.
  768. *
  769. * @since 4.9.0
  770. *
  771. * @global wpdb $wpdb WordPress database abstraction object.
  772. *
  773. * @param int $site_id Site ID to initialize user capabilities for. Default is the current site.
  774. */
  775. public function for_site( $site_id = '' ) {
  776. global $wpdb;
  777. if ( ! empty( $site_id ) ) {
  778. $this->site_id = absint( $site_id );
  779. } else {
  780. $this->site_id = get_current_blog_id();
  781. }
  782. $this->cap_key = $wpdb->get_blog_prefix( $this->site_id ) . 'capabilities';
  783. $this->caps = $this->get_caps_data();
  784. $this->get_role_caps();
  785. }
  786. /**
  787. * Gets the ID of the site for which the user's capabilities are currently initialized.
  788. *
  789. * @since 4.9.0
  790. *
  791. * @return int Site ID.
  792. */
  793. public function get_site_id() {
  794. return $this->site_id;
  795. }
  796. /**
  797. * Gets the available user capabilities data.
  798. *
  799. * @since 4.9.0
  800. *
  801. * @return bool[] List of capabilities keyed by the capability name,
  802. * e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
  803. */
  804. private function get_caps_data() {
  805. $caps = get_user_meta( $this->ID, $this->cap_key, true );
  806. if ( ! is_array( $caps ) ) {
  807. return array();
  808. }
  809. return $caps;
  810. }
  811. }