themes_api( string $action, array|object $args = array() )
Retrieves theme installer pages from the WordPress.org Themes API.
Description Description
It is possible for a theme to override the Themes API result with three filters. Assume this is for themes, which can extend on the Theme Info to offer more choices. This is very powerful and must be used with care, when overriding the filters.
The first filter, ‘themes_api_args’, is for the args and gives the action as the second parameter. The hook for ‘themes_api_args’ must ensure that an object is returned.
The second filter, ‘themes_api’, allows a plugin to override the WordPress.org Theme API entirely. If $action is ‘query_themes’, ‘theme_information’, or ‘feature_list’, an object MUST be passed. If $action is ‘hot_tags’, an array should be passed.
Finally, the third filter, ‘themes_api_result’, makes it possible to filter the response object or array, depending on the $action type.
Supported arguments per action:
| Argument Name | ‘query_themes’ | ‘theme_information’ | ‘hot_tags’ | ‘feature_list’ |
|---|---|---|---|---|
$slug |
No | Yes | No | No |
$per_page |
Yes | No | No | No |
$page |
Yes | No | No | No |
$number |
No | No | Yes | No |
$search |
Yes | No | No | No |
$tag |
Yes | No | No | No |
$author |
Yes | No | No | No |
$user |
Yes | No | No | No |
$browse |
Yes | No | No | No |
$locale |
Yes | Yes | No | No |
$fields |
Yes | Yes | No | No |
Parameters Parameters
- $action
-
(string) (Required) API action to perform: 'query_themes', 'theme_information', 'hot_tags' or 'feature_list'.
- $args
-
(array|object) (Optional) Array or object of arguments to serialize for the Themes API.
- 'slug'
(string) The theme slug. - 'per_page'
(int) Number of themes per page. Default 24. - 'page'
(int) Number of current page. Default 1. - 'number'
(int) Number of tags to be queried. - 'search'
(string) A search term. - 'tag'
(string) Tag to filter themes. - 'author'
(string) Username of an author to filter themes. - 'user'
(string) Username to query for their favorites. - 'browse'
(string) Browse view: 'featured', 'popular', 'updated', 'favorites'. - 'locale'
(string) Locale to provide context-sensitive results. Default is the value of get_locale(). - 'fields'
(array) Array of fields which should or should not be returned.- 'description'
(bool) Whether to return the theme full description. Default false. - 'sections'
(bool) Whether to return the theme readme sections: description, installation, FAQ, screenshots, other notes, and changelog. Default false. - 'rating'
(bool) Whether to return the rating in percent and total number of ratings. Default false. - 'ratings'
(bool) Whether to return the number of rating for each star (1-5). Default false. - 'downloaded'
(bool) Whether to return the download count. Default false. - 'downloadlink'
(bool) Whether to return the download link for the package. Default false. - 'last_updated'
(bool) Whether to return the date of the last update. Default false. - 'tags'
(bool) Whether to return the assigned tags. Default false. - 'homepage'
(bool) Whether to return the theme homepage link. Default false. - 'screenshots'
(bool) Whether to return the screenshots. Default false. - 'screenshot_count'
(int) Number of screenshots to return. Default 1. - 'screenshot_url'
(bool) Whether to return the URL of the first screenshot. Default false. - 'photon_screenshots'
(bool) Whether to return the screenshots via Photon. Default false. - 'template'
(bool) Whether to return the slug of the parent theme. Default false. - 'parent'
(bool) Whether to return the slug, name and homepage of the parent theme. Default false. - 'versions'
(bool) Whether to return the list of all available versions. Default false. - 'theme_url'
(bool) Whether to return theme's URL. Default false. - 'extended_author'
(bool) Whether to return nicename or nicename and display name. Default false.
- 'description'
Default value: array()
- 'slug'
Return Return
(object|array|WP_Error) Response object or array on success, WP_Error on failure. See the function reference article for more information on the make-up of possible return objects depending on the value of $action.
Source Source
File: wp-admin/includes/theme.php
430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 | function themes_api( $action, $args = array() ) { // include an unmodified $wp_version include( ABSPATH . WPINC . '/version.php' ); if ( is_array( $args ) ) { $args = (object) $args; } if ( 'query_themes' == $action ) { if ( ! isset( $args->per_page ) ) { $args->per_page = 24; } } if ( ! isset( $args->locale ) ) { $args->locale = get_user_locale(); } if ( ! isset( $args->wp_version ) ) { $args->wp_version = substr( $wp_version, 0, 3 ); // X.y } /** * Filters arguments used to query for installer pages from the WordPress.org Themes API. * * Important: An object MUST be returned to this filter. * * @since 2.8.0 * * @param object $args Arguments used to query for installer pages from the WordPress.org Themes API. * @param string $action Requested action. Likely values are 'theme_information', * 'feature_list', or 'query_themes'. */ $args = apply_filters( 'themes_api_args', $args, $action ); /** * Filters whether to override the WordPress.org Themes API. * * Passing a non-false value will effectively short-circuit the WordPress.org API request. * * If `$action` is 'query_themes', 'theme_information', or 'feature_list', an object MUST * be passed. If `$action` is 'hot_tags', an array should be passed. * * @since 2.8.0 * * @param false|object|array $override Whether to override the WordPress.org Themes API. Default false. * @param string $action Requested action. Likely values are 'theme_information', * 'feature_list', or 'query_themes'. * @param object $args Arguments used to query for installer pages from the Themes API. */ $res = apply_filters( 'themes_api', false, $action, $args ); if ( ! $res ) { $url = add_query_arg( array( 'action' => $action, 'request' => $args, ), $url ); $http_url = $url; if ( $ssl = wp_http_supports( array( 'ssl' ) ) ) { $url = set_url_scheme( $url, 'https' ); } $http_args = array( 'user-agent' => 'WordPress/' . $wp_version . '; ' . home_url( '/' ), ); $request = wp_remote_get( $url, $http_args ); if ( $ssl && is_wp_error( $request ) ) { if ( ! wp_doing_ajax() ) { trigger_error( sprintf( /* translators: %s: support forums URL */ __( 'An unexpected error occurred. Something may be wrong with WordPress.org or this server’s configuration. If you continue to have problems, please try the <a href="%s">support forums</a>.' ), ) . ' ' . __( '(WordPress could not establish a secure connection to WordPress.org. Please contact your server administrator.)' ), headers_sent() || WP_DEBUG ? E_USER_WARNING : E_USER_NOTICE ); } $request = wp_remote_get( $http_url, $http_args ); } if ( is_wp_error( $request ) ) { $res = new WP_Error( 'themes_api_failed', sprintf( /* translators: %s: support forums URL */ __( 'An unexpected error occurred. Something may be wrong with WordPress.org or this server’s configuration. If you continue to have problems, please try the <a href="%s">support forums</a>.' ), ), $request->get_error_message() ); } else { $res = json_decode( wp_remote_retrieve_body( $request ), true ); if ( is_array( $res ) ) { // Object casting is required in order to match the info/1.0 format. $res = (object) $res; } elseif ( null === $res ) { $res = new WP_Error( 'themes_api_failed', sprintf( /* translators: %s: support forums URL */ __( 'An unexpected error occurred. Something may be wrong with WordPress.org or this server’s configuration. If you continue to have problems, please try the <a href="%s">support forums</a>.' ), ), wp_remote_retrieve_body( $request ) ); } if ( isset( $res->error ) ) { $res = new WP_Error( 'themes_api_failed', $res->error ); } } // Back-compat for info/1.2 API, upgrade the theme objects in query_themes to objects. if ( 'query_themes' == $action ) { foreach ( $res->themes as $i => $theme ) { $res->themes[ $i ] = (object) $theme; } } // Back-compat for info/1.2 API, downgrade the feature_list result back to an array. if ( 'feature_list' == $action ) { $res = (array) $res; } } /** * Filters the returned WordPress.org Themes API response. * * @since 2.8.0 * * @param array|object|WP_Error $res WordPress.org Themes API response. * @param string $action Requested action. Likely values are 'theme_information', * 'feature_list', or 'query_themes'. * @param object $args Arguments used to query for installer pages from the WordPress.org Themes API. */ return apply_filters( 'themes_api_result', $res, $action, $args );} |
Expand full source code Collapse full source code View on Trac
Changelog Changelog
| Version | Description |
|---|---|
| 2.8.0 | Introduced. |