EP124. “第一个插件：插件头信息与 the_content 过滤器”

从零创建第一个最简单的插件：在 wp-content/plugins/ 下新建一个专属文件夹和同名 PHP 文件，用标准注释格式写插件头信息（WordPress 靠这段注释识别插件名称、版本、作者等），再用 the_content 过滤器给博客文章正文末尾动态追加一句话。最后用 is_page() + is_main_query() 组合条件，把这个效果限定在只对某类页面生效（而不是全站所有用到 the_content 的地方都生效）。

涉及文件

• wp-content/plugins/our-first-unique-plugin/our-first-unique-plugin.php （新建）

代码实现

our-first-unique-plugin.php（完整文件）：

<?php

/*
  Plugin Name: Our Test Plugin
  Description: A truly amazing plugin.
  Version: 1.0
  Author: Brad
  Author URI: https://www.udemy.com/user/bradschiff/
*/

add_filter('the_content', 'addToEndOfPost');

function addToEndOfPost($content) {
  if (is_page() && is_main_query()) {
    return $content . '<p>My name is Brad.</p>';
  }

  return $content;
}

关键改动点：

• 插件文件夹名和文件名可以随便取，但要选一个全网独一无二的名字，避免跟别的插件撞名冲突
• 文件开头的注释块是 WordPress 识别插件的标准格式：Plugin Name（必须精确是这个属性名，其余是自由文本）、Description、Version、Author、Author URI 这些字段会直接显示在后台 Plugins 列表里；没写在这一讲的属性（比如国际化相关的）留到后面涉及翻译功能时再补
• add_filter('the_content', 'addToEndOfPost')：the_content 是 WordPress 核心提供的过滤器钩子，专门用来拦截/修改文章正文即将输出的内容
• 回调函数命名要注意「唯一性」——因为目前用的是普通函数（不是类的方法），如果两个不同插件都定义了同名函数会直接报错冲突；作者提到后面会讲用 PHP 类来规避这个问题，但目前先接受这个限制
• addToEndOfPost($content) 接收的 $content 参数就是这篇文章原本的正文内容，函数最终 return 的值就是浏览器实际会显示的内容——如果只 return 新增的字符串而不拼接原始 $content，会导致原本的正文完全消失，只剩下插件加的这句话
• . '<p>...</p>' 用点号做字符串拼接，把新内容追加在原内容后面
• is_page() && is_main_query()：is_page() 判断当前是不是「Page」这个文章类型的详情页（不是博客文章，也不是 attachment）；is_main_query() 判断当前循环是不是这个 URL 的「主查询」（排除掉侧边栏/页脚等模板里可能出现的次要循环）——两者同时满足才追加内容，避免在文章列表、侧边栏摘要等不该出现的地方也被追加

[截图：wp-admin 插件列表页面，显示新建插件 "Our Test Plugin" 的名称/描述/版本信息]

[截图：前台 Page 详情页正文末尾出现的 "My name is Brad." 追加文字]

Hook / Function 速查

常见坑

• 回调函数只 return 新增内容、忘记拼接原始 $content——会导致文章原本的正文完全消失
• 回调函数命名太随意（比如叫 filter 或 run）——容易跟其他插件或 WordPress 核心的函数名冲突，报「函数已声明」的致命错误
• 忘记限定生效范围（直接对全站所有 the_content 调用生效）——列表页摘要、侧边栏最新文章等地方也会一起被追加内容，通常不是想要的效果，需要用 is_page()/is_single() 等条件函数收窄范围

延伸 / 后续讲座会用到

下一讲开始做真正有实用价值的插件：在博客文章详情页显示字数统计（Post Statistics），包括字数、字符数、预估阅读时间。

Sources

Udemy：

• Become a WordPress Developer: Unlocking Power With Code — Section 23, EP124