WordPress 4.5
[autoinstalls/wordpress.git] / wp-includes / class-wp-customize-control.php
index 3027a7b55c65a8493a55be62f1313e7687db5085..52a8a91ee64d59b058c47ba89d6196fd54d806bf 100644 (file)
@@ -64,6 +64,18 @@ class WP_Customize_Control {
         */
        public $setting = 'default';
 
+       /**
+        * Capability required to use this control.
+        *
+        * Normally this is empty and the capability is derived from the capabilities
+        * of the associated `$settings`.
+        *
+        * @since 4.5.0
+        * @access public
+        * @var string
+        */
+       public $capability;
+
        /**
         * @access public
         * @var int
@@ -133,15 +145,42 @@ class WP_Customize_Control {
        /**
         * Constructor.
         *
-        * Supplied $args override class property defaults.
+        * Supplied `$args` override class property defaults.
         *
-        * If $args['settings'] is not defined, use the $id as the setting ID.
+        * If `$args['settings']` is not defined, use the $id as the setting ID.
         *
         * @since 3.4.0
         *
         * @param WP_Customize_Manager $manager Customizer bootstrap instance.
         * @param string               $id      Control ID.
-        * @param array                $args    Optional. Arguments to override class property defaults.
+        * @param array                $args    {
+        *     Optional. Arguments to override class property defaults.
+        *
+        *     @type int                  $instance_number Order in which this instance was created in relation
+        *                                                 to other instances.
+        *     @type WP_Customize_Manager $manager         Customizer bootstrap instance.
+        *     @type string               $id              Control ID.
+        *     @type array                $settings        All settings tied to the control. If undefined, `$id` will
+        *                                                 be used.
+        *     @type string               $setting         The primary setting for the control (if there is one).
+        *                                                 Default 'default'.
+        *     @type int                  $priority        Order priority to load the control. Default 10.
+        *     @type string               $section         Section the control belongs to. Default empty.
+        *     @type string               $label           Label for the control. Default empty.
+        *     @type string               $description     Description for the control. Default empty.
+        *     @type array                $choices         List of choices for 'radio' or 'select' type controls, where
+        *                                                 values are the keys, and labels are the values.
+        *                                                 Default empty array.
+        *     @type array                $input_attrs     List of custom input attributes for control output, where
+        *                                                 attribute names are the keys and values are the values. Not
+        *                                                 used for 'checkbox', 'radio', 'select', 'textarea', or
+        *                                                 'dropdown-pages' control types. Default empty array.
+        *     @type array                $json            Deprecated. Use {@see WP_Customize_Control->json()} instead.
+        *     @type string               $type            Control type. Core controls include 'text', 'checkbox',
+        *                                                 'textarea', 'radio', 'select', and 'dropdown-pages'. Additional
+        *                                                 input types such as 'email', 'url', 'number', 'hidden', and
+        *                                                 'date' are supported implicitly. Default 'text'.
+        * }
         */
        public function __construct( $manager, $id, $args = array() ) {
                $keys = array_keys( get_object_vars( $this ) );
@@ -160,7 +199,7 @@ class WP_Customize_Control {
                $this->instance_number = self::$instance_count;
 
                // Process settings.
-               if ( empty( $this->settings ) ) {
+               if ( ! isset( $this->settings ) ) {
                        $this->settings = $id;
                }
 
@@ -169,7 +208,7 @@ class WP_Customize_Control {
                        foreach ( $this->settings as $key => $setting ) {
                                $settings[ $key ] = $this->manager->get_setting( $setting );
                        }
-               } else {
+               } else if ( is_string( $this->settings ) ) {
                        $this->setting = $this->manager->get_setting( $this->settings );
                        $settings['default'] = $this->setting;
                }
@@ -272,21 +311,32 @@ class WP_Customize_Control {
        }
 
        /**
-        * Check if the theme supports the control and check user capabilities.
+        * Checks if the user can use this control.
+        *
+        * Returns false if the user cannot manipulate one of the associated settings,
+        * or if one of the associated settings does not exist. Also returns false if
+        * the associated section does not exist or if its capability check returns
+        * false.
         *
         * @since 3.4.0
         *
         * @return bool False if theme doesn't support the control or user doesn't have the required permissions, otherwise true.
         */
        final public function check_capabilities() {
+               if ( ! empty( $this->capability ) && ! current_user_can( $this->capability ) ) {
+                       return false;
+               }
+
                foreach ( $this->settings as $setting ) {
-                       if ( ! $setting->check_capabilities() )
+                       if ( ! $setting || ! $setting->check_capabilities() ) {
                                return false;
+                       }
                }
 
                $section = $this->manager->get_section( $this->section );
-               if ( isset( $section ) && ! $section->check_capabilities() )
+               if ( isset( $section ) && ! $section->check_capabilities() ) {
                        return false;
+               }
 
                return true;
        }