feat: hook handler argument types (sniff + PHPStan rule)

[d4mation]

What

Adds two complementary checks that forbid native parameter and return types on WordPress hook handlers, where the types are not guaranteed.

A hook's argument and return types are never guaranteed: inaccurate documentation can lead to the wrong native type, and any third party can dispatch one of our hooks via apply_filters() / do_action() with arguments of a different type. Either way, a value that does not match a native type on the handler causes a runtime fatal. Enforcement follows the hook type:

• Filter handlers: no native type on any parameter and no native return type.
• Action handlers: no native type on any parameter; a native void return type is allowed (actions always return void).

There is no prefix or first-party concept — the check applies to every hook, and needs zero configuration.

1. PHPCS sniff — StellarWP.Hooks.HookHandlerTypes (auto-fixable)

Analyses at the add_action() / add_filter() call site and resolves same-file handlers — inline closures/arrows, [ $this, 'method' ] / [ self::class, 'method' ] (including the old [ &$this, 'method' ] idiom), 'function_name' globals, and $this->add_action( 'tag', 'method' ) wrapper calls (memberdash's MS_Hooker) — then strips only the offending native types (verified to never reformat: nullable/union/intersection/DNF/FQN/variadic/by-ref/attribute forms and multiline layouts, idempotent). Enable with <rule ref="StellarWP.Hooks.HookHandlerTypes"/>. Optional allow_void_return_on_actions property (default true).

Wrapper handlers are reported but not auto-fixed. The $this->add_action( 'tag', 'method' ) form is resolved with a name-match heuristic (the second argument names a method on the enclosing class, falling back to the hook name when it is absent or empty). That is safe enough to report on but not to auto-fix: in rare cases the matched method may not actually be a hook handler (e.g. a class that defines its own unrelated add_action() / add_filter() method alongside a coincidentally-named method), and stripping native types is destructive. So the sniff raises the violation without a fix — it still fails CI, but phpcbf leaves it alone. Remove the types by hand, or silence a false positive at the handler with // phpcs:ignore StellarWP.Hooks.HookHandlerTypes.NativeParameterType. Direct callbacks (closures, [ $this, 'method' ], global functions) remain auto-fixable.

2. PHPStan rule (auto-discovered extension)

Whole-codebase, never diff-limited. Resolves all callback forms across files via reflection (methods, Class::method, global functions, closures, $container->callback( Class::class, 'method' ) container callbacks, and $receiver->add_action( 'tag', 'method' ) wrapper methods) and resolves hook names via type inference (so a $hook = '...' variable is caught). Report-only; the message names the exact handler. Auto-registers via phpstan/extension-installer with no configuration; optional allowVoidReturnOnActions parameter (default true).

The two are complementary: the sniff gives instant, auto-fixable feedback for the same-file case; the PHPStan rule is the authoritative gate that catches handlers whose declaration lives in a different file from the hook call — the case a diff-limited phpcs run misses.

Tests

• AbstractSniffUnitTest (sniff) — asserts exact error lines + compares phpcbf output to a .inc.fixed baseline (the wrapper handlers appear as errors but are intentionally left unfixed in the baseline).
• RuleTestCase (PHPStan rule) — asserts exact messages/lines.
• composer test runs ruleset-explain + both suites. Green on PHP 7.4 (the rule test skips due to a php-parser emulation quirk on the 7.4 test runtime; the rule itself runs fine on 7.4) and 8.3.

Real-world validation

Installed into learndash-notifications (zero config). Both tools flag a real WPML fatal that had shipped and been hotfixed separately:

Uncaught TypeError: WPML::filter_has_access(): Argument #3 ($user_id) must be of type int, null given
apply_filters( 'sfwd_lms_has_access', true, 28, null )

Each tool reports 16 findings across 5 files, including all 8 in WPML.php.

Notes

• New dev deps: phpunit/phpunit, phpstan/phpstan. New autoload (StellarWP\ psr-4), extra.phpstan.includes, and a working composer test.

Draft: opened for review before merge.