深入理解 `add_shortcode()` 函数的源码，它是如何将短代码及其处理函数存储到 `Array` 全局数组的？ - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，大家好！今天咱们来聊聊WordPress里一个相当重要但又容易被忽略的小家伙 —— add_shortcode() 函数。别看它名字短小精悍，背后可是藏着不少门道呢。咱们要做的就是扒开它的外衣，看看它到底是怎么把短代码和处理函数塞进那个神秘的全局数组里的。

一、短代码：WordPress的瑞士军刀

首先，简单回顾一下短代码是啥。简单来说，短代码就是WordPress提供的一种简便方法，让你可以在文章、页面甚至小工具里插入一些复杂的功能，而无需编写大量的HTML或者PHP代码。你可以把它想象成一个预先定义好的“快捷指令”，WordPress会在渲染内容的时候，把这些指令替换成实际的内容。

举个例子，假设你有一个短代码叫做[my_special_button]，当你把这个短代码插入到文章里的时候，WordPress会自动调用一个你预先定义好的函数，这个函数会生成一个漂亮的按钮。是不是很方便？

二、add_shortcode()：短代码的注册中心

add_shortcode() 函数就是负责注册这些短代码的。它的基本用法如下：

add_shortcode( string $tag, callable $callback )

$tag：你要注册的短代码的名字，比如 'my_special_button'。
$callback：一个PHP的callable，也就是一个可以被调用的东西，通常是一个函数的名字，用来处理这个短代码。

三、源码剖析：add_shortcode()的内部秘密

好了，现在才是重头戏。咱们来看看 add_shortcode() 函数的源码，看看它到底是怎么工作的。

（以下代码基于WordPress 6.4.2版本，不同版本可能会有细微差异）

function add_shortcode( string $tag, callable $callback ): bool {
    global $shortcode_tags;

    if ( ! is_array( $shortcode_tags ) ) {
        $shortcode_tags = array();
    }

    if ( isset( $shortcode_tags[ $tag ] ) ) {
        return false;
    }

    $shortcode_tags[ $tag ] = $callback;

    return true;
}

这段代码虽然不长，但是信息量很大。咱们一行一行地分析：

global $shortcode_tags;

这行代码声明了一个全局变量 $shortcode_tags。这就是存储短代码和处理函数的神秘的数组。global 关键字告诉PHP，我们要在函数内部访问全局作用域中的 $shortcode_tags 变量，而不是创建一个新的局部变量。

重点： global 关键字在PHP里挺重要的，用不好容易出问题。它让你可以直接访问全局变量，但也要小心修改全局变量可能会影响到程序的其他部分。
if ( ! is_array( $shortcode_tags ) ) { $shortcode_tags = array(); }

这行代码检查 $shortcode_tags 是否是一个数组。如果是第一次调用 add_shortcode()，$shortcode_tags 可能还没有被初始化，所以我们需要把它初始化为一个空数组。

思考： 为什么要检查 $shortcode_tags 是否是数组？这是为了防止 $shortcode_tags 被意外地设置成其他类型的数据，比如字符串或者对象。如果 $shortcode_tags 不是数组，后面的代码就无法正常工作了。
if ( isset( $shortcode_tags[ $tag ] ) ) { return false; }

这行代码检查 $shortcode_tags 数组中是否已经存在以 $tag 为键的元素。也就是说，它检查是否已经注册过同名的短代码。如果已经注册过，就返回 false，表示注册失败。

灵魂拷问： 为什么要防止重复注册？原因很简单，如果允许重复注册同名的短代码，WordPress就不知道应该调用哪个函数来处理这个短代码了。这会导致不可预测的行为，甚至可能引发错误。
$shortcode_tags[ $tag ] = $callback;

这行代码是核心所在。它把短代码的名字 $tag 作为键，把处理函数 $callback 作为值，存储到 $shortcode_tags 数组中。这样，WordPress就知道哪个短代码对应哪个处理函数了。

关键： 这里使用了数组的键值对存储方式。键是短代码的名字，值是处理函数的引用。这使得WordPress可以通过短代码的名字快速找到对应的处理函数。
return true;

如果一切顺利，这行代码返回 true，表示短代码注册成功。

四、$shortcode_tags 数组的结构

通过上面的分析，我们知道 $shortcode_tags 数组是一个关联数组，它的结构大概是这样的：

$shortcode_tags = array(
    'shortcode_name_1' => 'callback_function_1',
    'shortcode_name_2' => 'callback_function_2',
    'shortcode_name_3' => 'callback_function_3',
    // ... 更多短代码
);

其中，shortcode_name_1、shortcode_name_2、shortcode_name_3 等是短代码的名字，callback_function_1、callback_function_2、callback_function_3 等是对应的处理函数的名字。

五、一个完整的例子

为了更好地理解 add_shortcode() 的用法，咱们来看一个完整的例子。

<?php
/**
 * Plugin Name: My Shortcode Plugin
 * Description: A simple plugin to demonstrate how to use add_shortcode().
 */

// 定义一个处理函数
function my_special_button_callback( $atts, $content = null ) {
    // 解析短代码的属性
    $atts = shortcode_atts(
        array(
            'text' => 'Click Me!',
            'url'  => '#',
        ),
        $atts,
        'my_special_button' // 短代码名称，用于过滤
    );

    // 构建按钮的HTML代码
    $output = '<a href="' . esc_url( $atts['url'] ) . '" class="my-special-button">';
    $output .= esc_html( $atts['text'] );
    $output .= '</a>';

    return $output;
}

// 注册短代码
add_shortcode( 'my_special_button', 'my_special_button_callback' );

// 添加CSS样式（可选）
function my_shortcode_plugin_styles() {
    wp_enqueue_style( 'my-shortcode-plugin', plugin_dir_url( __FILE__ ) . 'css/style.css' );
}
add_action( 'wp_enqueue_scripts', 'my_shortcode_plugin_styles' );

在这个例子中，我们定义了一个名为 my_special_button_callback 的函数，它接受两个参数：$atts 和 $content。$atts 参数是一个数组，包含了短代码的属性，$content 参数是短代码的内容（如果短代码是闭合的，比如 [my_shortcode]content[/my_shortcode]，$content 就会包含 content）。

然后，我们使用 add_shortcode() 函数注册了短代码 my_special_button，并把 my_special_button_callback 函数作为它的处理函数。

最后，我们在 my_shortcode_plugin_styles 函数中添加了CSS样式，让按钮看起来更漂亮。

使用方法：

将上面的代码保存为一个PHP文件，比如 my-shortcode-plugin.php。
将 my-shortcode-plugin.php 文件放到 WordPress 的插件目录 /wp-content/plugins/ 下。
在 WordPress 后台激活 "My Shortcode Plugin" 插件。
在文章或页面中使用短代码 [my_special_button text="点我！" url="https://www.example.com"]。

效果：你会在文章或页面中看到一个链接到 https://www.example.com 的按钮，按钮的文字是 "点我！"。

六、shortcode_atts()：短代码属性的利器

在上面的例子中，我们使用了 shortcode_atts() 函数来解析短代码的属性。这个函数的作用是：

定义默认值： 为短代码的属性定义默认值。
合并属性： 将用户传入的属性和默认属性合并。
类型转换： 确保属性的类型正确。
安全过滤： 对属性进行安全过滤，防止XSS攻击。

shortcode_atts() 函数的用法如下：

shortcode_atts( array $defaults, array $atts, string $shortcode = '' )

$defaults：一个关联数组，包含了属性的默认值。
$atts：一个关联数组，包含了用户传入的属性。
$shortcode：短代码的名字，用于过滤。

七、do_shortcode()：短代码的执行者

既然我们已经知道如何注册短代码了，那么WordPress是如何执行这些短代码的呢？答案是 do_shortcode() 函数。

do_shortcode() 函数会扫描文章或页面的内容，查找短代码，然后调用对应的处理函数来替换这些短代码。

do_shortcode() 函数的用法如下：

do_shortcode( string $content )

$content：要扫描的内容，通常是文章或页面的内容。

WordPress会在渲染文章或页面的时候自动调用 do_shortcode() 函数，所以我们通常不需要手动调用它。但是，如果你想在自己的代码中执行短代码，可以使用 do_shortcode() 函数。

八、一些高级技巧和注意事项

嵌套短代码： 短代码可以嵌套使用，但是要注意嵌套的层数不要太深，否则可能会影响性能。
闭合短代码： 短代码可以是闭合的，也可以是非闭合的。闭合的短代码可以包含内容，比如 [my_shortcode]content[/my_shortcode]。
优先级： 你可以使用 remove_shortcode() 函数来移除已注册的短代码，或者使用 add_filter( 'shortcode_atts_{$shortcode}', 'my_filter_function', 10, 3 ) 来修改短代码的属性。
安全： 在处理短代码的属性时，一定要进行安全过滤，防止XSS攻击。可以使用 esc_attr()、esc_url()、esc_html() 等函数进行过滤。

九、总结

add_shortcode() 函数是WordPress中一个非常重要的函数，它使得我们可以方便地扩展WordPress的功能，而无需修改WordPress的核心代码。通过深入理解 add_shortcode() 函数的源码，我们可以更好地掌握WordPress的开发技巧，编写出更高效、更安全的插件。

核心要点回顾:

函数/变量	作用	重要程度
`add_shortcode()`	注册短代码，将短代码名与处理函数关联	极高
`$shortcode_tags`	全局数组，存储所有已注册的短代码及其处理函数	极高
`shortcode_atts()`	处理短代码属性，提供默认值、合并属性、类型转换和安全过滤	高
`do_shortcode()`	扫描内容，执行短代码，将短代码替换为处理函数的输出	高
`global`	关键字，允许在函数内部访问全局变量	中
`callable`	PHP类型，表示可以被调用的东西，例如函数名	中

好了，今天的讲座就到这里。希望大家通过今天的学习，对 add_shortcode() 函数有了更深入的了解。下次再见！

发表回复 取消回复

发表回复取消回复