进阶 yourls.org 2026-11-19 17:39:56 · 2 阅读

第13章 插件系统

插件

YOURLS 采用插件架构和 API。插件是额外的 PHP 脚本,用于扩展 YOURLS 的功能。YOURLS 的核心设计力求轻量,避免臃肿(不实现并非所有人都需要的功能),并支持易于定制。

借助插件架构,你可以为 YOURLS 添加新功能,而无需修改核心文件。这样,当升级 YOURLS 时,你的修改就不会丢失。记住:不要篡改核心代码。

插件文件结构

插件文件必须命名为 plugin.php,并放置在 [YOURLS_ROOT]/user/plugins 目录下的独立子目录中,例如:YOURLS_ROOT/user/plugins/my_sample_plugin/plugin.php。

插件文件 plugin.php 的开头需要包含类似以下的头部信息:

<?php
/*
Plugin Name: My Sample Plugin
Plugin URI: https://your-own-domain-here.com/articles/hey-test-my-sample-plugin/
Description: This plugin does something and something else
Version: 1.0
Author: Ozh
Author URI: https://ozh.org/
*/

插件 API

YOURLS 核心使用两种“钩子”:过滤器(filters)和动作(actions),允许你的插件“接入” YOURLS 的处理流程。

  • 动作是 YOURLS 在特定点或特定操作时触发的钩子。它相当于通知“某个特定事件刚刚发生”,以便你的插件在此时执行指定的函数。
  • 过滤器是 YOURLS 触发的钩子,允许在变量返回、存入数据库或显示之前对其进行修改。

动作

动作由特定事件触发:将链接插入数据库、向浏览器发送头信息、重定向到长链接等。

YOURLS 核心中的典型动作是类似以下代码的函数调用:

yourls_do_action( 'some_event' );

函数 yourls_do_action() 还可以接受参数,为特定事件提供更多上下文信息。例如,以下动作发生在重定向到长链接时:

yourls_do_action( 'redirect_shorturl', $url );

为 action 挂载自定义函数

创建 action 函数的步骤如下:

  1. 定义一个自定义 PHP 函数 my_event_function(),当事件 'that_event' 触发时执行;
  2. 使用 YOURLS 的 yourls_add_action() 函数把你的函数挂载到该事件上,语法为:yourls_add_action( 'that_event', 'my_event_function' );
  3. 把自定义函数及其挂载代码写进一个插件文件中

简单的 Action 函数示例

当管理页面发送到浏览器、YOURLS 的 logo 打印完毕之后,YOURLS 核心会触发一个事件:

yourls_do_action( 'html_logo' );

我们在 logo 后面紧接着添加一段自定义文本:

// 我们的自定义函数,用来添加文本
function my_custom_text() {
echo "

This is a custom text

";
}

// 把自定义函数挂载到 'html_logo' 事件上
yourls_add_action( 'html_logo', 'my_custom_text');

很简单吧?

进阶的 Action 函数示例

在浏览器被重定向到另一个地址之前(比如访问一个指向长链接的短链接时),会触发下面这个事件:

yourls_do_action( 'pre_redirect', $location, $code );

其中 $location 是重定向的目标地址,$code 是要发送的状态码(大多数情况下是 '301 Moved Permanently')。

如果你把自定义函数挂载到 'pre_redirect' 事件上,它会收到 array($location, $code) 作为参数。

下面我们打断重定向流程,先向用户显示一条提示,告知他们即将跳转到另一个网址:

// 把自定义函数挂载到 'pre_redirect' 事件上
yourls_add_action( 'pre_redirect', 'warning_redirection' );

// 事件触发时会执行的自定义函数
function warning_redirection( $args ) {
$url = $args[0];
$code = $args[1];
echo "

This is a redirection page to: $url

";
echo "

Click here to proceed

";

// die() 以中断正常的事件流程
die();
}

Filters(过滤器)

Filter 是对数据进行处理的函数,通常在 YOURLS 内部函数处理或返回数据之前执行。

YOURLS 中典型的 filter 调用形式如下:

$value = yourls_apply_filter( 'some_filter', $value );

创建过滤器函数 创建过滤器函数的步骤如下: 1. 定义一个自定义 PHP 函数 `my_filter_function()`,接收参数、处理它们并返回结果; 2. 使用 YOURLS 提供的 `yourls_add_filter()` 函数,将该自定义函数挂载到特定的过滤器上; 3. 将自定义函数及其挂载代码写入插件文件中。 警告 即使过滤器没有以任何方式修改传入的值,也必须返回该未修改的值! 过滤器函数示例 当创建一个未提供自定义关键字的短链接时,系统会生成一个随机(实际上是指定序列)的关键字。随后,该关键字会经过以下过滤器: `$keyword = yourls_apply_filter( 'random_keyword', $keyword );
` 如果某个自定义函数挂载到了 `random_keyword` 过滤器,那么 `$keyword` 将作为参数传递给它。 假设我们将 `iloveyourls` 追加到每个序列关键字后,那么生成的短链接就会变成 `https://sho.rt/abciloveyourls`,而不是 `https://sho.rt/abc` `// 将自定义函数挂载到 'random_keyword' 过滤器上
yourls_add_filter( 'random_keyword', 'my_silly_function' );

// 我们的自定义函数
function my_silly_function( $original_keyword ) {
$silly_keyword = $original_keyword . "iloveyourls";

// 过滤器函数在处理完参数后必须返回一个值
return $silly_keyword;
}
` 特殊情况:Shunts(拦截钩子) 某些以 `shunt_` 开头的过滤器钩子,用于让插件有条件地告知 YOURLS 跳过某些操作。例如,你可以跳过符合自定义函数所定义的一组条件的用户的日志记录/点击跟踪。 Shunts 的注册方式与其他过滤器相同,除非条件匹配,否则应返回未修改的传入值: `yourls_add_filter('shunt_update_clicks', 'yp_dont_log_conditional');
yourls_add_filter('shunt_log_redirect', 'yp_dont_log_conditional');

function yp_dont_log_conditional($original_value) {
if (yp_dont_log_conditions_match()) {
return true;
}
return $original_value;
}
`

danger:任何非默认的返回值都会触发 shunt,哪怕返回的是 false 或 0。除非满足插件自身的条件,否则应始终返回传入的 $original_value,不要返回其他任何内容。

Hook 的高级语法

将函数挂载到 action 或 filter 有多种方式,详见高级 hook 语法页面。

插件管理页面

如果想让插件设置可以通过网页界面进行配置,可以注册一个"插件页面",它会显示在 Plugins 菜单下作为子菜单项。

<?php<br>// 注册插件管理页面<br>yourls_add_action( 'plugins_loaded', 'myplugin_init' );<br>function myplugin_init() {<br> yourls_register_plugin_page( 'myplugin', 'My Plugin', 'myplugin_display_page' );<br>}<br><br>// 绘制管理页面的函数<br>function myplugin_display_page() {<br> echo "Hello, World!";<br>}<br>

收尾:你的第一个插件

前面我们学习了如何用一个警告信息中断重定向,以及如何让所有随机短链接以 'iloveyourls' 结尾。现在把这些示例打包成一个真正的插件(虽然毫无实际用途)。

首先创建插件的目录和文件:

  • 在 user/plugins/ 下新建一个目录,比如命名为 my_first_plugin
  • 在其中新建一个空的 plugin.php 文件

ProTip:在 GitHub 上克隆这个骨架仓库,几秒钟就能搞定:YOURLS/plugin-sample

在这个空的 plugin.php 中粘贴以下代码:

<?php<br>/*<br>Plugin Name: My First Plugin<br>Plugin URI: https://github.com/YOURLS/my-first-plugin<br>Description: Sample (pointless) plugin that interrupts short URLs redirection and creates absurdly long short URLs<br>Version: 1.0<br>Author: Ozh<br>Author URI: https://ozh.org/<br>*/<br><br>// 把自定义函数挂载到 'pre_redirect' 事件上<br>yourls_add_action( 'pre_redirect', 'warning_redirection' );<br><br>// 事件触发时执行的自定义函数<br>function warning_redirection( $args ) {<br> $url = $args[0];<br> $code = $args[1]; // 打印提示信息<br> echo "<p>This is a redirection page to: $url</p>";<br> echo "<p>Click <a href='$url'>here</a> to proceed</p>";<br><br> // 用 die() 中断正常的事件流程<br> die();<br>}<br><br>// 把自定义函数挂载到 'random_keyword' filter 上<br>yourls_add_filter( 'random_keyword', 'my_silly_function' );<br><br>// 我们这个无厘头的自定义函数<br>function my_silly_function( $original_keyword ) {<br>

$silly_keyword = $original_keyword . "iloveyourls";

// 过滤器函数处理完参数后必须返回一个值
return $silly_keyword;
}


// 就这么简单了!
将这段 plugin.php 放入 user/plugins/my_first_plugin/ 目录,然后访问 YOURLS 管理后台:你会看到一个新增的“插件”菜单,指向插件管理页面。 恭喜,你刚刚扩展了 YOURLS 的功能! 卸载插件脚本 除了 plugin.php 文件外,YOURLS 1.9 及更高版本还支持卸载脚本。当插件被禁用时,系统会执行该脚本:uninstall.php 典型的 uninstall.php 只是一段感知 YOURLS 环境的代码,用于执行清理操作以确保不留下任何痕迹。示例: // 禁止直接调用。
if( !defined( 'YOURLS_UNINSTALL_PLUGIN' ) ) die();

// 删除自定义选项
yourls_delete_option('joe_plugin');

// 删除自定义表
$table = 'JOE_CUSTOM_TABLE';
$sql = "DROP TABLE IF EXISTS :table";
$binds = array('table' => $table);
$update = yourls_get_db()->fetchAffected($sql, $binds);

// 删除特定文件,
// 向插件的远程服务器发送卸载通知,
// 等等
例如,可以参考 GeoIP Update 插件的实现方式。 钩子列表 完整的钩子(动作和过滤器)列表可用。 该列表每晚针对 YOURLS 当前开发版本生成。 如果你正在开发插件,建议在测试环境中运行该开发版本。 编码指南,否则免谈 给一切加前缀。函数名、全局变量、类名、选项名等,都必须使用唯一的前缀,以避免与其他插件或 YOURLS 核心发生冲突。目前最佳的命名方案是 nick_project_meaningful_stuff(例如 ozh_pingfm_add_more_cheese、joe_captcha_validate_input 等)。 推论:严禁使用 yourls_ 作为前缀。该前缀专用于核心函数。 针对开发版本编写插件代码。这样更容易跟进代码开发进度,并申请添加缺失的钩子。 在 config.php 中设置 define( 'YOURLS_DEBUG', true );,以便尽早捕获 PHP 警告和编码错误。 编写整洁、有适当空白和注释的代码。 阅读编码标准以获取更多细节。

评论 (0)