At Vatu we use PHP Stan to analyze our code and help prevent bugs. For our WordPress projects, there is a handy WordPress Stubs module.
This reads the core WordPress functions DocBlocks and checks our code is adhering to these. This makes sure we are passing parameters correctly to functions and the like.
Our issue appears when using apply_filters('hook_name', $value1, $value2). If we pass more than two parameters to this function we are shown an error:
------ ---------------------------------------------------------------
Line includes/functions.php
------ ---------------------------------------------------------------
44 Function apply_filters invoked with 3 parameters, 2 required.
------ --------------------------------------------------------------- This is a false positive. As the apply_filters() function can accept multiple parameters.
The function also allows for multiple additional arguments to be passed to hooks.
WordPress Code Reference: Apply Filters Function
Checking the DocBlocks for apply_filters() shows the name within the parameter tag.
* @param mixed $value The value to filter.
* @param mixed ...$args Additional parameters to pass to the callback functions.
* @return mixed The filtered value after all hooked functions are applied to it.
*/
function apply_filters($hook_name, $value)It looks to have the wrong formatting for the name indicator. Changing the tag resolves the issue.
* @param mixed $value,... The value to filter.
* @param mixed ...$args Additional parameters to pass to the callback functions.
* @return mixed The filtered value after all hooked functions are applied to it.
*/
function apply_filters($hook_name, ...$value)This can be tested by making the change to the WordPress Stub’s code: https://github.com/php-stubs/wordpress-stubs/blob/master/wordpress-stubs.php#L109219-109223.
To fully resolve the issue. The change needs to be made in Core (https://github.com/WordPress/wordpress-develop/blob/7819ca4e3e3d2c0b3dbfec0ec83f52c304ef69bd/src/wp-includes/plugin.phpL#159-L163). Fixing this false positive in the next release of WordPress Stubs.
Our current solution is to patch the WordPress Stub files. with Composer’s “Post Update Command” and sed:
sed -i.tmp 's/* @param mixed $value The value to filter./* @param mixed $value,... The value to filter./' vendor/php-stubs/wordpress-stubs/wordpress-stubs.php
sed -i.tmp 's/function apply_filters($hook_name, $value)/function apply_filters($hook_name, ...$value)/' vendor/php-stubs/wordpress-stubs/wordpress-stubs.php