[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/rest-api/endpoints/ -> class-wp-rest-settings-controller.php (source)

   1  <?php
   2  /**
   3   * REST API: WP_REST_Settings_Controller class
   4   *
   5   * @package WordPress
   6   * @subpackage REST_API
   7   * @since 4.7.0
   8   */
   9  
  10  /**
  11   * Core class used to manage a site's settings via the REST API.
  12   *
  13   * @since 4.7.0
  14   *
  15   * @see WP_REST_Controller
  16   */
  17  class WP_REST_Settings_Controller extends WP_REST_Controller {
  18  
  19      /**
  20       * Constructor.
  21       *
  22       * @since 4.7.0
  23       */
  24  	public function __construct() {
  25          $this->namespace = 'wp/v2';
  26          $this->rest_base = 'settings';
  27      }
  28  
  29      /**
  30       * Registers the routes for the objects of the controller.
  31       *
  32       * @since 4.7.0
  33       *
  34       * @see register_rest_route()
  35       */
  36  	public function register_routes() {
  37  
  38          register_rest_route(
  39              $this->namespace,
  40              '/' . $this->rest_base,
  41              array(
  42                  array(
  43                      'methods'             => WP_REST_Server::READABLE,
  44                      'callback'            => array( $this, 'get_item' ),
  45                      'args'                => array(),
  46                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
  47                  ),
  48                  array(
  49                      'methods'             => WP_REST_Server::EDITABLE,
  50                      'callback'            => array( $this, 'update_item' ),
  51                      'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
  52                      'permission_callback' => array( $this, 'get_item_permissions_check' ),
  53                  ),
  54                  'schema' => array( $this, 'get_public_item_schema' ),
  55              )
  56          );
  57  
  58      }
  59  
  60      /**
  61       * Checks if a given request has access to read and manage settings.
  62       *
  63       * @since 4.7.0
  64       *
  65       * @param WP_REST_Request $request Full details about the request.
  66       * @return bool True if the request has read access for the item, otherwise false.
  67       */
  68  	public function get_item_permissions_check( $request ) {
  69          return current_user_can( 'manage_options' );
  70      }
  71  
  72      /**
  73       * Retrieves the settings.
  74       *
  75       * @since 4.7.0
  76       *
  77       * @param WP_REST_Request $request Full details about the request.
  78       * @return array|WP_Error Array on success, or WP_Error object on failure.
  79       */
  80  	public function get_item( $request ) {
  81          $options  = $this->get_registered_options();
  82          $response = array();
  83  
  84          foreach ( $options as $name => $args ) {
  85              /**
  86               * Filters the value of a setting recognized by the REST API.
  87               *
  88               * Allow hijacking the setting value and overriding the built-in behavior by returning a
  89               * non-null value.  The returned value will be presented as the setting value instead.
  90               *
  91               * @since 4.7.0
  92               *
  93               * @param mixed  $result Value to use for the requested setting. Can be a scalar
  94               *                       matching the registered schema for the setting, or null to
  95               *                       follow the default get_option() behavior.
  96               * @param string $name   Setting name (as shown in REST API responses).
  97               * @param array  $args   Arguments passed to register_setting() for this setting.
  98               */
  99              $response[ $name ] = apply_filters( 'rest_pre_get_setting', null, $name, $args );
 100  
 101              if ( is_null( $response[ $name ] ) ) {
 102                  // Default to a null value as "null" in the response means "not set".
 103                  $response[ $name ] = get_option( $args['option_name'], $args['schema']['default'] );
 104              }
 105  
 106              /*
 107               * Because get_option() is lossy, we have to
 108               * cast values to the type they are registered with.
 109               */
 110              $response[ $name ] = $this->prepare_value( $response[ $name ], $args['schema'] );
 111          }
 112  
 113          return $response;
 114      }
 115  
 116      /**
 117       * Prepares a value for output based off a schema array.
 118       *
 119       * @since 4.7.0
 120       *
 121       * @param mixed $value  Value to prepare.
 122       * @param array $schema Schema to match.
 123       * @return mixed The prepared value.
 124       */
 125  	protected function prepare_value( $value, $schema ) {
 126          // If the value is not valid by the schema, set the value to null. Null
 127          // values are specifcally non-destructive so this will not cause overwriting
 128          // the current invalid value to null.
 129          if ( is_wp_error( rest_validate_value_from_schema( $value, $schema ) ) ) {
 130              return null;
 131          }
 132          return rest_sanitize_value_from_schema( $value, $schema );
 133      }
 134  
 135      /**
 136       * Updates settings for the settings object.
 137       *
 138       * @since 4.7.0
 139       *
 140       * @param WP_REST_Request $request Full details about the request.
 141       * @return array|WP_Error Array on success, or error object on failure.
 142       */
 143  	public function update_item( $request ) {
 144          $options = $this->get_registered_options();
 145  
 146          $params = $request->get_params();
 147  
 148          foreach ( $options as $name => $args ) {
 149              if ( ! array_key_exists( $name, $params ) ) {
 150                  continue;
 151              }
 152  
 153              /**
 154               * Filters whether to preempt a setting value update.
 155               *
 156               * Allows hijacking the setting update logic and overriding the built-in behavior by
 157               * returning true.
 158               *
 159               * @since 4.7.0
 160               *
 161               * @param bool   $result Whether to override the default behavior for updating the
 162               *                       value of a setting.
 163               * @param string $name   Setting name (as shown in REST API responses).
 164               * @param mixed  $value  Updated setting value.
 165               * @param array  $args   Arguments passed to register_setting() for this setting.
 166               */
 167              $updated = apply_filters( 'rest_pre_update_setting', false, $name, $request[ $name ], $args );
 168  
 169              if ( $updated ) {
 170                  continue;
 171              }
 172  
 173              /*
 174               * A null value for an option would have the same effect as
 175               * deleting the option from the database, and relying on the
 176               * default value.
 177               */
 178              if ( is_null( $request[ $name ] ) ) {
 179                  /*
 180                   * A null value is returned in the response for any option
 181                   * that has a non-scalar value.
 182                   *
 183                   * To protect clients from accidentally including the null
 184                   * values from a response object in a request, we do not allow
 185                   * options with values that don't pass validation to be updated to null.
 186                   * Without this added protection a client could mistakenly
 187                   * delete all options that have invalid values from the
 188                   * database.
 189                   */
 190                  if ( is_wp_error( rest_validate_value_from_schema( get_option( $args['option_name'], false ), $args['schema'] ) ) ) {
 191                      return new WP_Error(
 192                          'rest_invalid_stored_value',
 193                          /* translators: %s: Property name. */
 194                          sprintf( __( 'The %s property has an invalid stored value, and cannot be updated to null.' ), $name ),
 195                          array( 'status' => 500 )
 196                      );
 197                  }
 198  
 199                  delete_option( $args['option_name'] );
 200              } else {
 201                  update_option( $args['option_name'], $request[ $name ] );
 202              }
 203          }
 204  
 205          return $this->get_item( $request );
 206      }
 207  
 208      /**
 209       * Retrieves all of the registered options for the Settings API.
 210       *
 211       * @since 4.7.0
 212       *
 213       * @return array Array of registered options.
 214       */
 215  	protected function get_registered_options() {
 216          $rest_options = array();
 217  
 218          foreach ( get_registered_settings() as $name => $args ) {
 219              if ( empty( $args['show_in_rest'] ) ) {
 220                  continue;
 221              }
 222  
 223              $rest_args = array();
 224  
 225              if ( is_array( $args['show_in_rest'] ) ) {
 226                  $rest_args = $args['show_in_rest'];
 227              }
 228  
 229              $defaults = array(
 230                  'name'   => ! empty( $rest_args['name'] ) ? $rest_args['name'] : $name,
 231                  'schema' => array(),
 232              );
 233  
 234              $rest_args = array_merge( $defaults, $rest_args );
 235  
 236              $default_schema = array(
 237                  'type'        => empty( $args['type'] ) ? null : $args['type'],
 238                  'description' => empty( $args['description'] ) ? '' : $args['description'],
 239                  'default'     => isset( $args['default'] ) ? $args['default'] : null,
 240              );
 241  
 242              $rest_args['schema']      = array_merge( $default_schema, $rest_args['schema'] );
 243              $rest_args['option_name'] = $name;
 244  
 245              // Skip over settings that don't have a defined type in the schema.
 246              if ( empty( $rest_args['schema']['type'] ) ) {
 247                  continue;
 248              }
 249  
 250              /*
 251               * Whitelist the supported types for settings, as we don't want invalid types
 252               * to be updated with arbitrary values that we can't do decent sanitizing for.
 253               */
 254              if ( ! in_array( $rest_args['schema']['type'], array( 'number', 'integer', 'string', 'boolean', 'array', 'object' ), true ) ) {
 255                  continue;
 256              }
 257  
 258              $rest_args['schema'] = $this->set_additional_properties_to_false( $rest_args['schema'] );
 259  
 260              $rest_options[ $rest_args['name'] ] = $rest_args;
 261          }
 262  
 263          return $rest_options;
 264      }
 265  
 266      /**
 267       * Retrieves the site setting schema, conforming to JSON Schema.
 268       *
 269       * @since 4.7.0
 270       *
 271       * @return array Item schema data.
 272       */
 273  	public function get_item_schema() {
 274          if ( $this->schema ) {
 275              return $this->add_additional_fields_schema( $this->schema );
 276          }
 277  
 278          $options = $this->get_registered_options();
 279  
 280          $schema = array(
 281              '$schema'    => 'http://json-schema.org/draft-04/schema#',
 282              'title'      => 'settings',
 283              'type'       => 'object',
 284              'properties' => array(),
 285          );
 286  
 287          foreach ( $options as $option_name => $option ) {
 288              $schema['properties'][ $option_name ]                = $option['schema'];
 289              $schema['properties'][ $option_name ]['arg_options'] = array(
 290                  'sanitize_callback' => array( $this, 'sanitize_callback' ),
 291              );
 292          }
 293  
 294          $this->schema = $schema;
 295          return $this->add_additional_fields_schema( $this->schema );
 296      }
 297  
 298      /**
 299       * Custom sanitize callback used for all options to allow the use of 'null'.
 300       *
 301       * By default, the schema of settings will throw an error if a value is set to
 302       * `null` as it's not a valid value for something like "type => string". We
 303       * provide a wrapper sanitizer to whitelist the use of `null`.
 304       *
 305       * @since 4.7.0
 306       *
 307       * @param mixed           $value   The value for the setting.
 308       * @param WP_REST_Request $request The request object.
 309       * @param string          $param   The parameter name.
 310       * @return mixed|WP_Error
 311       */
 312  	public function sanitize_callback( $value, $request, $param ) {
 313          if ( is_null( $value ) ) {
 314              return $value;
 315          }
 316          return rest_parse_request_arg( $value, $request, $param );
 317      }
 318  
 319      /**
 320       * Recursively add additionalProperties = false to all objects in a schema.
 321       *
 322       * This is need to restrict properties of objects in settings values to only
 323       * registered items, as the REST API will allow additional properties by
 324       * default.
 325       *
 326       * @since 4.9.0
 327       *
 328       * @param array $schema The schema array.
 329       * @return array
 330       */
 331  	protected function set_additional_properties_to_false( $schema ) {
 332          switch ( $schema['type'] ) {
 333              case 'object':
 334                  foreach ( $schema['properties'] as $key => $child_schema ) {
 335                      $schema['properties'][ $key ] = $this->set_additional_properties_to_false( $child_schema );
 336                  }
 337                  $schema['additionalProperties'] = false;
 338                  break;
 339              case 'array':
 340                  $schema['items'] = $this->set_additional_properties_to_false( $schema['items'] );
 341                  break;
 342          }
 343  
 344          return $schema;
 345      }
 346  }


Generated: Tue Sep 17 01:00:03 2019 Cross-referenced by PHPXref 0.7.1