WordPress.org

Make WordPress Core

Ticket #5632: 5632.r8903.diff

File 5632.r8903.diff, 16.8 KB (added by jacobsantos, 6 years ago)

Complete inline documentation for capabilities.php based off of r8903

  • capabilities.php

     
    11<?php 
     2/** 
     3 * WordPress Roles and Capabilities. 
     4 * 
     5 * @package WordPress 
     6 * @subpackage User 
     7 */ 
    28 
     9/** 
     10 * WordPress User Roles. 
     11 * 
     12 * The role option is simple, the structure is organized by role name that store 
     13 * the name in value of the 'name' key. The capabilities are stored as an array 
     14 * in the value of the 'capability' key. 
     15 * 
     16 * <code> 
     17 * array ( 
     18 *              'rolename' => array ( 
     19 *                      'name' => 'rolename', 
     20 *                      'capabilities' => array() 
     21 *              ) 
     22 * ) 
     23 * </code> 
     24 * 
     25 * @since 2.0.0 
     26 * @package WordPress 
     27 * @subpackage User 
     28 */ 
    329class WP_Roles { 
     30        /** 
     31         * List of roles and capabilities. 
     32         * 
     33         * @since 2.0.0 
     34         * @access public 
     35         * @var array 
     36         */ 
    437        var $roles; 
    538 
     39        /** 
     40         * List of the role objects. 
     41         * 
     42         * @since 2.0.0 
     43         * @access public 
     44         * @var array 
     45         */ 
    646        var $role_objects = array(); 
     47 
     48        /** 
     49         * List of role names. 
     50         * 
     51         * @since 2.0.0 
     52         * @access public 
     53         * @var array 
     54         */ 
    755        var $role_names = array(); 
     56 
     57        /** 
     58         * Option name for storing role list. 
     59         * 
     60         * @since 2.0.0 
     61         * @access public 
     62         * @var string 
     63         */ 
    864        var $role_key; 
     65 
     66        /** 
     67         * Whether to use the database for retrieval and storage. 
     68         * 
     69         * @since 2.1.0 
     70         * @access public 
     71         * @var bool 
     72         */ 
    973        var $use_db = true; 
    1074 
     75        /** 
     76         * PHP4 Constructor - Call {@link WP_Roles::_init()} method. 
     77         * 
     78         * @since 2.0.0 
     79         * @access public 
     80         * 
     81         * @return WP_Roles 
     82         */ 
    1183        function WP_Roles() { 
    1284                $this->_init(); 
    1385        } 
    1486 
     87        /** 
     88         * Setup the object properties. 
     89         * 
     90         * The role key is set to the current prefix for the $wpdb object with 
     91         * 'user_roles' appended. If the $wp_user_roles global is set, then it will 
     92         * be used and the role option will not be updated or used. 
     93         * 
     94         * @since 2.1.0 
     95         * @access protected 
     96         * @uses $wpdb Used to get the database prefix. 
     97         * @global array $wp_user_roles Used to set the 'roles' property value. 
     98         */ 
    1599        function _init () { 
    16100                global $wpdb; 
    17101                global $wp_user_roles; 
     
    34118                } 
    35119        } 
    36120 
     121        /** 
     122         * Add role name with capabilities to list. 
     123         * 
     124         * Updates the list of roles, if the role doesn't already exist. 
     125         * 
     126         * @since 2.0.0 
     127         * @access public 
     128         * 
     129         * @param string $role Role name. 
     130         * @param string $display_name Role display name. 
     131         * @param array $capabilities List of role capabilities. 
     132         * @return null|WP_Role WP_Role object if role is added, null if already exists. 
     133         */ 
    37134        function add_role( $role, $display_name, $capabilities = array() ) { 
    38135                if ( isset( $this->roles[$role] ) ) 
    39136                        return; 
     
    49146                return $this->role_objects[$role]; 
    50147        } 
    51148 
     149        /** 
     150         * Remove role by name. 
     151         * 
     152         * @since 2.0.0 
     153         * @access public 
     154         * 
     155         * @param string $role Role name. 
     156         */ 
    52157        function remove_role( $role ) { 
    53158                if ( ! isset( $this->role_objects[$role] ) ) 
    54159                        return; 
     
    61166                        update_option( $this->role_key, $this->roles ); 
    62167        } 
    63168 
     169        /** 
     170         * Add capability to role. 
     171         * 
     172         * @since 2.0.0 
     173         * @access public 
     174         * 
     175         * @param string $role Role name. 
     176         * @param string $cap Capability name. 
     177         * @param bool $grant Optional, default is true. Whether role is capable of preforming capability. 
     178         */ 
    64179        function add_cap( $role, $cap, $grant = true ) { 
    65180                $this->roles[$role]['capabilities'][$cap] = $grant; 
    66181                if ( $this->use_db ) 
    67182                        update_option( $this->role_key, $this->roles ); 
    68183        } 
    69184 
     185        /** 
     186         * Remove capability from role. 
     187         * 
     188         * @since 2.0.0 
     189         * @access public 
     190         * 
     191         * @param string $role Role name. 
     192         * @param string $cap Capability name. 
     193         */ 
    70194        function remove_cap( $role, $cap ) { 
    71195                unset( $this->roles[$role]['capabilities'][$cap] ); 
    72196                if ( $this->use_db ) 
    73197                        update_option( $this->role_key, $this->roles ); 
    74198        } 
    75199 
     200        /** 
     201         * Retrieve role object by name. 
     202         * 
     203         * @since 2.0.0 
     204         * @access public 
     205         * 
     206         * @param string $role Role name. 
     207         * @return object|null Null, if role does not exist. WP_Role object, if found. 
     208         */ 
    76209        function &get_role( $role ) { 
    77210                if ( isset( $this->role_objects[$role] ) ) 
    78211                        return $this->role_objects[$role]; 
     
    80213                        return null; 
    81214        } 
    82215 
     216        /** 
     217         * Retrieve list of role names. 
     218         * 
     219         * @since 2.0.0 
     220         * @access public 
     221         * 
     222         * @return array List of role names. 
     223         */ 
    83224        function get_names() { 
    84225                return $this->role_names; 
    85226        } 
    86227 
     228        /** 
     229         * Whether role name is currently in the list of available roles. 
     230         * 
     231         * @since 2.0.0 
     232         * @access public 
     233         * 
     234         * @param string $role Role name to look up. 
     235         * @return bool 
     236         */ 
    87237        function is_role( $role ) 
    88238        { 
    89239                return isset( $this->role_names[$role] ); 
    90240        } 
    91241} 
    92242 
     243/** 
     244 * WordPress Role class. 
     245 * 
     246 * @since 2.0.0 
     247 * @package WordPress 
     248 * @subpackage User 
     249 */ 
    93250class WP_Role { 
     251        /** 
     252         * Role name. 
     253         * 
     254         * @since 2.0.0 
     255         * @access public 
     256         * @var string 
     257         */ 
    94258        var $name; 
     259 
     260        /** 
     261         * List of capabilities the role contains. 
     262         * 
     263         * @since 2.0.0 
     264         * @access public 
     265         * @var array 
     266         */ 
    95267        var $capabilities; 
    96268 
     269        /** 
     270         * PHP4 Constructor - Setup object properties. 
     271         * 
     272         * The list of capabilities, must have the key as the name of the capability 
     273         * and the value a boolean of whether it is granted to the role or not. 
     274         * 
     275         * @since 2.0.0 
     276         * @access public 
     277         * 
     278         * @param string $role Role name. 
     279         * @param array $capabilities List of capabilities. 
     280         * @return WP_Role 
     281         */ 
    97282        function WP_Role( $role, $capabilities ) { 
    98283                $this->name = $role; 
    99284                $this->capabilities = $capabilities; 
    100285        } 
    101286 
     287        /** 
     288         * Assign role a capability. 
     289         * 
     290         * @see WP_Roles::add_cap() Method uses implementation for role. 
     291         * @since 2.0.0 
     292         * @access public 
     293         * 
     294         * @param string $cap Capability name. 
     295         * @param bool $grant Whether role has capability privilege.  
     296         */ 
    102297        function add_cap( $cap, $grant = true ) { 
    103298                global $wp_roles; 
    104299 
     
    109304                $wp_roles->add_cap( $this->name, $cap, $grant ); 
    110305        } 
    111306 
     307        /** 
     308         * Remove capability from role. 
     309         * 
     310         * This is a container for {@link WP_Roles::remove_cap()} to remove the 
     311         * capability from the role. That is to say, that {@link 
     312         * WP_Roles::remove_cap()} implements the functionality, but it also makes 
     313         * sense to use this class, because you don't need to enter the role name. 
     314         * 
     315         * @since 2.0.0 
     316         * @access public 
     317         * 
     318         * @param string $cap Capability name. 
     319         */ 
    112320        function remove_cap( $cap ) { 
    113321                global $wp_roles; 
    114322 
     
    119327                $wp_roles->remove_cap( $this->name, $cap ); 
    120328        } 
    121329 
     330        /** 
     331         * Whether role has capability. 
     332         * 
     333         * The capabilities is passed through the 'role_has_cap' filter. The first 
     334         * parameter for the hook is the list of capabilities the class has 
     335         * assigned. The second parameter is the capability name to look for. The 
     336         * third and final parameter for the hook is the role name. 
     337         * 
     338         * @since 2.0.0 
     339         * @access public 
     340         * 
     341         * @param string $cap Capability name. 
     342         * @return bool True, if user has capability. False, if doesn't have capability. 
     343         */ 
    122344        function has_cap( $cap ) { 
    123345                $capabilities = apply_filters( 'role_has_cap', $this->capabilities, $cap, $this->name ); 
    124346                if ( !empty( $capabilities[$cap] ) ) 
     
    129351 
    130352} 
    131353 
     354/** 
     355 * WordPress User class. 
     356 * 
     357 * @since 2.0.0 
     358 * @package WordPress 
     359 * @subpackage User 
     360 */ 
    132361class WP_User { 
     362        /** 
     363         * User data container. 
     364         * 
     365         * This will be set as properties of the object. 
     366         * 
     367         * @since 2.0.0 
     368         * @access private 
     369         * @var array 
     370         */ 
    133371        var $data; 
     372 
     373        /** 
     374         * The user's ID. 
     375         * 
     376         * @since 2.1.0 
     377         * @access public 
     378         * @var int 
     379         */ 
    134380        var $ID = 0; 
    135         var $id = 0; // Deprecated, use $ID instead. 
     381 
     382        /** 
     383         * The deprecated user's ID. 
     384         * 
     385         * @since 2.0.0 
     386         * @access public 
     387         * @deprecated Use WP_User::$ID 
     388         * @see WP_User::$ID 
     389         * @var int 
     390         */ 
     391        var $id = 0; 
     392 
     393        /** 
     394         * The individual capabilities the user has been given. 
     395         * 
     396         * @since 2.0.0 
     397         * @access public 
     398         * @var array 
     399         */ 
    136400        var $caps = array(); 
     401 
     402        /** 
     403         * User metadata option name. 
     404         * 
     405         * @since 2.0.0 
     406         * @access public 
     407         * @var string 
     408         */ 
    137409        var $cap_key; 
     410 
     411        /** 
     412         * The roles the user is part of. 
     413         * 
     414         * @since 2.0.0 
     415         * @access public 
     416         * @var array 
     417         */ 
    138418        var $roles = array(); 
     419 
     420        /** 
     421         * All capabilities the user has, including individual and role based. 
     422         * 
     423         * @since 2.0.0 
     424         * @access public 
     425         * @var array 
     426         */ 
    139427        var $allcaps = array(); 
    140          
     428 
     429        /** 
     430         * First name of the user. 
     431         * 
     432         * Created to prevent notices. 
     433         * 
     434         * @since 2.7.0 
     435         * @access public 
     436         * @var string 
     437         */ 
    141438        var $first_name = ''; 
     439 
     440        /** 
     441         * Last name of the user. 
     442         * 
     443         * Created to prevent notices. 
     444         * 
     445         * @since 2.7.0 
     446         * @access public 
     447         * @var string 
     448         */ 
    142449        var $last_name = ''; 
    143450 
     451        /** 
     452         * PHP4 Constructor - Sets up the object properties. 
     453         * 
     454         * Retrieves the userdata and then assigns all of the data keys to direct 
     455         * properties of the object. Calls {@link WP_User::_init_caps()} after 
     456         * setting up the object's user data properties. 
     457         * 
     458         * @since 2.0.0 
     459         * @access public 
     460         * 
     461         * @param int|string $id User's ID or username 
     462         * @param int $name Optional. User's username 
     463         * @return WP_User 
     464         */ 
    144465        function WP_User( $id, $name = '' ) { 
    145466 
    146467                if ( empty( $id ) && empty( $name ) ) 
     
    167488                $this->_init_caps(); 
    168489        } 
    169490 
     491        /** 
     492         * Setup capability object properties. 
     493         * 
     494         * Will set the value for the 'cap_key' property to current database table 
     495         * prefix, followed by 'capabilities'. Will then check to see if the 
     496         * property matching the 'cap_key' exists and is an array. If so, it will be 
     497         * used. 
     498         * 
     499         * @since 2.1.0 
     500         * @access protected 
     501         */ 
    170502        function _init_caps() { 
    171503                global $wpdb; 
    172504                $this->cap_key = $wpdb->prefix . 'capabilities'; 
     
    176508                $this->get_role_caps(); 
    177509        } 
    178510 
     511        /** 
     512         * Retrieve all of the role capabilities and merge with individual capabilities. 
     513         * 
     514         * All of the capabilities of the roles the user belongs to are merged with 
     515         * the users individual roles. This also means that the user can be denied 
     516         * specific roles that their role might have, but the specific user isn't 
     517         * granted permission to. 
     518         * 
     519         * @since 2.0.0 
     520         * @uses $wp_roles 
     521         * @access public 
     522         */ 
    179523        function get_role_caps() { 
    180524                global $wp_roles; 
    181525 
     
    195539                $this->allcaps = array_merge( $this->allcaps, $this->caps ); 
    196540        } 
    197541 
     542        /** 
     543         * Add role to user. 
     544         * 
     545         * Updates the user's meta data option with capabilities and roles. 
     546         * 
     547         * @since 2.0.0 
     548         * @access public 
     549         * 
     550         * @param string $role Role name. 
     551         */ 
    198552        function add_role( $role ) { 
    199553                $this->caps[$role] = true; 
    200554                update_usermeta( $this->ID, $this->cap_key, $this->caps ); 
     
    202556                $this->update_user_level_from_caps(); 
    203557        } 
    204558 
     559        /** 
     560         * Remove role from user. 
     561         * 
     562         * @since 2.0.0 
     563         * @access public 
     564         * 
     565         * @param string $role Role name. 
     566         */ 
    205567        function remove_role( $role ) { 
    206568                if ( empty( $this->roles[$role] ) || ( count( $this->roles ) <= 1 ) ) 
    207569                        return; 
     
    210572                $this->get_role_caps(); 
    211573        } 
    212574 
     575        /** 
     576         * Set the role of the user. 
     577         * 
     578         * This will remove the previous roles of the user and assign the user the 
     579         * new one. You can set the role to an empty string and it will remove all 
     580         * of the roles from the user. 
     581         * 
     582         * @since 2.0.0 
     583         * @access public 
     584         * 
     585         * @param string $role Role name. 
     586         */ 
    213587        function set_role( $role ) { 
    214588                foreach ( (array) $this->roles as $oldrole ) 
    215589                        unset( $this->caps[$oldrole] ); 
     
    224598                $this->update_user_level_from_caps(); 
    225599        } 
    226600 
     601        /** 
     602         * Choose the maximum level the user has. 
     603         * 
     604         * Will compare the level from the $item parameter against the $max 
     605         * parameter. If the item is incorrect, then just the $max parameter value 
     606         * will be returned. 
     607         * 
     608         * Used to get the max level based on the capabilities the user has. This 
     609         * is also based on roles, so if the user is assigned the Administrator role 
     610         * then the capability 'level_10' will exist and the user will get that 
     611         * value. 
     612         * 
     613         * @since 2.0.0 
     614         * @access public 
     615         * 
     616         * @param int $max Max level of user. 
     617         * @param string $item Level capability name. 
     618         * @return int Max Level. 
     619         */ 
    227620        function level_reduction( $max, $item ) { 
    228621                if ( preg_match( '/^level_(10|[0-9])$/i', $item, $matches ) ) { 
    229622                        $level = intval( $matches[1] ); 
     
    233626                } 
    234627        } 
    235628 
     629        /** 
     630         * Update the maximum user level for the user. 
     631         * 
     632         * Updates the 'user_level' user metadata (includes prefix that is the 
     633         * database table prefix) with the maximum user level. Gets the value from 
     634         * the all of the capabilities that the user has. 
     635         * 
     636         * @since 2.0.0 
     637         * @access public 
     638         */ 
    236639        function update_user_level_from_caps() { 
    237640                global $wpdb; 
    238641                $this->user_level = array_reduce( array_keys( $this->allcaps ), array( &$this, 'level_reduction' ), 0 ); 
    239642                update_usermeta( $this->ID, $wpdb->prefix.'user_level', $this->user_level ); 
    240643        } 
    241644 
     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         */ 
    242654        function add_cap( $cap, $grant = true ) { 
    243655                $this->caps[$cap] = $grant; 
    244656                update_usermeta( $this->ID, $this->cap_key, $this->caps ); 
    245657        } 
    246658 
     659        /** 
     660         * Remove capability from user. 
     661         * 
     662         * @since 2.0.0 
     663         * @access public 
     664         * 
     665         * @param string $cap Capability name. 
     666         */ 
    247667        function remove_cap( $cap ) { 
    248668                if ( empty( $this->caps[$cap] ) ) return; 
    249669                unset( $this->caps[$cap] ); 
    250670                update_usermeta( $this->ID, $this->cap_key, $this->caps ); 
    251671        } 
    252672 
     673        /** 
     674         * Remove all of the capabilities of the user. 
     675         * 
     676         * @since 2.1.0 
     677         * @access public 
     678         */ 
    253679        function remove_all_caps() { 
    254680                global $wpdb; 
    255681                $this->caps = array(); 
     
    258684                $this->get_role_caps(); 
    259685        } 
    260686 
    261         // has_cap( capability_or_role_name ) or 
    262         // has_cap( 'edit_post', post_id ) 
     687        /** 
     688         * Whether user has capability or role name. 
     689         * 
     690         * This is useful for looking up whether the user has a specific role 
     691         * assigned to the user. The second optional parameter can also be used to 
     692         * check for capabilities against a specfic post. 
     693         * 
     694         * @since 2.0.0 
     695         * @access public 
     696         * 
     697         * @param string|int $cap Capability or role name to search. 
     698         * @param int $post_id Optional. Post ID to check capability against specific post. 
     699         * @return bool True, if user has capability; false, if user does not have capability. 
     700         */ 
    263701        function has_cap( $cap ) { 
    264702                if ( is_numeric( $cap ) ) 
    265703                        $cap = $this->translate_level_to_cap( $cap ); 
     
    278716                return true; 
    279717        } 
    280718 
     719        /** 
     720         * Convert numeric level to level capability name. 
     721         * 
     722         * Prepends 'level_' to level number. 
     723         * 
     724         * @since 2.0.0 
     725         * @access public 
     726         * 
     727         * @param int $level Level number, 1 to 10. 
     728         * @return string 
     729         */ 
    281730        function translate_level_to_cap( $level ) { 
    282731                return 'level_' . $level; 
    283732        } 
    284733 
    285734} 
    286735 
    287 // Map meta capabilities to primitive capabilities. 
     736/** 
     737 * Map meta capabilities to primitive capabilities. 
     738 * 
     739 * This does not actually compare whether the user ID has the actual capability, 
     740 * just what the capability or capabilities are. Meta capability list value can 
     741 * be 'delete_user', 'edit_user', 'delete_post', 'delete_page', 'edit_post', 
     742 * 'edit_page', 'read_post', or 'read_page'. 
     743 * 
     744 * @since 2.0.0 
     745 * 
     746 * @param string $cap Capability name. 
     747 * @param int $user_id User ID. 
     748 * @return array Actual capabilities for meta capability. 
     749 */ 
    288750function map_meta_cap( $cap, $user_id ) { 
    289751        $args = array_slice( func_get_args(), 2 ); 
    290752        $caps = array(); 
     
    446908        return $caps; 
    447909} 
    448910 
    449 // Capability checking wrapper around the global $current_user object. 
     911/** 
     912 * Whether current user has capability or role. 
     913 * 
     914 * @since 2.0.0 
     915 * 
     916 * @param string $capability Capability or role name. 
     917 * @return bool 
     918 */ 
    450919function current_user_can( $capability ) { 
    451920        $current_user = wp_get_current_user(); 
    452921 
     
    459928        return call_user_func_array( array( &$current_user, 'has_cap' ), $args ); 
    460929} 
    461930 
    462 // Convenience wrappers around $wp_roles. 
     931/** 
     932 * Retrieve role object. 
     933 * 
     934 * @see WP_Roles::get_role() Uses method to retrieve role object. 
     935 * @since 2.0.0 
     936 * 
     937 * @param string $role Role name. 
     938 * @return object 
     939 */ 
    463940function get_role( $role ) { 
    464941        global $wp_roles; 
    465942 
     
    469946        return $wp_roles->get_role( $role ); 
    470947} 
    471948 
     949/** 
     950 * Add role, if it does not exist. 
     951 * 
     952 * @see WP_Roles::add_role() Uses method to add role. 
     953 * @since 2.0.0 
     954 * 
     955 * @param string $role Role name. 
     956 * @param string $display_name Display name for role. 
     957 * @param array $capabilities List of capabilities. 
     958 * @return null|WP_Role WP_Role object if role is added, null if already exists. 
     959 */ 
    472960function add_role( $role, $display_name, $capabilities = array() ) { 
    473961        global $wp_roles; 
    474962 
     
    478966        return $wp_roles->add_role( $role, $display_name, $capabilities ); 
    479967} 
    480968 
     969/** 
     970 * Remove role, if it exists. 
     971 * 
     972 * @see WP_Roles::remove_role() Uses method to remove role. 
     973 * @since 2.0.0 
     974 * 
     975 * @param string $role Role name. 
     976 * @return null 
     977 */ 
    481978function remove_role( $role ) { 
    482979        global $wp_roles; 
    483980