Changeset 8904
- Timestamp:
- 09/16/2008 09:51:36 PM (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/wp-includes/capabilities.php
r8646 r8904 1 1 <?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 */ 3 29 class WP_Roles { 30 /** 31 * List of roles and capabilities. 32 * 33 * @since 2.0.0 34 * @access public 35 * @var array 36 */ 4 37 var $roles; 5 38 39 /** 40 * List of the role objects. 41 * 42 * @since 2.0.0 43 * @access public 44 * @var array 45 */ 6 46 var $role_objects = array(); 47 48 /** 49 * List of role names. 50 * 51 * @since 2.0.0 52 * @access public 53 * @var array 54 */ 7 55 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 */ 8 64 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 */ 9 73 var $use_db = true; 10 74 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 */ 11 83 function WP_Roles() { 12 84 $this->_init(); 13 85 } 14 86 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 */ 15 99 function _init () { 16 100 global $wpdb; … … 35 119 } 36 120 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 */ 37 134 function add_role( $role, $display_name, $capabilities = array() ) { 38 135 if ( isset( $this->roles[$role] ) ) … … 50 147 } 51 148 149 /** 150 * Remove role by name. 151 * 152 * @since 2.0.0 153 * @access public 154 * 155 * @param string $role Role name. 156 */ 52 157 function remove_role( $role ) { 53 158 if ( ! isset( $this->role_objects[$role] ) ) … … 62 167 } 63 168 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 */ 64 179 function add_cap( $role, $cap, $grant = true ) { 65 180 $this->roles[$role]['capabilities'][$cap] = $grant; … … 68 183 } 69 184 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 */ 70 194 function remove_cap( $role, $cap ) { 71 195 unset( $this->roles[$role]['capabilities'][$cap] ); … … 74 198 } 75 199 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 */ 76 209 function &get_role( $role ) { 77 210 if ( isset( $this->role_objects[$role] ) ) … … 81 214 } 82 215 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 */ 83 224 function get_names() { 84 225 return $this->role_names; 85 226 } 86 227 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 */ 87 237 function is_role( $role ) 88 238 { … … 91 241 } 92 242 243 /** 244 * WordPress Role class. 245 * 246 * @since 2.0.0 247 * @package WordPress 248 * @subpackage User 249 */ 93 250 class WP_Role { 251 /** 252 * Role name. 253 * 254 * @since 2.0.0 255 * @access public 256 * @var string 257 */ 94 258 var $name; 259 260 /** 261 * List of capabilities the role contains. 262 * 263 * @since 2.0.0 264 * @access public 265 * @var array 266 */ 95 267 var $capabilities; 96 268 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 */ 97 282 function WP_Role( $role, $capabilities ) { 98 283 $this->name = $role; … … 100 285 } 101 286 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 */ 102 297 function add_cap( $cap, $grant = true ) { 103 298 global $wp_roles; … … 110 305 } 111 306 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 */ 112 320 function remove_cap( $cap ) { 113 321 global $wp_roles; … … 120 328 } 121 329 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 */ 122 344 function has_cap( $cap ) { 123 345 $capabilities = apply_filters( 'role_has_cap', $this->capabilities, $cap, $this->name ); … … 130 352 } 131 353 354 /** 355 * WordPress User class. 356 * 357 * @since 2.0.0 358 * @package WordPress 359 * @subpackage User 360 */ 132 361 class 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 */ 133 371 var $data; 372 373 /** 374 * The user's ID. 375 * 376 * @since 2.1.0 377 * @access public 378 * @var int 379 */ 134 380 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 */ 136 400 var $caps = array(); 401 402 /** 403 * User metadata option name. 404 * 405 * @since 2.0.0 406 * @access public 407 * @var string 408 */ 137 409 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 */ 138 418 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 */ 139 427 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 */ 141 438 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 */ 142 449 var $last_name = ''; 143 450 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 */ 144 465 function WP_User( $id, $name = '' ) { 145 466 … … 168 489 } 169 490 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 */ 170 502 function _init_caps() { 171 503 global $wpdb; … … 177 509 } 178 510 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 */ 179 523 function get_role_caps() { 180 524 global $wp_roles; … … 196 540 } 197 541 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 */ 198 552 function add_role( $role ) { 199 553 $this->caps[$role] = true; … … 203 557 } 204 558 559 /** 560 * Remove role from user. 561 * 562 * @since 2.0.0 563 * @access public 564 * 565 * @param string $role Role name. 566 */ 205 567 function remove_role( $role ) { 206 568 if ( empty( $this->roles[$role] ) || ( count( $this->roles ) <= 1 ) ) … … 211 573 } 212 574 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 */ 213 587 function set_role( $role ) { 214 588 foreach ( (array) $this->roles as $oldrole ) … … 225 599 } 226 600 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 */ 227 620 function level_reduction( $max, $item ) { 228 621 if ( preg_match( '/^level_(10|[0-9])$/i', $item, $matches ) ) { … … 234 627 } 235 628 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 */ 236 639 function update_user_level_from_caps() { 237 640 global $wpdb; … … 240 643 } 241 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 */ 242 654 function add_cap( $cap, $grant = true ) { 243 655 $this->caps[$cap] = $grant; … … 245 657 } 246 658 659 /** 660 * Remove capability from user. 661 * 662 * @since 2.0.0 663 * @access public 664 * 665 * @param string $cap Capability name. 666 */ 247 667 function remove_cap( $cap ) { 248 668 if ( empty( $this->caps[$cap] ) ) return; … … 251 671 } 252 672 673 /** 674 * Remove all of the capabilities of the user. 675 * 676 * @since 2.1.0 677 * @access public 678 */ 253 679 function remove_all_caps() { 254 680 global $wpdb; … … 259 685 } 260 686 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 */ 263 701 function has_cap( $cap ) { 264 702 if ( is_numeric( $cap ) ) … … 279 717 } 280 718 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 */ 281 730 function translate_level_to_cap( $level ) { 282 731 return 'level_' . $level; … … 285 734 } 286 735 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 */ 288 750 function map_meta_cap( $cap, $user_id ) { 289 751 $args = array_slice( func_get_args(), 2 ); … … 447 909 } 448 910 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 */ 450 919 function current_user_can( $capability ) { 451 920 $current_user = wp_get_current_user(); … … 460 929 } 461 930 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 */ 463 940 function get_role( $role ) { 464 941 global $wp_roles; … … 470 947 } 471 948 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 */ 472 960 function add_role( $role, $display_name, $capabilities = array() ) { 473 961 global $wp_roles; … … 479 967 } 480 968 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 */ 481 978 function remove_role( $role ) { 482 979 global $wp_roles;
Note: See TracChangeset
for help on using the changeset viewer.