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