Automattic / Automattic/VIP-Coding-Standards

Check the hook callback parameter count ?

未关闭
#567 0 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看
主要语言
PHP
星标
261
派生
44
平均合并
19 分钟
30 天内合并 PR
1

描述

## What problem would the enhancement address for VIP?

Prevent potential fatal `ArgumentCount` errors.

## Describe the solution you'd like

Inspired by the `AlwaysReturnInFilter` sniff, I was thinking that once the abstract hook/callback sniff exists, it wouldn't be that hard to create a sniff which would check synchronicity between the parameters requested from a hook-in and the callback function declaration.

This would apply to both `add_filter()` as well as `add_action()`.

Such a sniff would also be a candidate for (eventually moving to) WPCS, but I wanted to discuss the general idea here first, largely to see if the potential issue described above actually occurs in real life situations.

## What code should be reported as a violation?

```php
// Error: Two parameters expected, one (implicit) requested.
add_filter( 'the_title', function( $title, $id ) {
// Do something.
return $title;
} );

// Warning: One parameter expected, two requested.
add_filter( 'the_title', function( $title ) {
// Do something.
return $title;
}, 10, 2 );
```

## What code should *not* be reported as a violation?

```php
// OK: Two parameters expected, two requested.
add_filter( 'the_title', function( $title, $id ) {
// Do something.
return $title;
}, 10, 2 );

// OK: Three parameters expected, two requested, but third parameter is optional,
// which can be done by design to allow direct calls to the function to pass it.
function prefix_title_filter( $title, $id, $optional = null ) {
// Do something.
return $title;
}
add_filter( 'the_title', 'prefix_title_filter', 10, 2 );
```

## Additional context

### Future scope
* Once a list of WP native hooks + the amount of parameters they pass is known (via a trait in WPCS for instance), an additional check could be added that the `$accepted_args` parameter value is never higher than the number of passed parameters when the hook is called.

```php
function prefix_title_filter( $title, $id, $optional = null ) {
// Do something.
return $title;
}

// The `the_title` filter only passes two arguments max, so the code here is an error.
add_filter( 'the_title', 'prefix_title_filter', 10, 3 );
```
* For PHP native functions used in callbacks, reflection could be used to see how many (required) parameters these take and match that with the `$accepted_args` parameter.
* For WP native functions a list based solution would be needed to do the same.

## Relevant links
* https://developer.wordpress.org/reference/functions/add_action/
* https://developer.wordpress.org/reference/functions/add_filter/

贡献指南

打开贡献指南

调研方向

首先检查现有的 AlwaysReturnInFilter sniff,以及链接的 WordPress 参考资料中记录的 add_filter() 和 add_action() 入口点。在定义 sniff 的范围之前,明确应如何比较回调声明和 accepted_args,包括可选参数和闭包。对于所提供的违规和非违规示例,行为已得到规定即表示完成。

由索引模型根据 Issue 内容生成。

评估

技术栈
php
领域
tooling
Issue 类型
功能
难度
5/5
预计耗时
一周以上
活跃度
停滞
描述清晰度
需要澄清
新手友好度
25/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。