云策 WordPress 开发者社区

函数文档

get_plugin_data()

查看官方原文 ↗
💡 云策文档标注

概述

get_plugin_data() 函数用于解析插件文件内容，提取插件元数据。它从插件主文件的头部信息中读取数据，并返回一个包含插件名称、版本、描述等信息的数组。

关键要点

  • 函数解析插件文件的前 8 KB 内容以获取元数据，插件头部信息必须位于文件顶部。
  • 支持多种插件头部字段，包括必填项如 Plugin Name、Version，以及可选项如 Network、RequiresWP、RequiresPHP 等。
  • 参数 $plugin_file 为插件主文件的绝对路径，$markup 和 $translate 控制返回数据是否应用 HTML 标记和翻译。
  • 返回数组包含插件数据，未提供的字段值为空；函数内部处理了旧版 Site Wide Only 头部的兼容性。
  • 在非管理员界面使用时，可能需要先检查函数是否存在并包含 wp-admin/includes/plugin.php 文件。

代码示例

if ( is_admin() ) {
    if( ! function_exists('get_plugin_data') ){
        require_once( ABSPATH . 'wp-admin/includes/plugin.php' );
    }
    $plugin_data = get_plugin_data( __FILE__ );
    echo "";
    print_r( $plugin_data );
    echo "";
}

注意事项

  • 插件描述不能包含换行符，否则可能只显示部分内容。
  • 默认情况下，get_plugin_data() 可能仅在管理员界面可用，使用前建议检查 function_exists 以避免致命错误。
  • 当 $markup 或 $translate 为 true 时，函数可能调用 wptexturize，需注意执行时机以避免与其他插件冲突。
📄 原文内容

Parses the plugin contents to retrieve plugin’s metadata.

Description

All plugin headers must be on their own line. Plugin description must not have any newlines, otherwise only parts of the description will be displayed.
The below is formatted for printing.

/*
Plugin Name: Name of the plugin.
Plugin URI: The home page of the plugin.
Description: Plugin description.
Author: Plugin author's name.
Author URI: Link to the author's website.
Version: Plugin version.
Text Domain: Optional. Unique identifier, should be same as the one used in
     load_plugin_textdomain().
Domain Path: Optional. Only useful if the translations are located in a
     folder above the plugin's base path. For example, if .mo files are
     located in the locale folder then Domain Path will be "/locale/" and
     must have the first slash. Defaults to the base folder the plugin is
     located in.
Network: Optional. Specify "Network: true" to require that a plugin is activated
     across all sites in an installation. This will prevent a plugin from being
     activated on a single site when Multisite is enabled.
Requires at least: Optional. Specify the minimum required WordPress version.
Requires PHP: Optional. Specify the minimum required PHP version.
* / # Remove the space to close comment.

The first 8 KB of the file will be pulled in and if the plugin data is not within that first 8 KB, then the plugin author should correct their plugin and move the plugin data headers to the top.

The plugin file is assumed to have permissions to allow for scripts to read the file. This is not checked however and the file is only opened for reading.

Parameters

$plugin_filestringrequired
Absolute path to the main plugin file.
$markupbooloptional
If the returned data should have HTML markup applied.

Default:true

$translatebooloptional
If the returned data should be translated.

Default:true

Return

array Plugin data. Values will be empty if not supplied by the plugin.

  • Name string
    Name of the plugin. Should be unique.
  • PluginURI string
    Plugin URI.
  • Version string
    Plugin version.
  • Description string
    Plugin description.
  • Author string
    Plugin author’s name.
  • AuthorURI string
    Plugin author’s website address (if set).
  • TextDomain string
    Plugin textdomain.
  • DomainPath string
    Plugin’s relative directory path to .mo files.
  • Network bool
    Whether the plugin can only be activated network-wide.
  • RequiresWP string
    Minimum required version of WordPress.
  • RequiresPHP string
    Minimum required version of PHP.
  • UpdateURI string
    ID of the plugin for update purposes, should be a URI.
  • RequiresPlugins string
    Comma separated list of dot org plugin slugs.
  • Title string
    Title of the plugin and link to the plugin’s site (if set).
  • AuthorName string
    Plugin author’s name.

Source

function get_plugin_data( $plugin_file, $markup = true, $translate = true ) {

	$default_headers = array(
		'Name'            => 'Plugin Name',
		'PluginURI'       => 'Plugin URI',
		'Version'         => 'Version',
		'Description'     => 'Description',
		'Author'          => 'Author',
		'AuthorURI'       => 'Author URI',
		'TextDomain'      => 'Text Domain',
		'DomainPath'      => 'Domain Path',
		'Network'         => 'Network',
		'RequiresWP'      => 'Requires at least',
		'RequiresPHP'     => 'Requires PHP',
		'UpdateURI'       => 'Update URI',
		'RequiresPlugins' => 'Requires Plugins',
		// Site Wide Only is deprecated in favor of Network.
		'_sitewide'       => 'Site Wide Only',
	);

	$plugin_data = get_file_data( $plugin_file, $default_headers, 'plugin' );

	// Site Wide Only is the old header for Network.
	if ( ! $plugin_data['Network'] && $plugin_data['_sitewide'] ) {
		/* translators: 1: Site Wide Only: true, 2: Network: true */
		_deprecated_argument( __FUNCTION__, '3.0.0', sprintf( __( 'The %1$s plugin header is deprecated. Use %2$s instead.' ), '<code>Site Wide Only: true</code>', '<code>Network: true</code>' ) );
		$plugin_data['Network'] = $plugin_data['_sitewide'];
	}
	$plugin_data['Network'] = ( 'true' === strtolower( $plugin_data['Network'] ) );
	unset( $plugin_data['_sitewide'] );

	// If no text domain is defined fall back to the plugin slug.
	if ( ! $plugin_data['TextDomain'] ) {
		$plugin_slug = dirname( plugin_basename( $plugin_file ) );
		if ( '.' !== $plugin_slug && ! str_contains( $plugin_slug, '/' ) ) {
			$plugin_data['TextDomain'] = $plugin_slug;
		}
	}

	if ( $markup || $translate ) {
		$plugin_data = _get_plugin_data_markup_translate( $plugin_file, $plugin_data, $markup, $translate );
	} else {
		$plugin_data['Title']      = $plugin_data['Name'];
		$plugin_data['AuthorName'] = $plugin_data['Author'];
	}

	return $plugin_data;
}

View all references View on Trac View on GitHub

Uses Description
_get_plugin_data_markup_translate()wp-admin/includes/plugin.php

Sanitizes plugin data, optionally adds markup, optionally translates.
get_file_data()wp-includes/functions.php

Retrieves metadata from a file.
plugin_basename()wp-includes/plugin.php

Gets the basename of a plugin.
__()wp-includes/l10n.php

Retrieves the translation of $text.
_deprecated_argument()wp-includes/functions.php

Marks a function argument as deprecated and inform when it has been used.

Show 2 moreShow less

Used by Description
WP_REST_Templates_Controller::get_wp_templates_author_text_field()wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php

Returns a human readable text for the author of the template.
WP_REST_Plugins_Controller::create_item()wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php

Uploads a plugin and optionally activates it.
validate_plugin_requirements()wp-admin/includes/plugin.php

Validates the plugin requirements for WordPress version and PHP version.
wp_ajax_delete_plugin()wp-admin/includes/ajax-actions.php

Handles deleting a plugin via AJAX.
wp_ajax_update_plugin()wp-admin/includes/ajax-actions.php

Handles updating a plugin via AJAX.
WP_Automatic_Updater::update()wp-admin/includes/class-wp-automatic-updater.php

Updates an item, if appropriate.
Plugin_Upgrader::bulk_upgrade()wp-admin/includes/class-plugin-upgrader.php

Upgrades several plugins at once.
Plugin_Upgrader::check_package()wp-admin/includes/class-plugin-upgrader.php

Checks that the source package contains a valid plugin.
get_dropins()wp-admin/includes/plugin.php

Checks the wp-content directory and retrieve all drop-ins with any plugin data.
is_network_only_plugin()wp-admin/includes/plugin.php

Checks for “Network: true” in the plugin header to see if this should be activated only as a network wide plugin. The plugin would also work when Multisite is not enabled.
get_plugins()wp-admin/includes/plugin.php

Checks the plugins directory and retrieve all plugin files with plugin data.
get_mu_plugins()wp-admin/includes/plugin.php

Checks the mu-plugins directory and retrieve all mu-plugin files with any plugin data.

Show 7 moreShow less

Changelog

Version Description
6.5.0 Added support for Requires Plugins header.
5.8.0 Added support for Update URI header.
5.3.0 Added support for Requires at least and Requires PHP headers.
1.5.0 Introduced.

User Contributed Notes

  2. Skip to note 5 content


    yo35


    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

    Warning: get_plugin_data(..) is NOT available by default (not even in the admin). The pattern proposed by Aamer Shahzad with if ( ! function_exists( 'get_plugin_data' ) ) { require_once ... } seems to be mandatory before using get_plugin_data(..) (although not documented).

    Otherwise, the whole site may crash with a fatal PHP error “call to undefined function”.

  3. Skip to note 6 content


    pepe


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    If $markup or $translate are set to true (as they are by default), the function indirectly calls wptexturize, potentially breaking other plugins if this happens before the init hook.