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

Retrieves plugin installer pages from the WordPress.org Plugins API.

Description

It is possible for a plugin to override the Plugin API result with three filters. Assume this is for plugins, which can extend on the Plugin Info to offer more choices. This is very powerful and must be used with care when overriding the filters.

The first filter, ‘plugins_api_args’, is for the args and gives the action as the second parameter. The hook for ‘plugins_api_args’ must ensure that an object is returned.

The second filter, ‘plugins_api’, allows a plugin to override the WordPress.org Plugin Installation API entirely. If $action is ‘query_plugins’ or ‘plugin_information’, an object MUST be passed. If $action is ‘hot_tags’ or ‘hot_categories’, an array MUST be passed.

Finally, the third filter, ‘plugins_api_result’, makes it possible to filter the response object or array, depending on the $action type.

Supported arguments per action:

Argument Name	query_plugins	plugin_information	hot_tags	hot_categories
`$slug`	No	Yes	No	No
`$per_page`	Yes	No	No	No
`$page`	Yes	No	No	No
`$number`	No	No	Yes	Yes
`$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
`$installed_plugins`	Yes	No	No	No
`$is_ssl`	Yes	Yes	No	No
`$fields`	Yes	Yes	No	No

Parameters

$action string Required

API action to perform: 'query_plugins', 'plugin_information', 'hot_tags' or 'hot_categories'.

$args array|object Optional

Array or object of arguments to serialize for the Plugin Info API.

slugstring
The plugin slug.
per_pageint
Number of plugins per page. Default 24.
pageint
Number of current page. Default 1.
numberint
Number of tags or categories to be queried.
searchstring
A search term.
tagstring
Tag to filter plugins.
authorstring
Username of an plugin author to filter plugins.
userstring
Username to query for their favorites.
browsestring
Browse view: 'popular', 'new', 'beta', 'recommended'.
localestring
Locale to provide context-sensitive results. Default is the value of get_locale() .
installed_pluginsstring
Installed plugins to provide context-sensitive results.
is_sslbool
Whether links should be returned with https or not. Default false.

fieldsarray

Array of fields which should or should not be returned.

short_descriptionbool
Whether to return the plugin short description. Default true.
descriptionbool
Whether to return the plugin full description. Default false.
sectionsbool
Whether to return the plugin readme sections: description, installation, FAQ, screenshots, other notes, and changelog. Default false.
testedbool
Whether to return the 'Compatible up to' value. Default true.
requiresbool
Whether to return the required WordPress version. Default true.
requires_phpbool
Whether to return the required PHP version. Default true.
ratingbool
Whether to return the rating in percent and total number of ratings.
Default true.
ratingsbool
Whether to return the number of rating for each star (1-5). Default true.
downloadedbool
Whether to return the download count. Default true.
downloadlinkbool
Whether to return the download link for the package. Default true.
last_updatedbool
Whether to return the date of the last update. Default true.
addedbool
Whether to return the date when the plugin was added to the wordpress.org repository. Default true.
tagsbool
Whether to return the assigned tags. Default true.
compatibilitybool
Whether to return the WordPress compatibility list. Default true.
homepagebool
Whether to return the plugin homepage link. Default true.
versionsbool
Whether to return the list of all available versions. Default false.
donate_linkbool
Whether to return the donation link. Default true.
reviewsbool
Whether to return the plugin reviews. Default false.
bannersbool
Whether to return the banner images links. Default false.
iconsbool
Whether to return the icon links. Default false.
active_installsbool
Whether to return the number of active installations. Default false.
groupbool
Whether to return the assigned group. Default false.
contributorsbool
Whether to return the list of contributors. 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 values depending on the value of $action.

Source

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

function plugins_api( $action, $args = array() ) {
	// Include an unmodified $wp_version.
	require ABSPATH . WPINC . '/version.php';

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

	if ( 'query_plugins' === $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 the WordPress.org Plugin Installation API arguments.
	 *
	 * Important: An object MUST be returned to this filter.
	 *
	 * @since 2.7.0
	 *
	 * @param object $args   Plugin API arguments.
	 * @param string $action The type of information being requested from the Plugin Installation API.
	 */
	$args = apply_filters( 'plugins_api_args', $args, $action );

	/**
	 * Filters the response for the current WordPress.org Plugin Installation API request.
	 *
	 * Returning a non-false value will effectively short-circuit the WordPress.org API request.
	 *
	 * If `$action` is 'query_plugins' or 'plugin_information', an object MUST be passed.
	 * If `$action` is 'hot_tags' or 'hot_categories', an array should be passed.
	 *
	 * @since 2.7.0
	 *
	 * @param false|object|array $result The result object or array. Default false.
	 * @param string             $action The type of information being requested from the Plugin Installation API.
	 * @param object             $args   Plugin API arguments.
	 */
	$res = apply_filters( 'plugins_api', false, $action, $args );

	if ( false === $res ) {

		$url = 'http://api.wordpress.org/plugins/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(
			'timeout'    => 15,
			'user-agent' => 'WordPress/' . $wp_version . '; ' . home_url( '/' ),
		);
		$request   = wp_remote_get( $url, $http_args );

		if ( $ssl && is_wp_error( $request ) ) {
			if ( ! wp_is_json_request() ) {
				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(
				'plugins_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(
					'plugins_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( 'plugins_api_failed', $res->error );
			}
		}
	} elseif ( ! is_wp_error( $res ) ) {
		$res->external = true;
	}

	/**
	 * Filters the Plugin Installation API response results.
	 *
	 * @since 2.7.0
	 *
	 * @param object|WP_Error $res    Response object or WP_Error.
	 * @param string          $action The type of information being requested from the Plugin Installation API.
	 * @param object          $args   Plugin API arguments.
	 */
	return apply_filters( 'plugins_api_result', $res, $action, $args );
}

Hooks

apply_filters( 'plugins_api', false|object|array $result, string $action, object $args ): Filters the response for the current WordPress.org Plugin Installation API request.

apply_filters( 'plugins_api_args', object $args, string $action ): Filters the WordPress.org Plugin Installation API arguments.

apply_filters( 'plugins_api_result', object|WP_Error $res, string $action, object $args ): Filters the Plugin Installation API response results.

Uses

Uses	Description
wp_is_json_request() wp-includes/load.php	Checks whether current request is a JSON request, or is expecting a JSON response.
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_REST_Block_Directory_Controller::get_items() wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php	Search and retrieve blocks metadata
WP_REST_Plugins_Controller::create_item() wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php	Uploads a plugin and optionally activates it.
wp_ajax_install_plugin() wp-admin/includes/ajax-actions.php	Ajax handler for installing a plugin.
install_popular_tags() wp-admin/includes/plugin-install.php	Retrieves popular WordPress plugin tags.
install_plugin_information() wp-admin/includes/plugin-install.php	Displays plugin information in dialog box form.
WP_Plugin_Install_List_Table::prepare_items() wp-admin/includes/class-wp-plugin-install-list-table.php

Changelog

Version	Description
2.7.0	Introduced.

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

Docs

Docs4dev

Title here