云策 WordPress 开发者社区

函数文档

plugins_url()

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

概述

plugins_url() 函数用于获取插件或 mu-plugins 目录的绝对 URL，支持附加路径和相对文件路径。它通过内部常量 WP_PLUGIN_URL 或 WPMU_PLUGIN_URL 构建 URL，并应用 'plugins_url' 过滤器。

关键要点

  • 函数返回插件或 mu-plugins 目录的 URL，可选附加路径或基于指定文件相对路径。
  • 参数 $path 为附加路径字符串，$plugin 为插件文件路径，常用 __FILE__ 使 $path 相对当前文件父目录。
  • 内部使用 WP_PLUGIN_URL 或 WPMU_PLUGIN_URL 常量，并通过 apply_filters() 应用 'plugins_url' 过滤器。
  • 建议在 'init' 或 'admin_init' 等 Hook 中调用，避免全局上下文，以确保过滤器生效。
  • 函数处理路径规范化、URL 方案设置，并返回过滤后的 URL 字符串。

代码示例

// 基本用法：获取插件目录 URL
$plugins_url = plugins_url();

// 常见用法：使用 __FILE__ 使路径相对当前文件父目录
echo '<img src="' . plugins_url( 'images/icon.png', __FILE__ ) . '" />';

// 嵌套子目录时使用 dirname()
echo '<img src="' . plugins_url( 'images/icon.png', dirname( __FILE__ ) ) . '" />';

注意事项

  • 避免在插件文件的全局上下文中直接调用 plugins_url()，应通过 Hook 调用以确保过滤器可被其他插件修改。
  • mu-plugins 由于运行顺序较早，可以在全局上下文中过滤 plugins_url()。
  • 不推荐直接使用 WordPress 内部常量如 WP_PLUGIN_URL，应通过此函数获取 URL。
📄 原文内容

Retrieves a URL within the plugins or mu-plugins directory.

Description

Defaults to the plugins directory URL if no arguments are supplied.

Parameters

$pathstringoptional
Extra path appended to the end of the URL, including the relative directory if $plugin is supplied. Default empty.
$pluginstringoptional
A full path to a file inside a plugin or mu-plugin.
The URL will be relative to its directory. Default empty.
Typically this is done by passing __FILE__ as the argument.

Return

string Plugins URL link with optional paths appended.

More Information

This function retrieves the absolute URL to the plugins or mu-plugins directory (without the trailing slash) or, when using the $path argument, to a specific file under that directory. You can either specify the $path argument as a hardcoded path relative to the plugins or mu-plugins directory, or conveniently pass __FILE__ as the second argument to make the $path relative to the parent directory of the current PHP script file.

Uses the WP_PLUGIN_URL or, in the case the $plugin path begins with the WPMU_PLUGIN_DIR path, the WPMU_PLUGIN_URL constant internally, to compose the resultant URL. Note that the direct usage of WordPress internal constants is not recommended.

Uses apply_filters() to apply “plugins_url” filters on the resultant URL, with the following line of code

return apply_filters( 'plugins_url', $url, $path, $plugin );

The plugins_url()  function should not be called in the global context of plugins, but rather in a hook like “init” or “admin_init” to ensure that the “plugins_url” filters are already hooked at the time the function is called. This is vital for many site configurations to work, and if plugins_url()  is called in the global context of a plugin file it cannot be filtered by other plugins (though mu-plugins are able to filter it because they run before any other plugins).

Source

function plugins_url( $path = '', $plugin = '' ) {

	$path          = wp_normalize_path( $path );
	$plugin        = wp_normalize_path( $plugin );
	$mu_plugin_dir = wp_normalize_path( WPMU_PLUGIN_DIR );

	if ( ! empty( $plugin ) && str_starts_with( $plugin, $mu_plugin_dir ) ) {
		$url = WPMU_PLUGIN_URL;
	} else {
		$url = WP_PLUGIN_URL;
	}

	$url = set_url_scheme( $url );

	if ( ! empty( $plugin ) && is_string( $plugin ) ) {
		$folder = dirname( plugin_basename( $plugin ) );
		if ( '.' !== $folder ) {
			$url .= '/' . ltrim( $folder, '/' );
		}
	}

	if ( $path && is_string( $path ) ) {
		$url .= '/' . ltrim( $path, '/' );
	}

	/**
	 * Filters the URL to the plugins directory.
	 *
	 * @since 2.8.0
	 *
	 * @param string $url    The complete URL to the plugins directory including scheme and path.
	 * @param string $path   Path relative to the URL to the plugins directory. Blank string
	 *                       if no path is specified.
	 * @param string $plugin The plugin file path to be relative to. Blank string if no plugin
	 *                       is specified.
	 */
	return apply_filters( 'plugins_url', $url, $path, $plugin );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘plugins_url’, string $url, string $path, string $plugin )

Filters the URL to the plugins directory.

Uses Description
wp_normalize_path()wp-includes/functions.php

Normalizes a filesystem path.
set_url_scheme()wp-includes/link-template.php

Sets the scheme for a URL.
plugin_basename()wp-includes/plugin.php

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

Calls the callback functions that have been added to a filter hook.

Show 1 moreShow less

Used by Description
WP_URL_Pattern_Prefixer::get_default_contexts()wp-includes/class-wp-url-pattern-prefixer.php

Returns the default contexts used by the class.
get_block_asset_url()wp-includes/blocks.php

Gets the URL to a block asset.
load_script_textdomain()wp-includes/l10n.php

Loads the script translated strings.
get_theme_root_uri()wp-includes/theme.php

Retrieves URI for themes directory.
plugin_dir_url()wp-includes/plugin.php

Get the URL directory path (with trailing slash) for the plugin __FILE__ passed in.

Changelog

Version Description
2.6.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Codex


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

    Common Usage
    The plugins_url() function is commonly used in a plugin file. Passing the __FILE__ PHP magic constant in the place of the $plugin parameter makes the $path relative to the parent directory of that file:

    echo '<img src="' . esc_url( plugins_url( 'images/wordpress.png', __FILE__ ) ) . '" > ';

    The above might output this HTML markup: <img src="http://www.example.com/wp-content/plugins/my-plugin/images/wordpress.png">.

    If you are using the plugins_url() function in a file that is nested inside a subdirectory of your plugin directory, you should use PHP’s dirname() function:

    echo '<img src="' . esc_url( plugins_url( 'images/wordpress.png', dirname(__FILE__) ) ) . '" > ';

    The above might output this HTML markup: <img src="http://www.example.com/wp-content/plugins/images/wordpress.png">.