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

$actionstringrequired
API action to perform: 'query_plugins', 'plugin_information', 'hot_tags' or 'hot_categories'.
$argsarray|objectoptional
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 changelog. 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.
    • requires_php bool
      Whether to return the required PHP 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 installations. Default false.
    • group bool
      Whether to return the assigned group. Default false.
    • contributors bool
      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

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 = 'https://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.

Changelog

VersionDescription
2.7.0Introduced.

User Contributed Notes

  1. Skip to note 4 content

    Updated field list with defaults for $action = ‘plugin_information’:

    $fields = array(
    	'active_installs' => true,           // rounded int
    	'added' => true,                     // date
    	'author' => true,                    // a href html
    	'author_block_count' => true,        // int
    	'author_block_rating' => true,       // int
    	'author_profile' => true,            // url
    	'banners' => true,                   // array( [low], [high] )
    	'compatibility' => false,            // empty array?
    	'contributors' => true,              // array( array( [profile], [avatar], [display_name] )
    	'description' => false,              // string
    	'donate_link' => true,               // url
    	'download_link' => true,             // url
    	'downloaded' => false,               // int
    	// 'group' => false,                 // n/a 
    	'homepage' => true,                  // url
    	'icons' => false,                    // array( [1x] url, [2x] url )
    	'last_updated' => true,              // datetime
    	'name' => true,                      // string
    	'num_ratings' => true,               // int
    	'rating' => true,                    // int
    	'ratings' => true,                   // array( [5..0] )
    	'requires' => true,                  // version string
    	'requires_php' => true,              // version string
    	// 'reviews' => false,               // n/a, part of 'sections'
    	'screenshots' => true,               // array( array( [src],  ) )
    	'sections' => true,                  // array( [description], [installation], [changelog], [reviews], ...)
    	'short_description' => false,        // string
    	'slug' => true,                      // string
    	'support_threads' => true,           // int
    	'support_threads_resolved' => true,  // int
    	'tags' => true,                      // array( )
    	'tested' => true,                    // version string
    	'version' => true,                   // version string
    	'versions' => true,                  // array( [version] url )
    );
  2. Skip to note 5 content

    Get plugin data by URL or slug:

    function wpdev_get_plugin_data($urlOrSlug){
    	require_once( ABSPATH . 'wp-admin/includes/plugin-install.php' );
    	
    	$basename = str_replace('/', '', basename($urlOrSlug));
    
    	$info = plugins_api( 'plugin_information', array( 'slug' => $basename ) );
    
    	if ( ! $info or is_wp_error( $info ) ) {
    		return false;
    	}
    
    	return $info;
    }
    
    // Usage example
    $plugin_info = wpdev_get_plugin_data('https://wordpress.org/plugins/your-plugin-slug/'); // false or stdClass
  3. Skip to note 6 content

    Follow-up to comment by @luxxor (Mark Bernard):

    Yes, as of 2019, the plugin_information action does explicitly request author_block_count and author_block_rating by default – but this is only when retrieving info for a block plugin … which makes sense if you’re thinking about blocks but not if you’re expecting the data in a response to any other plugin.

    For anyone using the plugins_api to retrieve plugin_information for a non-block plugin, or using the API directly to retrieve that data, these details may be of interest.

    Block plugins are associated with “the Block Directory“.

    WordPress first searches the current site for the block … If it doesn’t find a block, it searches in the Block Directory which is a special corner of the WordPress plugin repository, where single block plugins are available.

    See Block Directory Items which defines the author_block fields discussed here.

    If not requested, the fields are not present in the response from wordpress.org.
    – This link shows a request for plugin_information on a non-block plugin, without the explicit request for the fields. The fields are not in the response.
    – This link shows a request on a block plugin, without the explicit request for the fields. The fields are still not in the response. The plugins_api function adds the fields in for us.

    If requested and the plugin is not a block plugin, the value of author_block_count is zero and author_block_rating is indeterminate.
    – This link shows a request for plugin_information on the same non-block plugin, with the explicit request for the fields. The fields are at the end of the response, but the block count is zero and the block rating is about 96. The code under the plugins_api function divides that number by 20 for a 0-5 rating. (I don’t know what that number is for a non-block plugin.)

    If requested and the plugin is in a block plugin, the value of author_block_count is a number cast as a string (“2”, “5”, etc) and author_block_rating is numeric. When plugins_api() receives a response from the wordpress.org API, the author_block_count is explicitly cast to an integer (and the rating is divided by 20). If you are using the API directly, again, the value you receive is a string which will not be consistent with the data you see from plugins_api() , and may lead to confusion or errors. (The raw rating value may also be confusing.)
    – This link shows a request for plugin_information on the same block plugin as above, with an explicit request for the fields.

    Note also that while the plugins_api arguments use Boolean values to define the return values, and common examples show true/false being used, when using the API you should use 0 or 1 for false and true respectively. With request[fields][author_block_rating]=false, the value ‘false’ is a string and is therefore “truthy”, so the attempt to exclude fields fails … For the API, use digit/number zero or one, and for plugins_api() , use Boolean true/false.

You must log in before being able to contribute a note or feedback.