themes_api( string $action, array|object $args = array() ): object|array|WP_Error

Retrieves theme installer pages from the WordPress.org Themes API.

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

$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.

slugstring
The theme slug.
per_pageint
Number of themes per page. Default 24.
pageint
Number of current page. Default 1.
numberint
Number of tags to be queried.
searchstring
A search term.
tagstring
Tag to filter themes.
authorstring
Username of an author to filter themes.
userstring
Username to query for their favorites.
browsestring
Browse view: 'featured', 'popular', 'updated', 'favorites'.
localestring
Locale to provide context-sensitive results. Default is the value of get_locale() .

fieldsarray

Array of fields which should or should not be returned.

descriptionbool
Whether to return the theme full description. Default false.
sectionsbool
Whether to return the theme readme sections: description, installation, FAQ, screenshots, other notes, and changelog. Default false.
ratingbool
Whether to return the rating in percent and total number of ratings.
Default false.
ratingsbool
Whether to return the number of rating for each star (1-5). Default false.
downloadedbool
Whether to return the download count. Default false.
downloadlinkbool
Whether to return the download link for the package. Default false.
last_updatedbool
Whether to return the date of the last update. Default false.
tagsbool
Whether to return the assigned tags. Default false.
homepagebool
Whether to return the theme homepage link. Default false.
screenshotsbool
Whether to return the screenshots. Default false.
screenshot_countint
Number of screenshots to return. Default 1.
screenshot_urlbool
Whether to return the URL of the first screenshot. Default false.
photon_screenshotsbool
Whether to return the screenshots via Photon. Default false.
templatebool
Whether to return the slug of the parent theme. Default false.
parentbool
Whether to return the slug, name and homepage of the parent theme. Default false.
versionsbool
Whether to return the list of all available versions. Default false.
theme_urlbool
Whether to return theme's URL. Default false.
extended_authorbool
Whether to return nicename or nicename and display name. Default false.

Default: array()

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

File: wp-admin/includes/theme.php. View all references

function themes_api( $action, $args = array() ) {
	// Include an unmodified $wp_version.
	require 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.
	 *
	 * Returning 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 = 'http://api.wordpress.org/themes/info/1.2/';
		$url = add_query_arg(
			array(
				'action'  => $action,
				'request' => $args,
			),
			$url
		);

		$http_url = $url;
		$ssl      = wp_http_supports( array( 'ssl' ) );
		if ( $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&#8217;s configuration. If you continue to have problems, please try the <a href="%s">support forums</a>.' ),
						__( 'https://wordpress.org/support/forums/' )
					) . ' ' . __( '(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&#8217;s configuration. If you continue to have problems, please try the <a href="%s">support forums</a>.' ),
					__( 'https://wordpress.org/support/forums/' )
				),
				$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&#8217;s configuration. If you continue to have problems, please try the <a href="%s">support forums</a>.' ),
						__( 'https://wordpress.org/support/forums/' )
					),
					wp_remote_retrieve_body( $request )
				);
			}

			if ( isset( $res->error ) ) {
				$res = new WP_Error( 'themes_api_failed', $res->error );
			}
		}

		if ( ! is_wp_error( $res ) ) {
			// 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|stdClass|WP_Error $res    WordPress.org Themes API response.
	 * @param string                  $action Requested action. Likely values are 'theme_information',
	 *                                        'feature_list', or 'query_themes'.
	 * @param stdClass                $args   Arguments used to query for installer pages from the WordPress.org Themes API.
	 */
	return apply_filters( 'themes_api_result', $res, $action, $args );
}

Hooks

apply_filters( 'themes_api', false|object|array $override, string $action, object $args ): Filters whether to override the WordPress.org Themes API.

apply_filters( 'themes_api_args', object $args, string $action ): Filters arguments used to query for installer pages from the WordPress.org Themes API.

apply_filters( 'themes_api_result', array|stdClass|WP_Error $res, string $action, stdClass $args ): Filters the returned WordPress.org Themes API response.

Uses

Uses	Description
wp_doing_ajax() wp-includes/load.php	Determines whether the current request is a WordPress Ajax request.
get_user_locale() wp-includes/l10n.php	Retrieves the locale of a user.
set_url_scheme() wp-includes/link-template.php	Sets the scheme for a URL.
wp_http_supports() wp-includes/http.php	Determines if there is an HTTP Transport that can process this request.
wp_remote_get() wp-includes/http.php	Performs an HTTP request using the GET method and returns its response.
wp_remote_retrieve_body() wp-includes/http.php	Retrieve only the body from the raw response.
__() wp-includes/l10n.php	Retrieves the translation of $text.
add_query_arg() wp-includes/functions.php	Retrieves a modified URL query string.
home_url() wp-includes/link-template.php	Retrieves the URL for the current site where the front end is accessible.
apply_filters() wp-includes/plugin.php	Calls the callback functions that have been added to a filter hook.
is_wp_error() wp-includes/load.php	Checks whether the given variable is a WordPress Error.
WP_Error::__construct() wp-includes/class-wp-error.php	Initializes the error.

Used By

Used By	Description
WP_Customize_Manager::handle_load_themes_request() wp-includes/class-wp-customize-manager.php	Loads themes into the theme browsing/installation UI.
wp_ajax_install_theme() wp-admin/includes/ajax-actions.php	Ajax handler for installing a theme.
Theme_Upgrader::check_parent_theme_filter() wp-admin/includes/class-theme-upgrader.php	Check if a child theme is being installed and we need to install its parent.
get_theme_feature_list() wp-admin/includes/theme.php	Retrieves list of WordPress theme features (aka theme tags).
install_themes_feature_list() wp-admin/includes/theme-install.php	Retrieves the list of WordPress theme features (aka theme tags).
install_theme_information() wp-admin/includes/theme-install.php	Displays theme information in dialog box form.
WP_Theme_Install_List_Table::prepare_items() wp-admin/includes/class-wp-theme-install-list-table.php
wp_ajax_query_themes() wp-admin/includes/ajax-actions.php	Ajax handler for getting themes from themes_api() .

Changelog

Version	Description
2.8.0	Introduced.

© 2003–2022 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/themes_api

Docs

Docs4dev

Title here