Automattic /
jetpack
Duplicate code is one of the most pungent code smells. A rule that is often used is to re-structure code once it is duplicated in three or more places.
Common duplication problems, and corresponding solutions are:
Complex classes like WPCOM_JSON_API_Endpoint often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes. You can also have a look at the cohesion graph to spot any un-connected, or weakly-connected components.
Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.
While breaking up the class, it is a good idea to analyze how other classes use WPCOM_JSON_API_Endpoint, and based on these observations, apply Extract Interface, too.
| 1 | <?php |
||
| 9 | abstract class WPCOM_JSON_API_Endpoint { |
||
| 10 | // The API Object |
||
| 11 | public $api; |
||
| 12 | |||
| 13 | // The link-generating utility class |
||
| 14 | public $links; |
||
| 15 | |||
| 16 | public $pass_wpcom_user_details = false; |
||
| 17 | |||
| 18 | // One liner. |
||
| 19 | public $description; |
||
| 20 | |||
| 21 | // Object Grouping For Documentation (Users, Posts, Comments) |
||
| 22 | public $group; |
||
| 23 | |||
| 24 | // Stats extra value to bump |
||
| 25 | public $stat; |
||
| 26 | |||
| 27 | // HTTP Method |
||
| 28 | public $method = 'GET'; |
||
| 29 | |||
| 30 | // Minimum version of the api for which to serve this endpoint |
||
| 31 | public $min_version = '0'; |
||
| 32 | |||
| 33 | // Maximum version of the api for which to serve this endpoint |
||
| 34 | public $max_version = WPCOM_JSON_API__CURRENT_VERSION; |
||
| 35 | |||
| 36 | // Path at which to serve this endpoint: sprintf() format. |
||
| 37 | public $path = ''; |
||
| 38 | |||
| 39 | // Identifiers to fill sprintf() formatted $path |
||
| 40 | public $path_labels = array(); |
||
| 41 | |||
| 42 | // Accepted query parameters |
||
| 43 | public $query = array( |
||
| 44 | // Parameter name |
||
| 45 | 'context' => array( |
||
| 46 | // Default value => description |
||
| 47 | 'display' => 'Formats the output as HTML for display. Shortcodes are parsed, paragraph tags are added, etc..', |
||
| 48 | // Other possible values => description |
||
| 49 | 'edit' => 'Formats the output for editing. Shortcodes are left unparsed, significant whitespace is kept, etc..', |
||
| 50 | ), |
||
| 51 | 'http_envelope' => array( |
||
| 52 | 'false' => '', |
||
| 53 | 'true' => 'Some environments (like in-browser JavaScript or Flash) block or divert responses with a non-200 HTTP status code. Setting this parameter will force the HTTP status code to always be 200. The JSON response is wrapped in an "envelope" containing the "real" HTTP status code and headers.', |
||
| 54 | ), |
||
| 55 | 'pretty' => array( |
||
| 56 | 'false' => '', |
||
| 57 | 'true' => 'Output pretty JSON', |
||
| 58 | ), |
||
| 59 | 'meta' => "(string) Optional. Loads data from the endpoints found in the 'meta' part of the response. Comma-separated list. Example: meta=site,likes", |
||
| 60 | 'fields' => '(string) Optional. Returns specified fields only. Comma-separated list. Example: fields=ID,title', |
||
| 61 | // Parameter name => description (default value is empty) |
||
| 62 | 'callback' => '(string) An optional JSONP callback function.', |
||
| 63 | ); |
||
| 64 | |||
| 65 | // Response format |
||
| 66 | public $response_format = array(); |
||
| 67 | |||
| 68 | // Request format |
||
| 69 | public $request_format = array(); |
||
| 70 | |||
| 71 | // Is this endpoint still in testing phase? If so, not available to the public. |
||
| 72 | public $in_testing = false; |
||
| 73 | |||
| 74 | // Is this endpoint still allowed if the site in question is flagged? |
||
| 75 | public $allowed_if_flagged = false; |
||
| 76 | |||
| 77 | // Is this endpoint allowed if the site is red flagged? |
||
| 78 | public $allowed_if_red_flagged = false; |
||
| 79 | |||
| 80 | /** |
||
| 81 | * @var string Version of the API |
||
| 82 | */ |
||
| 83 | public $version = ''; |
||
| 84 | |||
| 85 | /** |
||
| 86 | * @var string Example request to make |
||
| 87 | */ |
||
| 88 | public $example_request = ''; |
||
| 89 | |||
| 90 | /** |
||
| 91 | * @var string Example request data (for POST methods) |
||
| 92 | */ |
||
| 93 | public $example_request_data = ''; |
||
| 94 | |||
| 95 | /** |
||
| 96 | * @var string Example response from $example_request |
||
| 97 | */ |
||
| 98 | public $example_response = ''; |
||
| 99 | |||
| 100 | /** |
||
| 101 | * @var bool Set to true if the endpoint implements its own filtering instead of the standard `fields` query method |
||
| 102 | */ |
||
| 103 | public $custom_fields_filtering = false; |
||
| 104 | |||
| 105 | /** |
||
| 106 | * @var bool Set to true if the endpoint accepts all cross origin requests. You probably should not set this flag. |
||
| 107 | */ |
||
| 108 | public $allow_cross_origin_request = false; |
||
| 109 | |||
| 110 | /** |
||
| 111 | * @var bool Set to true if the endpoint can recieve unauthorized POST requests. |
||
| 112 | */ |
||
| 113 | public $allow_unauthorized_request = false; |
||
| 114 | |||
| 115 | /** |
||
| 116 | * @var bool Set to true if the endpoint should accept site based (not user based) authentication. |
||
| 117 | */ |
||
| 118 | public $allow_jetpack_site_auth = false; |
||
| 119 | |||
| 120 | /** |
||
| 121 | * @var bool Set to true if the endpoint should accept auth from an upload token. |
||
| 122 | */ |
||
| 123 | public $allow_upload_token_auth = false; |
||
| 124 | |||
| 125 | function __construct( $args ) { |
||
| 225 | |||
| 226 | // Get all query args. Prefill with defaults |
||
| 227 | function query_args( $return_default_values = true, $cast_and_filter = true ) { |
||
| 236 | |||
| 237 | // Get POST body data |
||
| 238 | function input( $return_default_values = true, $cast_and_filter = true ) { |
||
| 295 | |||
| 296 | |||
| 297 | protected function get_secure_body( $secure_key ) { |
||
| 309 | |||
| 310 | function cast_and_filter( $data, $documentation, $return_default_values = false, $for_output = false ) { |
||
| 371 | |||
| 372 | /** |
||
| 373 | * Casts $value according to $type. |
||
| 374 | * Handles fallbacks for certain values of $type when $value is not that $type |
||
| 375 | * Currently, only handles fallback between string <-> array (two way), from string -> false (one way), and from object -> false (one way), |
||
| 376 | * and string -> object (one way) |
||
| 377 | * |
||
| 378 | * Handles "child types" - array:URL, object:category |
||
| 379 | * array:URL means an array of URLs |
||
| 380 | * object:category means a hash of categories |
||
| 381 | * |
||
| 382 | * Handles object typing - object>post means an object of type post |
||
| 383 | */ |
||
| 384 | function cast_and_filter_item( &$return, $type, $key, $value, $types = array(), $for_output = false ) { |
||
| 385 | if ( is_string( $type ) ) { |
||
| 386 | $type = compact( 'type' ); |
||
| 387 | } |
||
| 388 | |||
| 389 | switch ( $type['type'] ) { |
||
| 390 | case 'false' : |
||
| 391 | $return[$key] = false; |
||
| 392 | break; |
||
| 393 | case 'url' : |
||
| 394 | $return[$key] = (string) esc_url_raw( $value ); |
||
| 395 | break; |
||
| 396 | case 'string' : |
||
| 397 | // Fallback string -> array, or for string -> object |
||
| 398 | if ( is_array( $value ) || is_object( $value ) ) { |
||
| 399 | View Code Duplication | if ( !empty( $types[0] ) ) { |
|
| 400 | $next_type = array_shift( $types ); |
||
| 401 | return $this->cast_and_filter_item( $return, $next_type, $key, $value, $types, $for_output ); |
||
| 402 | } |
||
| 403 | } |
||
| 404 | |||
| 405 | // Fallback string -> false |
||
| 406 | View Code Duplication | if ( !is_string( $value ) ) { |
|
| 407 | if ( !empty( $types[0] ) && 'false' === $types[0]['type'] ) { |
||
| 408 | $next_type = array_shift( $types ); |
||
| 409 | return $this->cast_and_filter_item( $return, $next_type, $key, $value, $types, $for_output ); |
||
| 410 | } |
||
| 411 | } |
||
| 412 | $return[$key] = (string) $value; |
||
| 413 | break; |
||
| 414 | case 'html' : |
||
| 415 | $return[$key] = (string) $value; |
||
| 416 | break; |
||
| 417 | case 'safehtml' : |
||
| 418 | $return[$key] = wp_kses( (string) $value, wp_kses_allowed_html() ); |
||
| 419 | break; |
||
| 420 | case 'zip' : |
||
| 421 | case 'media' : |
||
| 422 | if ( is_array( $value ) ) { |
||
| 423 | if ( isset( $value['name'] ) && is_array( $value['name'] ) ) { |
||
| 424 | // It's a $_FILES array |
||
| 425 | // Reformat into array of $_FILES items |
||
| 426 | $files = array(); |
||
| 427 | |||
| 428 | foreach ( $value['name'] as $k => $v ) { |
||
| 429 | $files[$k] = array(); |
||
| 430 | foreach ( array_keys( $value ) as $file_key ) { |
||
| 431 | $files[$k][$file_key] = $value[$file_key][$k]; |
||
| 432 | } |
||
| 433 | } |
||
| 434 | |||
| 435 | $return[$key] = $files; |
||
| 436 | break; |
||
| 437 | } |
||
| 438 | } else { |
||
| 439 | // no break - treat as 'array' |
||
| 440 | } |
||
| 441 | // nobreak |
||
| 442 | case 'array' : |
||
| 443 | // Fallback array -> string |
||
| 444 | View Code Duplication | if ( is_string( $value ) ) { |
|
| 445 | if ( !empty( $types[0] ) ) { |
||
| 446 | $next_type = array_shift( $types ); |
||
| 447 | return $this->cast_and_filter_item( $return, $next_type, $key, $value, $types, $for_output ); |
||
| 448 | } |
||
| 449 | } |
||
| 450 | |||
| 451 | View Code Duplication | if ( isset( $type['children'] ) ) { |
|
| 452 | $children = array(); |
||
| 453 | foreach ( (array) $value as $k => $child ) { |
||
| 454 | $this->cast_and_filter_item( $children, $type['children'], $k, $child, array(), $for_output ); |
||
| 455 | } |
||
| 456 | $return[$key] = (array) $children; |
||
| 457 | break; |
||
| 458 | } |
||
| 459 | |||
| 460 | $return[$key] = (array) $value; |
||
| 461 | break; |
||
| 462 | case 'iso 8601 datetime' : |
||
| 463 | case 'datetime' : |
||
| 464 | // (string)s |
||
| 465 | $dates = $this->parse_date( (string) $value ); |
||
| 466 | if ( $for_output ) { |
||
| 467 | $return[$key] = $this->format_date( $dates[1], $dates[0] ); |
||
| 468 | } else { |
||
| 469 | list( $return[$key], $return["{$key}_gmt"] ) = $dates; |
||
| 470 | } |
||
| 471 | break; |
||
| 472 | case 'float' : |
||
| 473 | $return[$key] = (float) $value; |
||
| 474 | break; |
||
| 475 | case 'int' : |
||
| 476 | case 'integer' : |
||
| 477 | $return[$key] = (int) $value; |
||
| 478 | break; |
||
| 479 | case 'bool' : |
||
| 480 | case 'boolean' : |
||
| 481 | $return[$key] = (bool) WPCOM_JSON_API::is_truthy( $value ); |
||
| 482 | break; |
||
| 483 | case 'object' : |
||
| 484 | // Fallback object -> false |
||
| 485 | View Code Duplication | if ( is_scalar( $value ) || is_null( $value ) ) { |
|
| 486 | if ( !empty( $types[0] ) && 'false' === $types[0]['type'] ) { |
||
| 487 | return $this->cast_and_filter_item( $return, 'false', $key, $value, $types, $for_output ); |
||
| 488 | } |
||
| 489 | } |
||
| 490 | |||
| 491 | View Code Duplication | if ( isset( $type['children'] ) ) { |
|
| 492 | $children = array(); |
||
| 493 | foreach ( (array) $value as $k => $child ) { |
||
| 494 | $this->cast_and_filter_item( $children, $type['children'], $k, $child, array(), $for_output ); |
||
| 495 | } |
||
| 496 | $return[$key] = (object) $children; |
||
| 497 | break; |
||
| 498 | } |
||
| 499 | |||
| 500 | if ( isset( $type['subtype'] ) ) { |
||
| 501 | return $this->cast_and_filter_item( $return, $type['subtype'], $key, $value, $types, $for_output ); |
||
| 502 | } |
||
| 503 | |||
| 504 | $return[$key] = (object) $value; |
||
| 505 | break; |
||
| 506 | case 'post' : |
||
| 507 | $return[$key] = (object) $this->cast_and_filter( $value, $this->post_object_format, false, $for_output ); |
||
| 508 | break; |
||
| 509 | case 'comment' : |
||
| 510 | $return[$key] = (object) $this->cast_and_filter( $value, $this->comment_object_format, false, $for_output ); |
||
| 511 | break; |
||
| 512 | case 'tag' : |
||
| 513 | case 'category' : |
||
| 514 | $docs = array( |
||
| 515 | 'ID' => '(int)', |
||
| 516 | 'name' => '(string)', |
||
| 517 | 'slug' => '(string)', |
||
| 518 | 'description' => '(HTML)', |
||
| 519 | 'post_count' => '(int)', |
||
| 520 | 'meta' => '(object)', |
||
| 521 | ); |
||
| 522 | if ( 'category' === $type['type'] ) { |
||
| 523 | $docs['parent'] = '(int)'; |
||
| 524 | } |
||
| 525 | $return[$key] = (object) $this->cast_and_filter( $value, $docs, false, $for_output ); |
||
| 526 | break; |
||
| 527 | case 'post_reference' : |
||
| 528 | View Code Duplication | case 'comment_reference' : |
|
| 529 | $docs = array( |
||
| 530 | 'ID' => '(int)', |
||
| 531 | 'type' => '(string)', |
||
| 532 | 'title' => '(string)', |
||
| 533 | 'link' => '(URL)', |
||
| 534 | ); |
||
| 535 | $return[$key] = (object) $this->cast_and_filter( $value, $docs, false, $for_output ); |
||
| 536 | break; |
||
| 537 | View Code Duplication | case 'geo' : |
|
| 538 | $docs = array( |
||
| 539 | 'latitude' => '(float)', |
||
| 540 | 'longitude' => '(float)', |
||
| 541 | 'address' => '(string)', |
||
| 542 | ); |
||
| 543 | $return[$key] = (object) $this->cast_and_filter( $value, $docs, false, $for_output ); |
||
| 544 | break; |
||
| 545 | case 'author' : |
||
| 546 | $docs = array( |
||
| 547 | 'ID' => '(int)', |
||
| 548 | 'user_login' => '(string)', |
||
| 549 | 'login' => '(string)', |
||
| 550 | 'email' => '(string|false)', |
||
| 551 | 'name' => '(string)', |
||
| 552 | 'first_name' => '(string)', |
||
| 553 | 'last_name' => '(string)', |
||
| 554 | 'nice_name' => '(string)', |
||
| 555 | 'URL' => '(URL)', |
||
| 556 | 'avatar_URL' => '(URL)', |
||
| 557 | 'profile_URL' => '(URL)', |
||
| 558 | 'is_super_admin' => '(bool)', |
||
| 559 | 'roles' => '(array:string)' |
||
| 560 | ); |
||
| 561 | $return[$key] = (object) $this->cast_and_filter( $value, $docs, false, $for_output ); |
||
| 562 | break; |
||
| 563 | View Code Duplication | case 'role' : |
|
| 564 | $docs = array( |
||
| 565 | 'name' => '(string)', |
||
| 566 | 'display_name' => '(string)', |
||
| 567 | 'capabilities' => '(object:boolean)', |
||
| 568 | ); |
||
| 569 | $return[$key] = (object) $this->cast_and_filter( $value, $docs, false, $for_output ); |
||
| 570 | break; |
||
| 571 | case 'attachment' : |
||
| 572 | $docs = array( |
||
| 573 | 'ID' => '(int)', |
||
| 574 | 'URL' => '(URL)', |
||
| 575 | 'guid' => '(string)', |
||
| 576 | 'mime_type' => '(string)', |
||
| 577 | 'width' => '(int)', |
||
| 578 | 'height' => '(int)', |
||
| 579 | 'duration' => '(int)', |
||
| 580 | ); |
||
| 581 | $return[$key] = (object) $this->cast_and_filter( |
||
| 582 | $value, |
||
| 583 | /** |
||
| 584 | * Filter the documentation returned for a post attachment. |
||
| 585 | * |
||
| 586 | * @module json-api |
||
| 587 | * |
||
| 588 | * @since 1.9.0 |
||
| 589 | * |
||
| 590 | * @param array $docs Array of documentation about a post attachment. |
||
| 591 | */ |
||
| 592 | apply_filters( 'wpcom_json_api_attachment_cast_and_filter', $docs ), |
||
| 593 | false, |
||
| 594 | $for_output |
||
| 595 | ); |
||
| 596 | break; |
||
| 597 | case 'metadata' : |
||
| 598 | $docs = array( |
||
| 599 | 'id' => '(int)', |
||
| 600 | 'key' => '(string)', |
||
| 601 | 'value' => '(string|false|float|int|array|object)', |
||
| 602 | 'previous_value' => '(string)', |
||
| 603 | 'operation' => '(string)', |
||
| 604 | ); |
||
| 605 | $return[$key] = (object) $this->cast_and_filter( |
||
| 606 | $value, |
||
| 607 | /** This filter is documented in class.json-api-endpoints.php */ |
||
| 608 | apply_filters( 'wpcom_json_api_attachment_cast_and_filter', $docs ), |
||
| 609 | false, |
||
| 610 | $for_output |
||
| 611 | ); |
||
| 612 | break; |
||
| 613 | case 'plugin' : |
||
| 614 | $docs = array( |
||
| 615 | 'id' => '(safehtml) The plugin\'s ID', |
||
| 616 | 'slug' => '(safehtml) The plugin\'s Slug', |
||
| 617 | 'active' => '(boolean) The plugin status.', |
||
| 618 | 'update' => '(object) The plugin update info.', |
||
| 619 | 'name' => '(safehtml) The name of the plugin.', |
||
| 620 | 'plugin_url' => '(url) Link to the plugin\'s web site.', |
||
| 621 | 'version' => '(safehtml) The plugin version number.', |
||
| 622 | 'description' => '(safehtml) Description of what the plugin does and/or notes from the author', |
||
| 623 | 'author' => '(safehtml) The plugin author\'s name', |
||
| 624 | 'author_url' => '(url) The plugin author web site address', |
||
| 625 | 'network' => '(boolean) Whether the plugin can only be activated network wide.', |
||
| 626 | 'autoupdate' => '(boolean) Whether the plugin is auto updated', |
||
| 627 | 'log' => '(array:safehtml) An array of update log strings.', |
||
| 628 | 'action_links' => '(array) An array of action links that the plugin uses.', |
||
| 629 | ); |
||
| 630 | $return[$key] = (object) $this->cast_and_filter( |
||
| 631 | $value, |
||
| 632 | /** |
||
| 633 | * Filter the documentation returned for a plugin. |
||
| 634 | * |
||
| 635 | * @module json-api |
||
| 636 | * |
||
| 637 | * @since 3.1.0 |
||
| 638 | * |
||
| 639 | * @param array $docs Array of documentation about a plugin. |
||
| 640 | */ |
||
| 641 | apply_filters( 'wpcom_json_api_plugin_cast_and_filter', $docs ), |
||
| 642 | false, |
||
| 643 | $for_output |
||
| 644 | ); |
||
| 645 | break; |
||
| 646 | case 'jetpackmodule' : |
||
| 647 | $docs = array( |
||
| 648 | 'id' => '(string) The module\'s ID', |
||
| 649 | 'active' => '(boolean) The module\'s status.', |
||
| 650 | 'name' => '(string) The module\'s name.', |
||
| 651 | 'description' => '(safehtml) The module\'s description.', |
||
| 652 | 'sort' => '(int) The module\'s display order.', |
||
| 653 | 'introduced' => '(string) The Jetpack version when the module was introduced.', |
||
| 654 | 'changed' => '(string) The Jetpack version when the module was changed.', |
||
| 655 | 'free' => '(boolean) The module\'s Free or Paid status.', |
||
| 656 | 'module_tags' => '(array) The module\'s tags.' |
||
| 657 | ); |
||
| 658 | $return[$key] = (object) $this->cast_and_filter( |
||
| 659 | $value, |
||
| 660 | /** This filter is documented in class.json-api-endpoints.php */ |
||
| 661 | apply_filters( 'wpcom_json_api_plugin_cast_and_filter', $docs ), |
||
| 662 | false, |
||
| 663 | $for_output |
||
| 664 | ); |
||
| 665 | break; |
||
| 666 | case 'sharing_button' : |
||
| 667 | $docs = array( |
||
| 668 | 'ID' => '(string)', |
||
| 669 | 'name' => '(string)', |
||
| 670 | 'URL' => '(string)', |
||
| 671 | 'icon' => '(string)', |
||
| 672 | 'enabled' => '(bool)', |
||
| 673 | 'visibility' => '(string)', |
||
| 674 | ); |
||
| 675 | $return[$key] = (array) $this->cast_and_filter( $value, $docs, false, $for_output ); |
||
| 676 | break; |
||
| 677 | case 'sharing_button_service': |
||
| 678 | $docs = array( |
||
| 679 | 'ID' => '(string) The service identifier', |
||
| 680 | 'name' => '(string) The service name', |
||
| 681 | 'class_name' => '(string) Class name for custom style sharing button elements', |
||
| 682 | 'genericon' => '(string) The Genericon unicode character for the custom style sharing button icon', |
||
| 683 | 'preview_smart' => '(string) An HTML snippet of a rendered sharing button smart preview', |
||
| 684 | 'preview_smart_js' => '(string) An HTML snippet of the page-wide initialization scripts used for rendering the sharing button smart preview' |
||
| 685 | ); |
||
| 686 | $return[$key] = (array) $this->cast_and_filter( $value, $docs, false, $for_output ); |
||
| 687 | break; |
||
| 688 | case 'taxonomy': |
||
| 689 | $docs = array( |
||
| 690 | 'name' => '(string) The taxonomy slug', |
||
| 691 | 'label' => '(string) The taxonomy human-readable name', |
||
| 692 | 'labels' => '(object) Mapping of labels for the taxonomy', |
||
| 693 | 'description' => '(string) The taxonomy description', |
||
| 694 | 'hierarchical' => '(bool) Whether the taxonomy is hierarchical', |
||
| 695 | 'public' => '(bool) Whether the taxonomy is public', |
||
| 696 | 'capabilities' => '(object) Mapping of current user capabilities for the taxonomy', |
||
| 697 | ); |
||
| 698 | $return[$key] = (array) $this->cast_and_filter( $value, $docs, false, $for_output ); |
||
| 699 | break; |
||
| 700 | |||
| 701 | default : |
||
| 702 | $method_name = $type['type'] . '_docs'; |
||
| 703 | if ( method_exists( WPCOM_JSON_API_Jetpack_Overrides, $method_name ) ) { |
||
| 704 | $docs = WPCOM_JSON_API_Jetpack_Overrides::$method_name(); |
||
| 705 | } |
||
| 706 | |||
| 707 | if ( ! empty( $docs ) ) { |
||
| 708 | $return[$key] = (object) $this->cast_and_filter( |
||
| 709 | $value, |
||
| 710 | /** This filter is documented in class.json-api-endpoints.php */ |
||
| 711 | apply_filters( 'wpcom_json_api_plugin_cast_and_filter', $docs ), |
||
| 712 | false, |
||
| 713 | $for_output |
||
| 714 | ); |
||
| 715 | } else { |
||
| 716 | trigger_error( "Unknown API casting type {$type['type']}", E_USER_WARNING ); |
||
| 717 | } |
||
| 718 | } |
||
| 719 | } |
||
| 720 | |||
| 721 | function parse_types( $text ) { |
||
| 741 | |||
| 742 | /** |
||
| 743 | * Checks if the endpoint is publicly displayable |
||
| 744 | */ |
||
| 745 | function is_publicly_documentable() { |
||
| 748 | |||
| 749 | /** |
||
| 750 | * Auto generates documentation based on description, method, path, path_labels, and query parameters. |
||
| 751 | * Echoes HTML. |
||
| 752 | */ |
||
| 753 | function document( $show_description = true ) { |
||
| 869 | |||
| 870 | function add_http_build_query_to_php_content_example( $matches ) { |
||
| 877 | |||
| 878 | /** |
||
| 879 | * Recursively generates the <dl>'s to document item descriptions. |
||
| 880 | * Echoes HTML. |
||
| 881 | */ |
||
| 882 | function generate_doc_description( $item ) { |
||
| 900 | |||
| 901 | /** |
||
| 902 | * Auto generates documentation based on description, method, path, path_labels, and query parameters. |
||
| 903 | * Echoes HTML. |
||
| 904 | */ |
||
| 905 | function generate_documentation() { |
||
| 986 | |||
| 987 | function user_can_view_post( $post_id ) { |
||
| 1051 | |||
| 1052 | /** |
||
| 1053 | * Returns author object. |
||
| 1054 | * |
||
| 1055 | * @param $author user ID, user row, WP_User object, comment row, post row |
||
| 1056 | * @param $show_email output the author's email address? |
||
| 1057 | * |
||
| 1058 | * @return (object) |
||
| 1059 | */ |
||
| 1060 | function get_author( $author, $show_email = false ) { |
||
| 1061 | if ( isset( $author->comment_author_email ) && !$author->user_id ) { |
||
| 1062 | $ID = 0; |
||
| 1063 | $login = ''; |
||
| 1064 | $email = $author->comment_author_email; |
||
| 1065 | $name = $author->comment_author; |
||
| 1066 | $first_name = ''; |
||
| 1067 | $last_name = ''; |
||
| 1068 | $URL = $author->comment_author_url; |
||
| 1069 | $avatar_URL = $this->api->get_avatar_url( $author ); |
||
| 1070 | $profile_URL = 'https://en.gravatar.com/' . md5( strtolower( trim( $email ) ) ); |
||
| 1071 | $nice = ''; |
||
| 1072 | $site_id = -1; |
||
| 1073 | |||
| 1074 | // Comment author URLs and Emails are sent through wp_kses() on save, which replaces "&" with "&" |
||
| 1075 | // "&" is the only email/URL character altered by wp_kses() |
||
| 1076 | foreach ( array( 'email', 'URL' ) as $field ) { |
||
| 1077 | $$field = str_replace( '&', '&', $$field ); |
||
| 1078 | } |
||
| 1079 | } else { |
||
| 1080 | if ( isset( $author->user_id ) && $author->user_id ) { |
||
| 1081 | $author = $author->user_id; |
||
| 1082 | } elseif ( isset( $author->user_email ) ) { |
||
| 1083 | $author = $author->ID; |
||
| 1084 | } elseif ( isset( $author->post_author ) ) { |
||
| 1085 | // then $author is a Post Object. |
||
| 1086 | if ( 0 == $author->post_author ) |
||
| 1087 | return null; |
||
| 1088 | /** |
||
| 1089 | * Filter whether the current site is a Jetpack site. |
||
| 1090 | * |
||
| 1091 | * @module json-api |
||
| 1092 | * |
||
| 1093 | * @since 3.3.0 |
||
| 1094 | * |
||
| 1095 | * @param bool false Is the current site a Jetpack site. Default to false. |
||
| 1096 | * @param int get_current_blog_id() Blog ID. |
||
| 1097 | */ |
||
| 1098 | $is_jetpack = true === apply_filters( 'is_jetpack_site', false, get_current_blog_id() ); |
||
| 1099 | $post_id = $author->ID; |
||
| 1100 | if ( $is_jetpack && ( defined( 'IS_WPCOM' ) && IS_WPCOM ) ) { |
||
| 1101 | $ID = get_post_meta( $post_id, '_jetpack_post_author_external_id', true ); |
||
| 1102 | $email = get_post_meta( $post_id, '_jetpack_author_email', true ); |
||
| 1103 | $login = ''; |
||
| 1104 | $name = get_post_meta( $post_id, '_jetpack_author', true ); |
||
| 1105 | $first_name = ''; |
||
| 1106 | $last_name = ''; |
||
| 1107 | $URL = ''; |
||
| 1108 | $nice = ''; |
||
| 1109 | } else { |
||
| 1110 | $author = $author->post_author; |
||
| 1111 | } |
||
| 1112 | } |
||
| 1113 | |||
| 1114 | if ( ! isset( $ID ) ) { |
||
| 1115 | $user = get_user_by( 'id', $author ); |
||
| 1116 | if ( ! $user || is_wp_error( $user ) ) { |
||
| 1117 | trigger_error( 'Unknown user', E_USER_WARNING ); |
||
| 1118 | |||
| 1119 | return null; |
||
| 1120 | } |
||
| 1121 | $ID = $user->ID; |
||
| 1122 | $email = $user->user_email; |
||
| 1123 | $login = $user->user_login; |
||
| 1124 | $name = $user->display_name; |
||
| 1125 | $first_name = $user->first_name; |
||
| 1126 | $last_name = $user->last_name; |
||
| 1127 | $URL = $user->user_url; |
||
| 1128 | $nice = $user->user_nicename; |
||
| 1129 | } |
||
| 1130 | if ( defined( 'IS_WPCOM' ) && IS_WPCOM && ! $is_jetpack ) { |
||
| 1131 | $active_blog = get_active_blog_for_user( $ID ); |
||
| 1132 | $site_id = $active_blog->blog_id; |
||
| 1133 | $profile_URL = "https://en.gravatar.com/{$login}"; |
||
| 1134 | } else { |
||
| 1135 | $profile_URL = 'https://en.gravatar.com/' . md5( strtolower( trim( $email ) ) ); |
||
| 1136 | $site_id = -1; |
||
| 1137 | } |
||
| 1138 | |||
| 1139 | $avatar_URL = $this->api->get_avatar_url( $email ); |
||
| 1140 | } |
||
| 1141 | |||
| 1142 | $email = $show_email ? (string) $email : false; |
||
| 1143 | |||
| 1144 | $author = array( |
||
| 1145 | 'ID' => (int) $ID, |
||
| 1146 | 'login' => (string) $login, |
||
| 1147 | 'email' => $email, // (string|bool) |
||
| 1148 | 'name' => (string) $name, |
||
| 1149 | 'first_name' => (string) $first_name, |
||
| 1150 | 'last_name' => (string) $last_name, |
||
| 1151 | 'nice_name' => (string) $nice, |
||
| 1152 | 'URL' => (string) esc_url_raw( $URL ), |
||
| 1153 | 'avatar_URL' => (string) esc_url_raw( $avatar_URL ), |
||
| 1154 | 'profile_URL' => (string) esc_url_raw( $profile_URL ), |
||
| 1155 | ); |
||
| 1156 | |||
| 1157 | if ($site_id > -1) { |
||
| 1158 | $author['site_ID'] = (int) $site_id; |
||
| 1159 | } |
||
| 1160 | |||
| 1161 | return (object) $author; |
||
| 1162 | } |
||
| 1163 | |||
| 1164 | function get_media_item( $media_id ) { |
||
| 1197 | |||
| 1198 | function get_media_item_v1_1( $media_id, $media_item = null, $file = null ) { |
||
| 1330 | |||
| 1331 | function get_taxonomy( $taxonomy_id, $taxonomy_type, $context ) { |
||
| 1341 | |||
| 1342 | View Code Duplication | function format_taxonomy( $taxonomy, $taxonomy_type, $context ) { |
|
| 1343 | // Permissions |
||
| 1344 | switch ( $context ) { |
||
| 1345 | case 'edit' : |
||
| 1346 | $tax = get_taxonomy( $taxonomy_type ); |
||
| 1347 | if ( !current_user_can( $tax->cap->edit_terms ) ) |
||
| 1348 | return new WP_Error( 'unauthorized', 'User cannot edit taxonomy', 403 ); |
||
| 1349 | break; |
||
| 1350 | case 'display' : |
||
| 1351 | if ( -1 == get_option( 'blog_public' ) && ! current_user_can( 'read' ) ) { |
||
| 1352 | return new WP_Error( 'unauthorized', 'User cannot view taxonomy', 403 ); |
||
| 1353 | } |
||
| 1354 | break; |
||
| 1355 | default : |
||
| 1356 | return new WP_Error( 'invalid_context', 'Invalid API CONTEXT', 400 ); |
||
| 1357 | } |
||
| 1358 | |||
| 1359 | $response = array(); |
||
| 1360 | $response['ID'] = (int) $taxonomy->term_id; |
||
| 1361 | $response['name'] = (string) $taxonomy->name; |
||
| 1362 | $response['slug'] = (string) $taxonomy->slug; |
||
| 1363 | $response['description'] = (string) $taxonomy->description; |
||
| 1364 | $response['post_count'] = (int) $taxonomy->count; |
||
| 1365 | |||
| 1366 | if ( is_taxonomy_hierarchical( $taxonomy_type ) ) { |
||
| 1367 | $response['parent'] = (int) $taxonomy->parent; |
||
| 1368 | } |
||
| 1369 | |||
| 1370 | $response['meta'] = (object) array( |
||
| 1371 | 'links' => (object) array( |
||
| 1372 | 'self' => (string) $this->links->get_taxonomy_link( $this->api->get_blog_id_for_output(), $taxonomy->slug, $taxonomy_type ), |
||
| 1373 | 'help' => (string) $this->links->get_taxonomy_link( $this->api->get_blog_id_for_output(), $taxonomy->slug, $taxonomy_type, 'help' ), |
||
| 1374 | 'site' => (string) $this->links->get_site_link( $this->api->get_blog_id_for_output() ), |
||
| 1375 | ), |
||
| 1376 | ); |
||
| 1377 | |||
| 1378 | return (object) $response; |
||
| 1379 | } |
||
| 1380 | |||
| 1381 | /** |
||
| 1382 | * Returns ISO 8601 formatted datetime: 2011-12-08T01:15:36-08:00 |
||
| 1383 | * |
||
| 1384 | * @param $date_gmt (string) GMT datetime string. |
||
| 1385 | * @param $date (string) Optional. Used to calculate the offset from GMT. |
||
| 1386 | * |
||
| 1387 | * @return string |
||
| 1388 | */ |
||
| 1389 | function format_date( $date_gmt, $date = null ) { |
||
| 1392 | |||
| 1393 | /** |
||
| 1394 | * Parses a date string and returns the local and GMT representations |
||
| 1395 | * of that date & time in 'YYYY-MM-DD HH:MM:SS' format without |
||
| 1396 | * timezones or offsets. If the parsed datetime was not localized to a |
||
| 1397 | * particular timezone or offset we will assume it was given in GMT |
||
| 1398 | * relative to now and will convert it to local time using either the |
||
| 1399 | * timezone set in the options table for the blog or the GMT offset. |
||
| 1400 | * |
||
| 1401 | * @param datetime string |
||
| 1402 | * |
||
| 1403 | * @return array( $local_time_string, $gmt_time_string ) |
||
| 1404 | */ |
||
| 1405 | function parse_date( $date_string ) { |
||
| 1447 | |||
| 1448 | // Load the functions.php file for the current theme to get its post formats, CPTs, etc. |
||
| 1449 | function load_theme_functions() { |
||
| 1521 | |||
| 1522 | function copy_hooks( $from_hook, $to_hook, $base_paths ) { |
||
| 1559 | |||
| 1560 | function get_reflection( $callback ) { |
||
| 1581 | |||
| 1582 | /** |
||
| 1583 | * Check whether a user can view or edit a post type |
||
| 1584 | * @param string $post_type post type to check |
||
| 1585 | * @param string $context 'display' or 'edit' |
||
| 1586 | * @return bool |
||
| 1587 | */ |
||
| 1588 | View Code Duplication | function current_user_can_access_post_type( $post_type, $context='display' ) { |
|
| 1589 | $post_type_object = get_post_type_object( $post_type ); |
||
| 1590 | if ( ! $post_type_object ) { |
||
| 1591 | return false; |
||
| 1592 | } |
||
| 1593 | |||
| 1594 | switch( $context ) { |
||
| 1595 | case 'edit': |
||
| 1596 | return current_user_can( $post_type_object->cap->edit_posts ); |
||
| 1597 | case 'display': |
||
| 1598 | return $post_type_object->public || current_user_can( $post_type_object->cap->read_private_posts ); |
||
| 1599 | default: |
||
| 1600 | return false; |
||
| 1601 | } |
||
| 1602 | } |
||
| 1603 | |||
| 1604 | function is_post_type_allowed( $post_type ) { |
||
| 1631 | |||
| 1632 | /** |
||
| 1633 | * Gets the whitelisted post types that JP should allow access to. |
||
| 1634 | * |
||
| 1635 | * @return array Whitelisted post types. |
||
| 1636 | */ |
||
| 1637 | View Code Duplication | protected function _get_whitelisted_post_types() { |
|
| 1653 | |||
| 1654 | function handle_media_creation_v1_1( $media_files, $media_urls, $media_attrs = array(), $force_parent_id = false ) { |
||
| 1778 | |||
| 1779 | function handle_media_sideload( $url, $parent_post_id = 0, $type = 'any' ) { |
||
| 1821 | |||
| 1822 | /** |
||
| 1823 | * Checks that the mime type of the specified file is among those in a filterable list of mime types. |
||
| 1824 | * |
||
| 1825 | * @param string $file Path to file to get its mime type. |
||
| 1826 | * |
||
| 1827 | * @return bool |
||
| 1828 | */ |
||
| 1829 | View Code Duplication | protected function is_file_supported_for_sideloading( $file ) { |
|
| 1877 | |||
| 1878 | function allow_video_uploads( $mimes ) { |
||
| 1938 | |||
| 1939 | function is_current_site_multi_user() { |
||
| 1951 | |||
| 1952 | function allows_cross_origin_requests() { |
||
| 1955 | |||
| 1956 | function allows_unauthorized_requests( $origin, $complete_access_origins ) { |
||
| 1959 | |||
| 1960 | function get_platform() { |
||
| 1963 | |||
| 1964 | /** |
||
| 1965 | * Allows the endpoint to perform logic to allow it to decide whether-or-not it should force a |
||
| 1966 | * response from the WPCOM API, or potentially go to the Jetpack blog. |
||
| 1967 | * |
||
| 1968 | * Override this method if you want to do something different. |
||
| 1969 | * |
||
| 1970 | * @param int $blog_id |
||
| 1971 | * @return bool |
||
| 1972 | */ |
||
| 1973 | function force_wpcom_request( $blog_id ) { |
||
| 1976 | |||
| 1977 | /** |
||
| 1978 | * Return endpoint response |
||
| 1979 | * |
||
| 1980 | * @param ... determined by ->$path |
||
| 1981 | * |
||
| 1982 | * @return |
||
| 1983 | * falsy: HTTP 500, no response body |
||
| 1984 | * WP_Error( $error_code, $error_message, $http_status_code ): HTTP $status_code, json_encode( array( 'error' => $error_code, 'message' => $error_message ) ) response body |
||
| 1985 | * $data: HTTP 200, json_encode( $data ) response body |
||
| 1986 | */ |
||
| 1987 | abstract function callback( $path = '' ); |
||
| 1988 | |||
| 1989 | |||
| 1990 | } |
||
| 1991 | |||
| 1992 | require_once( dirname( __FILE__ ) . '/json-endpoints.php' ); |
||
| 1993 |
Loading history...
This check looks for improperly formatted assignments.
Every assignment must have exactly one space before and one space after the equals operator.
To illustrate:
will have no issues, while
will report issues in lines 1 and 2.