第11章 Hooks(钩子)
钩子
本指南面向已经熟悉 Plugins API 基础知识的开发者,列举了将自定义函数挂钩到动作(Actions)和事件(Events)的所有方式。
注意:虽然此处仅涵盖过滤器(Filters),但所有规则同样适用于动作。
编写生产就绪代码:为了简明清晰,示例中为函数和变量使用了通用且随意的名称(如 my_function())。实际开发中请避免这种做法,务必阅读 编码标准。
可能的语法
yourls_add_filter('filter', 'funcname');
这是默认方式,使用两个字符串。示例如下:
function say_hello( $name ) {
return yourls_apply_filter( 'hello', "hello $name" );
}
// 未经过滤的结果
var_dump( say_hello( "ozh" ) );
// string 'hello ozh' (length=9)
// 自定义过滤函数
function add_exclamations( $input ) {
return $input . '!!!';
}
// 挂钩后的过滤结果
yourls_add_filter( 'hello', 'add_exclamations' );
var_dump( say_hello( "ozh" ) );
// string 'hello ozh!!!' (length=12)
yourls_add_filter('filter', create_function(...));
你无需专门定义自定义函数,可以直接在 PHP 中内联使用匿名函数,配合 create_function() 实现(注意:create_function() 在 PHP 7.2.0 起已被弃用)。
以下示例会对任何挂钩的过滤器返回 false:
yourls_add_filter( 'some_filter', create_function( '', 'return false;' ) );
尽管这在语法上完全可行且是有效的 PHP 写法,但我们不推荐这种做法:这种写可读性差,当匿名函数逻辑非显而易见时难以调试,且存在性能和内存效率问题,并在 PHP 7.2 中已被弃用。
yourls_add_filter('filter', function(){...});
使用闭包(Closures)是更优雅且易读的匿名函数用法。
完整示例:
function say_hello( $name ) {
return yourls_apply_filter( 'hello', "hello $name" );
}
// 未经过滤的结果
var_dump( say_hello( "ozh" ) );
// string 'hello ozh' (length=9)
yourls_add_filter( 'hello', function( $in ) { return "well $in and have a good day"; } );
// 挂钩后的过滤结果
var_dump( say_hello( "ozh" ) );
// string 'well hello ozh and have a good day' (length=34)
yourls_add_filter('filter', array('my_class','some_function'));
你也可以使用类内部定义的过滤函数。示例:
function say_hello( $name ) {
return yourls_apply_filter( 'hello', "hello $name" );
}
// 未经过滤的结果
var_dump( say_hello( "ozh" ) );
// 字符串 'hello ozh'(长度=9)
class My_Class {
static function my_friend( $var ) {
return "$var my friend";
}
}
yourls_add_filter( 'hello', array('My_Class', 'my_friend') );
// 过滤后的结果
var_dump( say_hello( "ozh" ) );
// string 'hello ozh my friend' (length=19)
注意:由于类没有被实例化,必须把函数声明为静态方法才能使用。 yourls_add_filter('filter', 'my_class::some_function'); 同一个例子的另一种写法,用 'class::method' 表示法: function say_hello( $name ) {
return yourls_apply_filter( 'hello', "hello $name" );
}
// 过滤前的结果
var_dump( say_hello( "ozh" ) );
// string 'hello ozh' (length=9)
class My_Class {
static function my_friend( $var ) {
return "$var my friend";
}
}
yourls_add_filter( 'hello', 'My_Class::my_friend' );
// 过滤后的结果
var_dump( say_hello( "ozh" ) );
// string 'hello ozh my friend' (length=19)
yourls_add_filter('filter', array($this,'some_function')); 如果类已有实例,写法如下: function say_hello( $name ) {
return yourls_apply_filter( 'hello', "hello $name" );
}
// 过滤前的结果
var_dump( say_hello( "ozh" ) );
// string 'hello ozh' (length=9)
class My_Class {
function my_friend( $var ) {
return "$var my friend";
}
}
$friendify = new My_Class;
yourls_add_filter( 'hello', array( $friendify, 'my_friend' ) );
// 过滤后的结果
var_dump( say_hello( "ozh" ) );
// string 'hello ozh my friend' (length=19)
当然,类实例不必赋值给变量,直接写 array( new My_Class, 'my_friend' ) 即可,不必引入 $friendify。 这种写法常用于插件本身封装在一个类里的情况,此时可以用 $this 关键字引用类的当前实例。 总结 这个简洁示例涵盖了所有可用的 hook 语法,方便快速查阅。 实际使用示例 一个实用示例:在每个管理页面的标题后附加 "title is modified",效果类似于 YOURLS 自带的示例插件: /*
Plugin Name: Change admin page titles
Version: 1.0
Author: Ozh
Author URI: https://ozh.org/
*/
class Hack_The_Page_Title{
function __construct() {
yourls_add_filter( 'html_title', array( $this, 'change_title' ) );
}
function change_title( $value ) {
return $value . ' -- title is modified';
}
}
new Hack_The_Page_Title;
进一步的 Hook 调试
使用 yourls_remove_filter() 删除过滤器,或用 yourls_has_filter() 检查某个 Hook 是否存在过滤器时,引用函数的语法与之前相同。下面是一个简单的示例,展示了在 YOURLS 插件类中如何添加、检查和删除过滤器。
Actions 的工作机制与 Filters 完全一致,可以使用相同的语法来添加、检查或移除一个 action。
需要注意的是,通过匿名函数添加的 Hook 通常无法方便地移除(或检查其是否存在)。因此在大多数情况下,应避免使用这种语法。