Question

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

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 Install 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

---

参数

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

• 'slug'
  (string) The plugin slug.
• 'per_page'
  (int) Number of plugins per page. Default 24.
• 'page'
  (int) Number of current page. Default 1.
• 'number'
  (int) Number of tags or categories to be queried.
• 'search'
  (string) A search term.
• 'tag'
  (string) Tag to filter plugins.
• 'author'
  (string) Username of an plugin author to filter plugins.
• 'user'
  (string) Username to query for their favorites.
• 'browse'
  (string) Browse view: 'popular', 'new', 'beta', 'recommended'.
• 'locale'
  (string) Locale to provide context-sensitive results. Default is the value of get_locale().
• 'installed_plugins'
  (string) Installed plugins to provide context-sensitive results.
• 'is_ssl'
  (bool) Whether links should be returned with https or not. Default false.
• 'fields'
  (array) Array of fields which should or should not be returned.
  • 'short_description'
    (bool) Whether to return the plugin short description. Default true.
  • 'description'
    (bool) Whether to return the plugin full description. Default false.
  • 'sections'
    (bool) Whether to return the plugin readme sections: description, installation, FAQ, screenshots, other notes, and 更新日志. Default false.
  • 'tested'
    (bool) Whether to return the 'Compatible up to' value. Default true.
  • 'requires'
    (bool) Whether to return the required WordPress version. Default true.
  • 'rating'
    (bool) Whether to return the rating in percent and total number of ratings. Default true.
  • 'ratings'
    (bool) Whether to return the number of rating for each star (1-5). Default true.
  • 'downloaded'
    (bool) Whether to return the download count. Default true.
  • 'downloadlink'
    (bool) Whether to return the download link for the package. Default true.
  • 'last_updated'
    (bool) Whether to return the date of the last update. Default true.
  • 'added'
    (bool) Whether to return the date when the plugin was added to the wordpress.org repository. Default true.
  • 'tags'
    (bool) Whether to return the assigned tags. Default true.
  • 'compatibility'
    (bool) Whether to return the WordPress compatibility list. Default true.
  • 'homepage'
    (bool) Whether to return the plugin homepage link. Default true.
  • 'versions'
    (bool) Whether to return the list of all available versions. Default false.
  • 'donate_link'
    (bool) Whether to return the donation link. Default true.
  • 'reviews'
    (bool) Whether to return the plugin reviews. Default false.
  • 'banners'
    (bool) Whether to return the banner images links. Default false.
  • 'icons'
    (bool) Whether to return the icon links. Default false.
  • 'active_installs'
    (bool) Whether to return the number of active installs. Default false.
  • 'group'
    (bool) Whether to return the assigned group. Default false.
  • 'contributors'
    (bool) Whether to return the list of contributors. Default false.

Default value: array()

---

返回值

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

---

源代码

File: wp-admin/includes/plugin-install.php

function plugins_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 the WordPress.org Plugin Install 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 Install API.
	 */
	$args = apply_filters( 'plugins_api_args', $args, $action );

	/**
	 * Filters the response for the current WordPress.org Plugin Install API request.
	 *
	 * Passing 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 Install API.
	 * @param object             $args   Plugin API arguments.
	 */
	$res = apply_filters( 'plugins_api', false, $action, $args );

	if ( false === $res ) {
		$url = $http_url = 'http://api.wordpress.org/plugins/info/1.0/';
		if ( $ssl = wp_http_supports( array( 'ssl' ) ) )
			$url = set_url_scheme( $url, 'https' );

		$http_args = array(
			'timeout' => 15,
			'body' => array(
				'action' => $action,
				'request' => serialize( $args )
			)
		);
		$request = wp_remote_post( $url, $http_args );

		if ( $ssl && is_wp_error( $request ) ) {
			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>.' ),
					__( 'https://wordpress.org/support/' )
				) . ' ' . __( '(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_post( $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’s configuration. If you continue to have problems, please try the <a href="%s">support forums</a>.' ),
					__( 'https://wordpress.org/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( 'plugins_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>.' ),
__( 'https://wordpress.org/support/' )
					),
					wp_remote_retrieve_body( $request )
				);
			}
		}
	} elseif ( !is_wp_error($res) ) {
		$res->external = true;
	}

	/**
	 * Filters the Plugin Install 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 Install API.
	 * @param object          $args   Plugin API arguments.
	 */
	return apply_filters( 'plugins_api_result', $res, $action, $args );
}

---

更新日志

Version	description
2.7.0	Introduced.

---

相关函数

Uses

• wp-includes/l10n.php: get_user_locale()
• wp-admin/includes/plugin-install.php: plugins_api_args
• wp-admin/includes/plugin-install.php: plugins_api
• wp-admin/includes/plugin-install.php: plugins_api_result
• wp-includes/l10n.php: __()
• wp-includes/functions.php: maybe_unserialize()
• wp-includes/link-template.php: set_url_scheme()
• wp-includes/http.php: wp_http_supports()
• wp-includes/http.php: wp_remote_post()
• wp-includes/http.php: wp_remote_retrieve_body()
• wp-includes/plugin.php: apply_filters()
• wp-includes/load.php: is_wp_error()
• wp-includes/class-wp-error.php: WP_Error::__construct()
Show 8 more uses Hide more uses

---

Used By

• wp-admin/includes/ajax-actions.php: wp_ajax_install_plugin()
• wp-admin/includes/plugin-install.php: install_popular_tags()
• wp-admin/includes/plugin-install.php: install_plugin_information()
• wp-admin/includes/class-wp-plugin-install-list-table.php: WP_Plugin_Install_List_Table::prepare_items()

---

User Contributed Notes