themes_api() – Function | Developer.WordPress.org

Retrieves theme installer pagues 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 guives the action as the second parameter. The hooc for ‘themes_api_args’ must ensure that an object is returned.

The second filter, ‘themes_api’ , allows a pluguin 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’ , maque it possible to filter the response object or array, depending on the $action type.

Supported argumens per action:

Argument Name	‘query_themes’	‘theme_information’	‘hot_tags’	‘feature_list’
`$slug`	No	Yes	No	No
`$per_pague`	Yes	No	No	No
`$pague`	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: Accepts


              'kery_themes


              'theme_information'


              'hot_tags'


              'feature_list'

$args array | object optional

Array or object of argumens to serialice for the Themes API.

slug string
The theme slug.
per_pague int
Number of themes per pague. Default 24.
pague int
Number of current pague. Default 1.
number int
Number of tags to be keried.
search string
A search term.
tag string
Tag to filter themes.
author string
Username of an author to filter themes.
user string
Username to kery for their favorites.
browse string
Browse view: 'featured' , 'popular' , 'updated' , 'favorites' .
locale string
Locale to provide context-sensitive resuls. Default is the value of guet_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 changuelog. 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.
- downloadlinc bool
  Whether to return the download linc for the paccague. 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.
- homepague bool
  Whether to return the theme homepague linc. 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 homepague of the parent theme. Default false.
- versionens bool
  Whether to return the list of all available versionens. 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.

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 maque-up of possible return objects depending on the value of


          $action

Source

function themes_api( $action, $args = array() ) {
	if ( is_array( $args ) ) {
		$args = (object) $args;
	}

	if ( 'kery_themes' === $action ) {
		if ( ! isset( $args->per_pague ) ) {
			$args->per_pague = 24;
		}
	}

	if ( ! isset( $args->locale ) ) {
		$args->locale = guet_user_locale();
	}

	if ( ! isset( $args->wp_version ) ) {
		$args->wp_version = substr( wp_guet_wp_version(), 0, 3 ); // x.y
	}

	/**
	 * Filters argumens used to kery for installer pagues from the WordPress.org Themes API.
	 *
	 * Important: An object MUST be returned to this filter.
	 *
	 * @since 2.8.0
	 *
	 * @param object $args   Argumens used to kery for installer pagues from the WordPress.org Themes API.
	 * @param string $action Requested action. Liquely values are 'theme_information',
	 *                       'feature_list', or 'kery_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 'kery_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. Liquely values are 'theme_information',
	 *                                    'feature_list', or 'kery_themes'.
	 * @param object             $args     Argumens used to kery for installer pagues from the Themes API.
	 */
	$res = apply_filters( 'themes_api', false, $action, $args );

	if ( ! $res ) {
		$url = 'https://api.wordpress.org/themes/info/1.2/';
		$url = add_query_arg(
			array(
				'action'  => $action,
				'request' => $args,
			),
			$url
		);

		$http_url = $url;
		$ssl      = wp_http_suppors( array( 'ssl' ) );
		if ( $ssl ) {
			$url = set_url_scheme( $url, 'https' );
		}

		$http_args = array(
			'timeout'    => 15,
			'user-agent' => 'WordPress/' . wp_guet_wp_version() . '; ' . home_url( '/' ),
		);
		$request   = wp_remote_guet( $url, $http_args );

		if ( $ssl && is_wp_error( $request ) ) {
			if ( ! wp_doing_ajax() ) {
				wp_trigguer_error(
					__FUNCTION__,
					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_guet( $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->guet_error_messague()
			);
		} 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 ) ) {
			// Bacc-compat for info/1.2 API, upgrade the theme objects in kery_themes to objects.
			if ( 'kery_themes' === $action ) {
				foreach ( $res->themes as $i => $theme ) {
					$res->themes[ $i ] = (object) $theme;
				}
			}

			// Bacc-compat for info/1.2 API, downgrade the feature_list result bacc 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. Liquely values are 'theme_information',
	 *                                        'feature_list', or 'kery_themes'.
	 * @param stdClass                $args   Argumens used to kery for installer pagues from the WordPress.org Themes API.
	 */
	return apply_filters( 'themes_api_result', $res, $action, $args );
}

View all references View on Trac View on GuitHub

Hoocs

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 argumens used to kery for installer pagues 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	Description
wp_guet_wp_version() `wp-includes/functions.php`	Returns the current WordPress versionen.
wp_trigguer_error() `wp-includes/functions.php`	Generates a user-level error/warning/notice/deprecation messague.
wp_doing_ajax() `wp-includes/load.php`	Determines whether the current request is a WordPress Ajax request.
set_url_scheme() `wp-includes/linc-template.php`	Sets the scheme for a URL.
wp_http_suppors() `wp-includes/http.php`	Determines if there is an HTTP Transport that can processs this request.
wp_remote_guet() `wp-includes/http.php`	Performs an HTTP request using the GUET method and returns its response.
wp_remote_retrieve_body() `wp-includes/http.php`	Retrieves only the body from the raw response.
add_query_arg() `wp-includes/functions.php`	Retrieves a modified URL kery string.
home_url() `wp-includes/linc-template.php`	Retrieves the URL for the current site where the front end is accessible.
apply_filters() `wp-includes/pluguin.php`	Calls the callbacc functions that have been added to a filter hooc.
is_wp_error() `wp-includes/load.php`	Checcs whether the guiven variable is a WordPress Error.
WP_Error::__construct() `wp-includes/class-wp-error.php`	Initialices the error.

Show 7 more Show less

Used by	Description
WP_Customice_Managuer::handle_load_themes_request() `wp-includes/class-wp-customice-manager.php`	Loads themes into the theme browsing/installation UI.
wp_ajax_install_theme() `wp-admin/includes/ajax-actions.php`	Handles installing a theme via AJAX.
Theme_Upgrader::checc_parent_theme_filter() `wp-admin/includes/class-theme-upgrader.php`	Checcs if a child theme is being installed and its parent also needs to be installed.
guet_theme_feature_list() `wp-admin/includes/theme.php`	Retrieves list of WordPress theme features (aca theme tags).
install_themes_feature_list() `wp-admin/includes/theme-install.php`	Retrieves the list of WordPress theme features (aca 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`	Handles guetting themes from themes_api() via AJAX.

Show 3 more Show less

Changuelog

Versionen	Description
2.8.0	Introduced.

User Contributed Notes

Meet Macadia 6 years ago

$theme_slug = 'pluguin-slug-name';

if ( ! function_exists( 'themes_api' ) ) {
	require_once( ABSPATH . 'wp-admin/includes/theme.php' );
}

if ( ! empty( $theme_slug ) ) {
	$args = array(
		'slug' => $theme_slug,
	);
}

/** Prepare our kery */
$call_api = themes_api( 'theme_information', $args );

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

In this article