plugins_api( string $action, array|object $args = array() ): object|array|WP_Error
Retrieves plugin installer pages from the WordPress.org Plugins API.
Contents
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.
slug
stringThe plugin slug.per_page
intNumber of plugins per page. Default 24.page
intNumber of current page. Default 1.number
intNumber of tags or categories to be queried.search
stringA search term.tag
stringTag to filter plugins.author
stringUsername of an plugin author to filter plugins.user
stringUsername to query for their favorites.browse
stringBrowse view:'popular'
,'new'
,'beta'
,'recommended'
.locale
stringLocale to provide context-sensitive results. Default is the value of get_locale() .installed_plugins
stringInstalled plugins to provide context-sensitive results.is_ssl
boolWhether links should be returned with https or not. Default false.fields
arrayArray of fields which should or should not be returned.short_description
boolWhether to return the plugin short description. Default true.description
boolWhether to return the plugin full description. Default false.sections
boolWhether to return the plugin readme sections: description, installation, FAQ, screenshots, other notes, and changelog. Default false.tested
boolWhether to return the 'Compatible up to' value. Default true.requires
boolWhether to return the required WordPress version. Default true.requires_php
boolWhether to return the required PHP version. Default true.rating
boolWhether to return the rating in percent and total number of ratings.
Default true.ratings
boolWhether to return the number of rating for each star (1-5). Default true.downloaded
boolWhether to return the download count. Default true.downloadlink
boolWhether to return the download link for the package. Default true.last_updated
boolWhether to return the date of the last update. Default true.added
boolWhether to return the date when the plugin was added to the wordpress.org repository. Default true.tags
boolWhether to return the assigned tags. Default true.compatibility
boolWhether to return the WordPress compatibility list. Default true.homepage
boolWhether to return the plugin homepage link. Default true.versions
boolWhether to return the list of all available versions. Default false.donate_link
boolWhether to return the donation link. Default true.reviews
boolWhether to return the plugin reviews. Default false.banners
boolWhether to return the banner images links. Default false.icons
boolWhether to return the icon links. Default false.active_installs
boolWhether to return the number of active installations. Default false.group
boolWhether to return the assigned group. Default false.contributors
boolWhether 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 referencesfunction 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’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’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’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.
Changelog
Changelog Version Description 2.7.0 Introduced.
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Updated field list with defaults for $action = ‘plugin_information’:
Get plugin data by URL or slug: