wpcom-endpoints
2 days ago
class-wpcom-rest-field-controller.php
1 month ago
class.jetpack-core-api-module-endpoints.php
2 weeks ago
class.jetpack-core-api-site-endpoints.php
2 months ago
class.jetpack-core-api-widgets-endpoints.php
4 years ago
class.jetpack-core-api-xmlrpc-consumer-endpoint.php
4 years ago
load-wpcom-endpoints.php
7 months ago
class-wpcom-rest-field-controller.php
443 lines
| 1 | <?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName |
| 2 | /** |
| 3 | * `WP_REST_Controller` is basically a wrapper for `register_rest_route()` |
| 4 | * `WPCOM_REST_API_V2_Field_Controller` is a mostly-analogous wrapper for `register_rest_field()` |
| 5 | * |
| 6 | * @todo - nicer API for array values? |
| 7 | * |
| 8 | * @package automattic/jetpack |
| 9 | */ |
| 10 | |
| 11 | /** |
| 12 | * Abstract WPCOM_REST_API_V2_Field_Controller class extended for different fields needed in the Jetpack plugin. |
| 13 | */ |
| 14 | abstract class WPCOM_REST_API_V2_Field_Controller { |
| 15 | /** |
| 16 | * The REST Object Type(s) to which the field should be added. |
| 17 | * |
| 18 | * @var string|string[] |
| 19 | */ |
| 20 | protected $object_type; |
| 21 | |
| 22 | /** |
| 23 | * The name of the REST API field to add. |
| 24 | * |
| 25 | * @var string |
| 26 | */ |
| 27 | protected $field_name; |
| 28 | |
| 29 | /** |
| 30 | * Constructor |
| 31 | */ |
| 32 | public function __construct() { |
| 33 | if ( ! $this->object_type ) { |
| 34 | _doing_it_wrong( |
| 35 | 'WPCOM_REST_API_V2_Field_Controller::$object_type', |
| 36 | sprintf( |
| 37 | /* translators: %s: object_type */ |
| 38 | esc_html__( "Property '%s' must be overridden.", 'jetpack' ), |
| 39 | 'object_type' |
| 40 | ), |
| 41 | 'jetpack-6.8' |
| 42 | ); |
| 43 | return; |
| 44 | } |
| 45 | |
| 46 | if ( ! $this->field_name ) { |
| 47 | _doing_it_wrong( |
| 48 | 'WPCOM_REST_API_V2_Field_Controller::$field_name', |
| 49 | sprintf( |
| 50 | /* translators: %s: field_name */ |
| 51 | esc_html__( "Property '%s' must be overridden.", 'jetpack' ), |
| 52 | 'field_name' |
| 53 | ), |
| 54 | 'jetpack-6.8' |
| 55 | ); |
| 56 | return; |
| 57 | } |
| 58 | |
| 59 | add_action( 'rest_api_init', array( $this, 'register_fields' ) ); |
| 60 | |
| 61 | // do this again later to collect any CPTs that get registered later. |
| 62 | add_action( 'restapi_theme_init', array( $this, 'register_fields' ), 20 ); |
| 63 | } |
| 64 | |
| 65 | /** |
| 66 | * Registers the field with the appropriate schema and callbacks. |
| 67 | */ |
| 68 | public function register_fields() { |
| 69 | foreach ( (array) $this->object_type as $object_type ) { |
| 70 | if ( $this->is_registered( $object_type ) ) { |
| 71 | continue; |
| 72 | } |
| 73 | register_rest_field( |
| 74 | $object_type, |
| 75 | $this->field_name, |
| 76 | array( |
| 77 | 'get_callback' => array( $this, 'get_for_response' ), |
| 78 | 'update_callback' => array( $this, 'update_from_request' ), |
| 79 | 'schema' => $this->get_schema(), |
| 80 | ) |
| 81 | ); |
| 82 | } |
| 83 | } |
| 84 | |
| 85 | /** |
| 86 | * Checks if the field is already registered for the object_type |
| 87 | * |
| 88 | * @param string $object_type The name of the object type. |
| 89 | * @return boolean Whether the field has been registered for the type. |
| 90 | */ |
| 91 | public function is_registered( $object_type ) { |
| 92 | global $wp_rest_additional_fields; |
| 93 | |
| 94 | return ! empty( $wp_rest_additional_fields[ $object_type ][ $this->field_name ] ); |
| 95 | } |
| 96 | |
| 97 | /** |
| 98 | * Ensures the response matches the schema and request context. |
| 99 | * |
| 100 | * @param mixed $value Value passed in request. |
| 101 | * @param WP_REST_Request $request WP API request. |
| 102 | * |
| 103 | * @return mixed |
| 104 | */ |
| 105 | private function prepare_for_response( $value, $request ) { |
| 106 | $context = ! empty( $request['context'] ) ? $request['context'] : 'view'; |
| 107 | $schema = $this->get_schema(); |
| 108 | |
| 109 | $is_valid = rest_validate_value_from_schema( $value, $schema, $this->field_name ); |
| 110 | if ( is_wp_error( $is_valid ) ) { |
| 111 | return $is_valid; |
| 112 | } |
| 113 | |
| 114 | return $this->filter_response_by_context( $value, $schema, $context ); |
| 115 | } |
| 116 | |
| 117 | /** |
| 118 | * Returns the schema's default value |
| 119 | * |
| 120 | * If there is no default, returns the type's falsey value. |
| 121 | * |
| 122 | * @param array $schema Schema to validate against. |
| 123 | * |
| 124 | * @return mixed |
| 125 | */ |
| 126 | final public function get_default_value( $schema ) { |
| 127 | if ( isset( $schema['default'] ) ) { |
| 128 | return $schema['default']; |
| 129 | } |
| 130 | |
| 131 | // If you have something more complicated, use $schema['default']. |
| 132 | switch ( $schema['type'] ?? 'null' ) { |
| 133 | case 'string': |
| 134 | return ''; |
| 135 | case 'integer': |
| 136 | case 'number': |
| 137 | return 0; |
| 138 | case 'object': |
| 139 | return (object) array(); |
| 140 | case 'array': |
| 141 | return array(); |
| 142 | case 'boolean': |
| 143 | return false; |
| 144 | case 'null': |
| 145 | default: |
| 146 | return null; |
| 147 | } |
| 148 | } |
| 149 | |
| 150 | /** |
| 151 | * The field's wrapped getter. Does permission checks and output preparation. |
| 152 | * |
| 153 | * This cannot be extended: implement `->get()` instead. |
| 154 | * |
| 155 | * @param mixed $object_data Probably an array. Whatever the endpoint returns. |
| 156 | * @param string $field_name Should always match `->field_name`. |
| 157 | * @param WP_REST_Request $request WP API request. |
| 158 | * @param string $object_type Should always match `->object_type`. |
| 159 | * |
| 160 | * @return mixed |
| 161 | */ |
| 162 | final public function get_for_response( $object_data, $field_name, $request, $object_type ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable |
| 163 | $permission_check = $this->get_permission_check( $object_data, $request ); |
| 164 | |
| 165 | if ( ! $permission_check ) { |
| 166 | _doing_it_wrong( |
| 167 | 'WPCOM_REST_API_V2_Field_Controller::get_permission_check', |
| 168 | sprintf( |
| 169 | /* translators: %s: get_permission_check() */ |
| 170 | esc_html__( "Method '%s' must return either true or WP_Error.", 'jetpack' ), |
| 171 | 'get_permission_check' |
| 172 | ), |
| 173 | 'jetpack-6.8' |
| 174 | ); |
| 175 | return $this->get_default_value( $this->get_schema() ); |
| 176 | } |
| 177 | |
| 178 | if ( is_wp_error( $permission_check ) ) { |
| 179 | return $this->get_default_value( $this->get_schema() ); |
| 180 | } |
| 181 | |
| 182 | $value = $this->get( $object_data, $request ); |
| 183 | |
| 184 | return $this->prepare_for_response( $value, $request ); |
| 185 | } |
| 186 | |
| 187 | /** |
| 188 | * The field's wrapped setter. Does permission checks. |
| 189 | * |
| 190 | * This cannot be extended: implement `->update()` instead. |
| 191 | * |
| 192 | * @param mixed $value The new value for the field. |
| 193 | * @param mixed $object_data Probably a WordPress object (e.g., WP_Post). |
| 194 | * @param string $field_name Should always match `->field_name`. |
| 195 | * @param WP_REST_Request $request WP API request. |
| 196 | * @param string $object_type Should always match `->object_type`. |
| 197 | * @return void|WP_Error |
| 198 | */ |
| 199 | final public function update_from_request( $value, $object_data, $field_name, $request, $object_type ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable |
| 200 | $permission_check = $this->update_permission_check( $value, $object_data, $request ); |
| 201 | |
| 202 | if ( ! $permission_check ) { |
| 203 | _doing_it_wrong( |
| 204 | 'WPCOM_REST_API_V2_Field_Controller::update_permission_check', |
| 205 | sprintf( |
| 206 | /* translators: %s: update_permission_check() */ |
| 207 | esc_html__( "Method '%s' must return either true or WP_Error.", 'jetpack' ), |
| 208 | 'update_permission_check' |
| 209 | ), |
| 210 | 'jetpack-6.8' |
| 211 | ); |
| 212 | |
| 213 | return new WP_Error( |
| 214 | 'invalid_user_permission', |
| 215 | sprintf( |
| 216 | /* translators: %s: the name of an API response field */ |
| 217 | __( "You are not allowed to access the '%s' field.", 'jetpack' ), |
| 218 | $this->field_name |
| 219 | ) |
| 220 | ); |
| 221 | } |
| 222 | |
| 223 | if ( is_wp_error( $permission_check ) ) { |
| 224 | return $permission_check; |
| 225 | } |
| 226 | |
| 227 | $updated = $this->update( $value, $object_data, $request ); |
| 228 | |
| 229 | if ( is_wp_error( $updated ) ) { |
| 230 | return $updated; |
| 231 | } |
| 232 | } |
| 233 | |
| 234 | /** |
| 235 | * Permission Check for the field's getter. Must be implemented in the inheriting class. |
| 236 | * |
| 237 | * @param mixed $object_data Whatever the endpoint would return for its response. |
| 238 | * @param WP_REST_Request $request WP API request. |
| 239 | * |
| 240 | * @return true|WP_Error |
| 241 | */ |
| 242 | public function get_permission_check( $object_data, $request ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable |
| 243 | _doing_it_wrong( |
| 244 | 'WPCOM_REST_API_V2_Field_Controller::get_permission_check', |
| 245 | sprintf( |
| 246 | /* translators: %s: method name. */ |
| 247 | esc_html__( "Method '%s' must be overridden.", 'jetpack' ), |
| 248 | __METHOD__ |
| 249 | ), |
| 250 | 'jetpack-6.8' |
| 251 | ); |
| 252 | return null; |
| 253 | } |
| 254 | |
| 255 | /** |
| 256 | * The field's "raw" getter. Must be implemented in the inheriting class. |
| 257 | * |
| 258 | * @param mixed $object_data Whatever the endpoint would return for its response. |
| 259 | * @param WP_REST_Request $request WP API request. |
| 260 | * @return mixed |
| 261 | */ |
| 262 | public function get( $object_data, $request ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable |
| 263 | _doing_it_wrong( |
| 264 | 'WPCOM_REST_API_V2_Field_Controller::get', |
| 265 | sprintf( |
| 266 | /* translators: %s: method name. */ |
| 267 | esc_html__( "Method '%s' must be overridden.", 'jetpack' ), |
| 268 | __METHOD__ |
| 269 | ), |
| 270 | 'jetpack-6.8' |
| 271 | ); |
| 272 | } |
| 273 | |
| 274 | /** |
| 275 | * Permission Check for the field's setter. Must be implemented in the inheriting class. |
| 276 | * |
| 277 | * @param mixed $value The new value for the field. |
| 278 | * @param mixed $object_data Probably a WordPress object (e.g., WP_Post). |
| 279 | * @param WP_REST_Request $request WP API request. |
| 280 | * |
| 281 | * @return true|WP_Error |
| 282 | */ |
| 283 | public function update_permission_check( $value, $object_data, $request ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable |
| 284 | _doing_it_wrong( |
| 285 | 'WPCOM_REST_API_V2_Field_Controller::update_permission_check', |
| 286 | sprintf( |
| 287 | /* translators: %s: method name. */ |
| 288 | esc_html__( "Method '%s' must be overridden.", 'jetpack' ), |
| 289 | __METHOD__ |
| 290 | ), |
| 291 | 'jetpack-6.8' |
| 292 | ); |
| 293 | return null; |
| 294 | } |
| 295 | |
| 296 | /** |
| 297 | * The field's "raw" setter. Must be implemented in the inheriting class. |
| 298 | * |
| 299 | * @param mixed $value The new value for the field. |
| 300 | * @param mixed $object_data Probably a WordPress object (e.g., WP_Post). |
| 301 | * @param WP_REST_Request $request WP API request. |
| 302 | * |
| 303 | * @return mixed |
| 304 | */ |
| 305 | public function update( $value, $object_data, $request ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable |
| 306 | _doing_it_wrong( |
| 307 | 'WPCOM_REST_API_V2_Field_Controller::update', |
| 308 | sprintf( |
| 309 | /* translators: %s: method name. */ |
| 310 | esc_html__( "Method '%s' must be overridden.", 'jetpack' ), |
| 311 | __METHOD__ |
| 312 | ), |
| 313 | 'jetpack-6.8' |
| 314 | ); |
| 315 | } |
| 316 | |
| 317 | /** |
| 318 | * The JSON Schema for the field |
| 319 | * |
| 320 | * @link https://json-schema.org/understanding-json-schema/ |
| 321 | * As of WordPress 5.0, Core currently understands: |
| 322 | * * type |
| 323 | * * string - not minLength, not maxLength, not pattern |
| 324 | * * integer - minimum, maximum, exclusiveMinimum, exclusiveMaximum, not multipleOf |
| 325 | * * number - minimum, maximum, exclusiveMinimum, exclusiveMaximum, not multipleOf |
| 326 | * * boolean |
| 327 | * * null |
| 328 | * * object - properties, additionalProperties, not propertyNames, not dependencies, not patternProperties, not required |
| 329 | * * array: only lists, not tuples - items, not minItems, not maxItems, not uniqueItems, not contains |
| 330 | * * enum |
| 331 | * * format |
| 332 | * * date-time |
| 333 | |
| 334 | * * ip |
| 335 | * * uri |
| 336 | * As of WordPress 5.0, Core does not support: |
| 337 | * * Multiple type: `type: [ 'string', 'integer' ]` |
| 338 | * * $ref, allOf, anyOf, oneOf, not, const |
| 339 | * |
| 340 | * @return array |
| 341 | */ |
| 342 | public function get_schema() { |
| 343 | _doing_it_wrong( |
| 344 | 'WPCOM_REST_API_V2_Field_Controller::get_schema', |
| 345 | sprintf( |
| 346 | /* translators: %s: method name. */ |
| 347 | esc_html__( "Method '%s' must be overridden.", 'jetpack' ), |
| 348 | __METHOD__ |
| 349 | ), |
| 350 | 'jetpack-6.8' |
| 351 | ); |
| 352 | return null; |
| 353 | } |
| 354 | |
| 355 | /** |
| 356 | * Ensure that our request matches its expected context. |
| 357 | * |
| 358 | * @param array $schema Schema to validate against. |
| 359 | * @param string $context REST API Request context. |
| 360 | * @return bool |
| 361 | */ |
| 362 | private function is_valid_for_context( $schema, $context ) { |
| 363 | return empty( $schema['context'] ) || in_array( $context, $schema['context'], true ); |
| 364 | } |
| 365 | |
| 366 | /** |
| 367 | * Removes properties that should not appear in the current |
| 368 | * request's context |
| 369 | * |
| 370 | * $context is a Core REST API Framework request attribute that is |
| 371 | * always one of: |
| 372 | * * view (what you see on the blog) |
| 373 | * * edit (what you see in an editor) |
| 374 | * * embed (what you see in, e.g., an oembed) |
| 375 | * |
| 376 | * Fields (and sub-fields, and sub-sub-...) can be flagged for a |
| 377 | * set of specific contexts via the field's schema. |
| 378 | * |
| 379 | * The Core API will filter out top-level fields with the wrong |
| 380 | * context, but will not recurse deeply enough into arrays/objects |
| 381 | * to remove all levels of sub-fields with the wrong context. |
| 382 | * |
| 383 | * This function handles that recursion. |
| 384 | * |
| 385 | * @param mixed $value Value passed to API request. |
| 386 | * @param array $schema Schema to validate against. |
| 387 | * @param string $context REST API Request context. |
| 388 | * |
| 389 | * @return mixed Filtered $value |
| 390 | */ |
| 391 | final public function filter_response_by_context( $value, $schema, $context ) { |
| 392 | if ( ! $this->is_valid_for_context( $schema, $context ) ) { |
| 393 | // We use this intentionally odd looking WP_Error object |
| 394 | // internally only in this recursive function (see below |
| 395 | // in the `object` case). It will never be output by the REST API. |
| 396 | // If we return this for the top level object, Core |
| 397 | // correctly remove the top level object from the response |
| 398 | // for us. |
| 399 | return new WP_Error( '__wrong-context__' ); |
| 400 | } |
| 401 | |
| 402 | switch ( $schema['type'] ) { |
| 403 | case 'array': |
| 404 | if ( ! isset( $schema['items'] ) ) { |
| 405 | return $value; |
| 406 | } |
| 407 | |
| 408 | // Shortcircuit if we know none of the items are valid for this context. |
| 409 | // This would only happen in a strangely written schema. |
| 410 | if ( ! $this->is_valid_for_context( $schema['items'], $context ) ) { |
| 411 | return array(); |
| 412 | } |
| 413 | |
| 414 | // Recurse to prune sub-properties of each item. |
| 415 | foreach ( $value as $key => $item ) { |
| 416 | $value[ $key ] = $this->filter_response_by_context( $item, $schema['items'], $context ); |
| 417 | } |
| 418 | |
| 419 | return $value; |
| 420 | case 'object': |
| 421 | if ( ! isset( $schema['properties'] ) ) { |
| 422 | return $value; |
| 423 | } |
| 424 | |
| 425 | foreach ( $value as $field_name => $field_value ) { |
| 426 | if ( isset( $schema['properties'][ $field_name ] ) ) { |
| 427 | $field_value = $this->filter_response_by_context( $field_value, $schema['properties'][ $field_name ], $context ); |
| 428 | if ( is_wp_error( $field_value ) && '__wrong-context__' === $field_value->get_error_code() ) { |
| 429 | unset( $value[ $field_name ] ); |
| 430 | } else { |
| 431 | // Respect recursion that pruned sub-properties of each property. |
| 432 | $value[ $field_name ] = $field_value; |
| 433 | } |
| 434 | } |
| 435 | } |
| 436 | |
| 437 | return (object) $value; |
| 438 | } |
| 439 | |
| 440 | return $value; |
| 441 | } |
| 442 | } |
| 443 |