阐述 WordPress `add_shortcode()` 函数的源码：插件如何注册短代码。

各位观众老爷们，晚上好！今天咱们来聊聊 WordPress 插件里那些“短小精悍”的家伙——短代码（Shortcode）。它们就像一个个小小的魔法咒语，嵌入文章或页面后，就能变出各种各样的功能，比如插入相册、显示表格、播放视频等等。而这一切的幕后功臣，就是 WordPress 的 add_shortcode() 函数。

咱们今天就来扒一扒 add_shortcode() 的源码，看看它是如何让插件注册短代码，从而实现这些神奇的功能的。

1. 短代码：化繁为简的“咒语”

在深入源码之前，先简单回顾一下短代码的概念。短代码本质上就是一个被方括号包裹的标记，例如 [my_shortcode] 或者 [my_shortcode attribute="value"]。WordPress 会扫描文章内容，找到这些标记，然后调用相应的函数来替换它们。

2. add_shortcode()：注册短代码的“魔法书”

add_shortcode() 函数的作用就是将一个短代码标记与一个 PHP 函数关联起来。它的基本语法如下：

add_shortcode( string $tag, callable $callback );

• $tag: 短代码的名称，例如 "my_shortcode"。
• $callback: 处理短代码的 PHP 函数，也称为短代码处理函数。

3. 源码剖析：add_shortcode() 的内部运作

现在，让我们深入 WordPress 核心代码，看看 add_shortcode() 究竟是如何运作的。 为了简化说明，我们只关注核心逻辑，忽略一些错误处理和兼容性代码。

实际上，add_shortcode() 函数并没有直接位于全局空间，而是定义在 WP_Shortcode 类中，这个类是 WordPress 用来管理短代码的核心类。 但是为了方便理解，我们可以假设它是一个全局函数。

// 假设的 add_shortcode() 函数实现（简化版）
function add_shortcode( $tag, $callback ) {
  global $shortcode_tags; // 引用全局变量 $shortcode_tags

  if ( ! is_callable( $callback ) ) {
    return; // 如果回调函数不可调用，直接返回
  }

  $shortcode_tags[ $tag ] = $callback; // 将短代码和回调函数存储到全局数组中
}

这段代码的核心是 global $shortcode_tags; 和 $shortcode_tags[ $tag ] = $callback;。

• global $shortcode_tags;: 这行代码声明 $shortcode_tags 是一个全局变量。 $shortcode_tags 是一个数组，用于存储所有已注册的短代码及其对应的处理函数。 可以把它想象成一本“短代码魔法书”，记录了每个短代码对应的“魔法咒语”。

• $shortcode_tags[ $tag ] = $callback;: 这行代码将短代码 $tag 和处理函数 $callback 存储到 $shortcode_tags 数组中。 键是短代码的名称，值是处理函数的名称。 这就像在“魔法书”中添加了一个新的条目，记录了新的短代码的“魔法咒语”。

4. 全局变量 $shortcode_tags：短代码的“魔法书”

$shortcode_tags 是一个非常重要的全局变量，它是一个关联数组，存储了所有已注册的短代码及其对应的处理函数。 它的结构大致如下：

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

5. 短代码处理函数：执行“魔法咒语”的“魔法师”

短代码处理函数是负责实际处理短代码并生成输出的函数。 它的基本语法如下：

function my_shortcode_handler( $atts = [], $content = null, $tag = '' ) {
  // 处理短代码的逻辑
  // 返回要显示的 HTML 内容
  return '<div>短代码的输出</div>';
}

• $atts: 一个关联数组，包含了短代码的所有属性。 例如，如果短代码是 [my_shortcode attribute1="value1" attribute2="value2"]，那么 $atts 数组将是 array('attribute1' => 'value1', 'attribute2' => 'value2')。

• $content: 短代码的内容。 如果短代码是 [my_shortcode]内容[/my_shortcode]，那么 $content 将是 "内容"。 如果短代码没有闭合标签（例如 [my_shortcode]），则 $content 为 null。

• $tag: 短代码的名称，例如 "my_shortcode"。

6. WordPress 如何解析短代码：寻找并执行“魔法咒语”

当 WordPress 显示文章或页面时，它会调用 do_shortcode() 函数来解析短代码。 do_shortcode() 函数会扫描文章内容，找到所有短代码标记，然后从 $shortcode_tags 数组中找到对应的处理函数，并调用该函数来替换短代码标记。

do_shortcode() 函数的内部逻辑比较复杂，涉及到正则表达式匹配和递归调用。 为了简化说明，我们只关注核心逻辑。

// 假设的 do_shortcode() 函数实现（简化版）
function do_shortcode( $content ) {
  global $shortcode_tags; // 引用全局变量 $shortcode_tags

  if ( empty( $shortcode_tags ) || ! is_array( $shortcode_tags ) ) {
    return $content; // 如果没有注册任何短代码，直接返回原始内容
  }

  $pattern = get_shortcode_regex(); // 获取用于匹配短代码的正则表达式

  return preg_replace_callback( "/$pattern/s", 'do_shortcode_tag', $content ); // 使用正则表达式匹配短代码，并调用 do_shortcode_tag 函数来替换它们
}

• global $shortcode_tags;: 这行代码声明 $shortcode_tags 是一个全局变量。 do_shortcode() 函数需要访问 $shortcode_tags 数组，才能找到短代码对应的处理函数。

• get_shortcode_regex();: 这行代码调用 get_shortcode_regex() 函数来获取用于匹配短代码的正则表达式。 这个正则表达式可以匹配各种格式的短代码，包括带属性的短代码和带内容的短代码。

• preg_replace_callback( "/$pattern/s", 'do_shortcode_tag', $content );: 这行代码使用 preg_replace_callback() 函数来匹配文章内容中的短代码，并调用 do_shortcode_tag() 函数来替换它们。 preg_replace_callback() 函数会将每个匹配到的短代码传递给 do_shortcode_tag() 函数进行处理。

do_shortcode_tag() 函数负责实际调用短代码处理函数并替换短代码标记。

// 假设的 do_shortcode_tag() 函数实现（简化版）
function do_shortcode_tag( $matches ) {
  global $shortcode_tags; // 引用全局变量 $shortcode_tags

  $tag = $matches[2]; // 获取短代码的名称

  if ( isset( $shortcode_tags[ $tag ] ) ) {
    $callback = $shortcode_tags[ $tag ]; // 获取短代码的处理函数

    $atts = shortcode_parse_atts( $matches[3] ); // 解析短代码的属性

    return call_user_func( $callback, $atts, $matches[5], $tag ); // 调用短代码的处理函数，并返回结果
  } else {
    return $matches[0]; // 如果没有找到对应的处理函数，则返回原始的短代码标记
  }
}

• global $shortcode_tags;: 这行代码声明 $shortcode_tags 是一个全局变量。 do_shortcode_tag() 函数需要访问 $shortcode_tags 数组，才能找到短代码对应的处理函数。

• $tag = $matches[2];: 这行代码从正则表达式匹配结果中获取短代码的名称。

• if ( isset( $shortcode_tags[ $tag ] ) ) { ... }: 这行代码检查 $shortcode_tags 数组中是否存在该短代码的处理函数。

• $callback = $shortcode_tags[ $tag ];: 这行代码从 $shortcode_tags 数组中获取短代码的处理函数。

• $atts = shortcode_parse_atts( $matches[3] );: 这行代码调用 shortcode_parse_atts() 函数来解析短代码的属性。

• return call_user_func( $callback, $atts, $matches[5], $tag );: 这行代码使用 call_user_func() 函数来调用短代码的处理函数，并将属性、内容和短代码名称作为参数传递给它。 call_user_func() 函数允许我们动态地调用函数，非常灵活。

7. 示例：注册和使用一个简单的短代码

下面是一个简单的示例，演示如何注册和使用一个短代码：

<?php
/**
 * Plugin Name: Simple Shortcode Example
 */

// 注册短代码
add_shortcode( 'greeting', 'greeting_shortcode_handler' );

// 短代码处理函数
function greeting_shortcode_handler( $atts = [], $content = null, $tag = '' ) {
  // 设置默认属性
  $atts = shortcode_atts(
    array(
      'name' => 'World',
    ),
    $atts,
    $tag
  );

  // 构建输出
  $output = 'Hello, ' . esc_html( $atts['name'] ) . '!';

  return $output;
}

在这个示例中，我们注册了一个名为 "greeting" 的短代码，并将其与 greeting_shortcode_handler() 函数关联起来。 greeting_shortcode_handler() 函数接受一个可选的 "name" 属性，并返回一个包含问候语的字符串。

现在，你可以在文章或页面中使用这个短代码：

[greeting]
[greeting name="John"]

第一个短代码将输出 "Hello, World!"，第二个短代码将输出 "Hello, John!"。

8. 总结：add_shortcode() 的核心机制

总而言之，add_shortcode() 函数的核心机制就是将短代码名称和处理函数存储到一个全局数组 $shortcode_tags 中。 当 WordPress 解析文章内容时，它会扫描文章内容，找到所有短代码标记，然后从 $shortcode_tags 数组中找到对应的处理函数，并调用该函数来替换短代码标记。

我们可以用一个表格来总结 add_shortcode() 函数涉及的关键元素：

元素	描述
add_shortcode()	用于注册短代码的函数。它将短代码名称和处理函数存储到全局数组 $shortcode_tags 中。
$shortcode_tags	一个全局数组，存储了所有已注册的短代码及其对应的处理函数。可以把它想象成一本“短代码魔法书”。
短代码处理函数	负责实际处理短代码并生成输出的函数。它接受属性、内容和短代码名称作为参数。
do_shortcode()	用于解析文章内容中的短代码的函数。它会扫描文章内容，找到所有短代码标记，然后从 $shortcode_tags 数组中找到对应的处理函数，并调用该函数来替换短代码标记。
do_shortcode_tag()	do_shortcode() 函数内部使用的函数，负责实际调用短代码处理函数并替换短代码标记。
get_shortcode_regex()	用于获取匹配短代码的正则表达式的函数。

9. 高级技巧：短代码的嵌套和属性解析

除了基本的短代码注册和使用之外，还有一些高级技巧可以帮助你更好地利用短代码：

• 短代码的嵌套: 短代码可以嵌套使用，例如 [parent][child]内容[/child][/parent]。 要处理嵌套的短代码，需要在短代码处理函数中递归调用 do_shortcode() 函数。

• 属性解析: shortcode_atts() 函数可以用来设置默认属性，并对用户传递的属性进行过滤和验证。

10. 注意事项：安全性和性能

在使用短代码时，需要注意以下几点：

• 安全性: 短代码处理函数应该对用户输入进行转义和验证，以防止安全漏洞，例如跨站脚本攻击 (XSS)。

• 性能: 过多的短代码会影响页面的加载速度。 应该尽量减少短代码的使用，并优化短代码处理函数的性能。

好了，今天的讲座就到这里。希望通过今天的讲解，大家对 WordPress 的 add_shortcode() 函数有了更深入的了解。 短代码是一个非常强大的工具，可以帮助你扩展 WordPress 的功能，并为用户提供更好的体验。 希望大家能够灵活运用短代码，创造出更多精彩的 WordPress 插件和主题！ 记住，编程就像变魔术，而 add_shortcode() 就是你手中的魔杖！ 祝大家编程愉快！