themes_api( $action,  $args = array() )

Retrieves theme installer pages from the ClassicPress.net 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 ClassicPress.net 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

Source

File: wp-admin/includes/theme.php

function themes_api( $action, $args = array() ) {

	if ( is_array( $args ) ) {
		$args = (object) $args;
	}

	if ( ! isset( $args->per_page ) ) {
		$args->per_page = 24;
	}

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

	/**
	 * Filters arguments used to query for installer pages from the ClassicPress.net Themes API.
	 *
	 * Important: An object MUST be returned to this filter.
	 *
	 * @since WP-2.8.0
	 *
	 * @param object $args   Arguments used to query for installer pages from the ClassicPress.net 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 ClassicPress.net Themes API.
	 *
	 * Passing a non-false value will effectively short-circuit the ClassicPress.net 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 WP-2.8.0
	 *
	 * @param false|object|array $override Whether to override the ClassicPress.net 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 ) {
		// include an unmodified $wp_version
		include( ABSPATH . WPINC . '/version.php' );

		$url = 'https://api.wordpress.org/themes/info/1.0/';

		$http_args = array(
			'user-agent' => classicpress_user_agent(),
			'body' => array(
				'action' => $action,
				'request' => serialize( $args )
			)
		);
		$request = wp_remote_post( $url, $http_args );

		if ( 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 ClassicPress.net or this server&#8217;s configuration. If you continue to have problems, please try the <a href="%s">support forums</a>.' ),
						__( 'https://forums.classicpress.net/c/support' )
					) . ' ' . __( '(ClassicPress could not establish a secure connection to ClassicPress.net. Please contact your server administrator.)' ),
					headers_sent() || WP_DEBUG ? E_USER_WARNING : E_USER_NOTICE
				);
			}

			// Retry request
			$request = wp_remote_post( $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 ClassicPress.net or this server&#8217;s configuration. If you continue to have problems, please try the <a href="%s">support forums</a>.' ),
					__( 'https://forums.classicpress.net/c/support' )
				),
				$request->get_error_message()
			);
		} else {
			$res = maybe_unserialize( wp_remote_retrieve_body( $request ) );
			if ( ! is_object( $res ) && ! is_array( $res ) ) {
				$res = new WP_Error( 'themes_api_failed',
					sprintf(
						/* translators: %s: support forums URL */
						__( 'An unexpected error occurred. Something may be wrong with ClassicPress.net or this server&#8217;s configuration. If you continue to have problems, please try the <a href="%s">support forums</a>.' ),
						__( 'https://forums.classicpress.net/c/support' )
					),
					wp_remote_retrieve_body( $request )
				);
			}
		}
	}

	/**
	 * Filters the returned ClassicPress.net Themes API response.
	 *
	 * @since WP-2.8.0
	 *
	 * @param array|object|WP_Error $res    ClassicPress.net 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 ClassicPress.net Themes API.
	 */
	return apply_filters( 'themes_api_result', $res, $action, $args );
}