WordPress.org

Make WordPress Core

Ticket #5632: 5632.r8903.diff

File 5632.r8903.diff, 16.8 KB (added by jacobsantos, 10 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