分析 WordPress `plugin_basename()` 函数的源码：如何获取插件文件相对于插件目录的路径。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位技术达人们，晚上好！今天咱们来聊聊 WordPress 插件开发中一个不起眼，但又非常实用的函数：plugin_basename()。别看它名字平平无奇，它可是能帮我们获取插件文件相对于插件目录的路径，这在很多场景下都非常重要。接下来，就让我们一起扒一扒它的源码，看看它是如何工作的。

一、缘起：为什么需要 plugin_basename()？

在 WordPress 插件开发中，我们经常需要知道当前插件的文件路径。比如：

注册设置链接: 在插件列表页面添加一个“设置”链接，需要知道插件的主文件路径才能正确生成 URL。
处理国际化 (i18n): 加载插件的语言包时，需要知道语言包文件相对于插件目录的位置。
更新检查: 确定当前运行的插件版本，需要基于主插件文件路径进行版本信息比对。

plugin_basename() 函数正是为了解决这个问题而生的。它能返回插件主文件相对于 WP_PLUGIN_DIR (插件目录) 的路径，这对于构建健壮且可维护的插件至关重要。

二、庖丁解牛：plugin_basename() 源码分析

让我们一起看看 plugin_basename() 的源码（位于 wp-includes/plugin.php 文件中）：

function plugin_basename( $file ) {
    /**
     * Filters the base name of the plugin.
     *
     * @since 2.5.0
     *
     * @param string $file The plugin file path.
     */
    return apply_filters( 'plugin_basename', plugin_basename_recursive( $file ), $file );
}

function plugin_basename_recursive( $file ) {
    $file = wp_normalize_path( $file );
    $wp_plugin_dir = wp_normalize_path( WP_PLUGIN_DIR );
    $wp_mu_plugin_dir = wp_normalize_path( WPMU_PLUGIN_DIR );

    if ( strpos( $file, '/' ) === false ) {
        return $file;
    }

    // Get the plugin folder name from the path.
    $plugin_path = str_replace( wp_normalize_path( ABSPATH ), '', $file );
    $plugin_path = str_replace( $wp_plugin_dir . '/', '', $plugin_path );
    $plugin_path = str_replace( $wp_mu_plugin_dir . '/', '', $plugin_path );

    $parts = explode( '/', $plugin_path );
    $plugin_path = $parts[0];

    if ( strpos( $plugin_path, '.' ) !== false ) {
        return '';
    }

    return $plugin_path . '/' . basename( $file );
}

别被这一堆代码吓到，让我们慢慢拆解：

plugin_basename( $file ): 这是主函数。它接收一个参数 $file，即插件文件的完整路径。它使用 apply_filters 钩子，允许我们通过过滤器修改最终结果。重点是它调用了 plugin_basename_recursive() 函数来实际处理路径。
plugin_basename_recursive( $file ): 这个函数才是真正的幕后功臣。
- 标准化路径: 首先，它使用 wp_normalize_path() 函数标准化 $file、WP_PLUGIN_DIR 和 WPMU_PLUGIN_DIR 的路径。这样做是为了确保在不同操作系统上路径分隔符的一致性（例如，Windows 使用，而 Linux 使用 /）。
- 简单情况处理: 如果 $file 中不包含 /，则直接返回 $file。这种情况通常发生在直接传入插件文件夹名称而不是完整文件路径时。
- 计算相对路径: 这是核心部分。它使用 str_replace() 函数从 $file 中移除 ABSPATH (WordPress 根目录)、WP_PLUGIN_DIR 和 WPMU_PLUGIN_DIR，从而得到相对于插件目录的路径。
- 提取插件目录: 使用 explode() 函数将相对路径分割成数组，取第一个元素作为插件目录名。
- 安全检查: 检查插件目录名中是否包含 .。如果包含，则认为路径无效，返回空字符串。
- 构建最终结果: 最后，将插件目录名和文件名组合成最终的相对路径，并返回。

三、代码示例：plugin_basename() 的实际应用

为了更好地理解 plugin_basename() 的用法，让我们看几个实际的代码示例：

示例 1：获取插件主文件路径

<?php
/**
 * Plugin Name: My Awesome Plugin
 */

// 获取当前插件主文件的完整路径
$plugin_file = __FILE__;

// 获取插件的 basename
$plugin_base = plugin_basename( $plugin_file );

echo '插件主文件路径：' . $plugin_file . '<br>';
echo '插件 basename：' . $plugin_base;

// 输出结果类似：
// 插件主文件路径：/var/www/html/wp-content/plugins/my-awesome-plugin/my-awesome-plugin.php
// 插件 basename：my-awesome-plugin/my-awesome-plugin.php
?>

在这个例子中，__FILE__ 常量包含了当前插件主文件的完整路径。 plugin_basename() 函数将其转换为相对于插件目录的路径 "my-awesome-plugin/my-awesome-plugin.php"。

示例 2：在插件列表页面添加设置链接

<?php
add_filter( 'plugin_action_links_' . plugin_basename( __FILE__ ), 'my_plugin_settings_link' );

function my_plugin_settings_link( $links ) {
    $settings_link = '<a href="options-general.php?page=my-plugin-settings">' . __( 'Settings', 'my-plugin' ) . '</a>';
    array_unshift( $links, $settings_link );
    return $links;
}
?>

这里，plugin_basename( __FILE__ ) 用于构造 plugin_action_links_{$plugin_file} 过滤器名称，其中 $plugin_file 就是插件的 basename。这样，WordPress 才能知道要将设置链接添加到哪个插件的动作链接列表中。

示例 3：加载插件语言包

<?php
function my_plugin_load_textdomain() {
    load_plugin_textdomain(
        'my-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages/'
    );
}
add_action( 'plugins_loaded', 'my_plugin_load_textdomain' );
?>

在这个例子中，dirname( plugin_basename( __FILE__ ) ) 返回插件目录名 "my-plugin"。然后，将其与 /languages/ 组合，得到语言包文件的相对路径 "my-plugin/languages/"。 load_plugin_textdomain() 函数使用这个路径来加载插件的语言包。

四、plugin_basename() 的注意事项

必须在插件主文件中使用: plugin_basename() 应该在插件的主文件中使用，或者在插件的其他文件中使用时，确保传入的是插件主文件的完整路径。
不要滥用: 只有在确实需要获取插件相对路径时才使用 plugin_basename()。过度使用可能会导致代码的可读性和可维护性降低。
路径分隔符: plugin_basename() 返回的路径使用 / 作为分隔符，这在所有操作系统上都是一致的。

五、plugin_basename() 与其他路径函数的比较

WordPress 提供了多个与路径相关的函数，让我们简单比较一下 plugin_basename() 与其他一些常用函数：

函数	功能	返回值示例	适用场景
`plugin_basename( $file )`	获取插件主文件相对于插件目录的路径。	`my-plugin/my-plugin.php`	在插件列表页面添加设置链接，加载插件语言包等，需要知道插件相对路径的场景。
`plugins_url( $path, $plugin )`	获取插件目录中的文件的完整 URL。	`http://example.com/wp-content/plugins/my-plugin/assets/style.css`	在前端页面中引用插件的 CSS、JavaScript 或其他静态资源。
`plugin_dir_path( $file )`	获取插件目录的完整路径。	`/var/www/html/wp-content/plugins/my-plugin/`	在插件中需要读取或写入文件时，获取插件目录的完整路径。
`plugin_dir_url( $file )`	获取插件目录的完整 URL。	`http://example.com/wp-content/plugins/my-plugin/`	获取插件目录的 URL，例如用于 AJAX 请求。
`dirname( $file )`	获取文件所在目录的路径。	如果 `$file` 是 `/var/www/html/wp-content/plugins/my-plugin/my-plugin.php`，则返回 `/var/www/html/wp-content/plugins/my-plugin`。	获取文件所在目录的路径，可以与 `plugin_basename()` 结合使用，例如 `dirname( plugin_basename( __FILE__ ) )` 可以获取插件的目录名。
`wp_normalize_path( $path )`	标准化路径，将路径分隔符统一为 `/`。	将 `C:pathtofile` 转换为 `C:/path/to/file`。	在处理文件路径时，确保路径分隔符的一致性，避免在不同操作系统上出现问题。

六、总结

plugin_basename() 函数虽然简单，但却是 WordPress 插件开发中一个非常实用的工具。它可以帮助我们获取插件文件的相对路径，从而方便地注册设置链接、处理国际化、进行更新检查等等。理解它的源码和用法，可以让我们编写出更健壮、更可维护的 WordPress 插件。

希望今天的讲解对大家有所帮助！记住，熟练掌握这些小技巧，才能在 WordPress 开发的道路上越走越远。感谢大家的收听！

发表回复 取消回复

发表回复取消回复