Make WordPress Core

Changeset 8904


Ignore:
Timestamp:
09/16/2008 09:51:36 PM (15 years ago)
Author:
ryan
Message:

phpdoc for capabilities.php. Props jacobsantos. fixes #5632

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/capabilities.php

    r8646 r8904  
    11<?php
    2 
     2/**
     3 * WordPress Roles and Capabilities.
     4 *
     5 * @package WordPress
     6 * @subpackage User
     7 */
     8
     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;
     
    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] ) )
     
    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] ) )
     
    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;
     
    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] );
     
    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] ) )
     
    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    {
     
    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;
     
    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;
     
    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;
     
    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 );
     
    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
     
    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;
     
    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;
     
    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;
     
    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 ) )
     
    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 )
     
    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 ) ) {
     
    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;
     
    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;
     
    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;
     
    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;
     
    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 ) )
     
    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;
     
    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 );
     
    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();
     
    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;
     
    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;
     
    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;
Note: See TracChangeset for help on using the changeset viewer.