plugins_api() │ WP 2.7.0

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

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', 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
$slug No Yes No
$per_page Yes No No
$page Yes No No
$number No No Yes
$search Yes No No
$tag Yes No No
$author Yes No No
$user Yes No No
$browse Yes No No
$locale Yes Yes No
$installed_plugins Yes No No
$is_ssl Yes Yes No
$fields Yes Yes No
Хуки из функции

Возвращает

Объект|Массив|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.

Использование

plugins_api( $action, $args );
$action(строка) (обязательный)
API action to perform: 'query_plugins', 'plugin_information', or 'hot_tags'.
$args(массив|объект)

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

По умолчанию: array()

  • slug(строка)
    The plugin slug.
    По умолчанию: ''

  • per_page(int)
    Number of plugins per page.
    По умолчанию: 24

  • page(int)
    Number of current page.
    По умолчанию: 1

  • number(int)
    Number of tags or categories to be queried.

  • search(строка)
    A search term.
    По умолчанию: ''

  • tag(строка)
    Tag to filter plugins.
    По умолчанию: ''

  • author(строка)
    Username of an plugin author to filter plugins.
    По умолчанию: ''

  • user(строка)
    Username to query for their favorites.
    По умолчанию: ''

  • browse(строка)
    Browse view: 'popular', 'new', 'beta', 'recommended'.

  • locale(строка)
    Locale to provide context-sensitive results.
    По умолчанию: value of get_locale()

  • installed_plugins(строка)
    Installed plugins to provide context-sensitive results.

  • is_ssl(true|false)
    Whether links should be returned with https or not.
    По умолчанию: false

  • fields(массив)
    Array of fields which should or should not be returned.

    • short_description(true|false)
      Whether to return the plugin short description.
      По умолчанию: true

    • description(true|false)
      Whether to return the plugin full description.
      По умолчанию: false

    • sections(true|false)
      Whether to return the plugin readme sections: description, installation, FAQ, screenshots, other notes, and changelog.
      По умолчанию: false

    • tested(true|false)
      Whether to return the 'Compatible up to' value.
      По умолчанию: true

    • requires(true|false)
      Whether to return the required WordPress version.
      По умолчанию: true

    • requires_php(true|false)
      Whether to return the required PHP version.
      По умолчанию: true

    • rating(true|false)
      Whether to return the rating in percent and total number of ratings.
      По умолчанию: true

    • ratings(true|false)
      Whether to return the number of rating for each star (1-5).
      По умолчанию: true

    • downloaded(true|false)
      Whether to return the download count.
      По умолчанию: true

    • downloadlink(true|false)
      Whether to return the download link for the package.
      По умолчанию: true

    • last_updated(true|false)
      Whether to return the date of the last update.
      По умолчанию: true

    • added(true|false)
      Whether to return the date when the plugin was added to the wordpress.org repository.
      По умолчанию: true

    • tags(true|false)
      Whether to return the assigned tags.
      По умолчанию: true

    • compatibility(true|false)
      Whether to return the WordPress compatibility list.
      По умолчанию: true

    • homepage(true|false)
      Whether to return the plugin homepage link.
      По умолчанию: true

    • versions(true|false)
      Whether to return the list of all available versions.
      По умолчанию: false

    • donate_link(true|false)
      Whether to return the donation link.
      По умолчанию: true

    • reviews(true|false)
      Whether to return the plugin reviews.
      По умолчанию: false

    • banners(true|false)
      Whether to return the banner images links.
      По умолчанию: false

    • icons(true|false)
      Whether to return the icon links.
      По умолчанию: false

    • active_installs(true|false)
      Whether to return the number of active installations.
      По умолчанию: false

    • contributors(true|false)
      Whether to return the list of contributors.
      По умолчанию: false

Список изменений

С версии 2.7.0 Введена.

Код plugins_api() WP 6.7.1

wp-admin/includes/plugin-install.php 
function plugins_api( $action, $args = array() ) {
	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_get_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', 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_get_wp_version() . '; ' . home_url( '/' ),
		);
		$request   = wp_remote_get( $url, $http_args );

		if ( $ssl && is_wp_error( $request ) ) {
			if ( ! wp_is_json_request() ) {
				wp_trigger_error(
					__FUNCTION__,
					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 );
}