PHPStan: Add dynamic return type extension for WP_CLI::do_hook()

[swissspidy]

Inspired by WordPress/wordpress-develop#12022

Summary by CodeRabbit

• New Features

  • Improved PHPStan analysis for WP_CLI::do_hook().
  • Return types are now inferred from supplied arguments and applicable documentation, including scalar values and array shapes.

• Bug Fixes

  • Added handling for hook calls without arguments, correctly identifying null return values.

• Tests

  • Added coverage for common hook return types, typed arrays, inline documentation, and formatter results.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 24 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../PHPStan/WPCliDoHookDynamicReturnTypeExtension.php	0.00%	24 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

WP-CLI hook return type analysis

Layer / File(s)	Summary
Dynamic do_hook return type resolution src/PHPStan/WPCliDoHookDynamicReturnTypeExtension.php	Adds PHPStan inference for WP_CLI::do_hook(), using resolved PHPDoc types, the second argument type, or NullType.
Service registration and type assertions extension.neon, tests/data/do_hook.php, tests/tests/PHPStan/TestDynamicReturnTypeExtension.php	Registers the PHPStan services and verifies null, scalar, array, typed-array, and docblock-driven return types.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PHPStan
  participant WPCliDoHookDynamicReturnTypeExtension
  participant FileTypeMapper
  participant WP_CLI
  PHPStan->>WPCliDoHookDynamicReturnTypeExtension: Analyze WP_CLI::do_hook()
  WPCliDoHookDynamicReturnTypeExtension->>FileTypeMapper: Resolve PHPDoc parameter types
  FileTypeMapper-->>WPCliDoHookDynamicReturnTypeExtension: Return resolved type
  WPCliDoHookDynamicReturnTypeExtension-->>PHPStan: Provide inferred return type

Loading

Suggested reviewers: schlessera, brianhenryie, ernilambar

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a PHPStan dynamic return type extension for WP_CLI::do_hook().
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch add/do-hook-extension

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 PHPStan (2.2.6)

PHPStan was skipped because the config uses disallowed bootstrapFiles, bootstrapFile, or includes directives.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/PHPStan/WPCliDoHookDynamicReturnTypeExtension.php (1)

48-65: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

First @param tag is used unconditionally — fragile if the docblock ever has more than one param.

The loop returns the type of whichever @param tag is encountered first in getParamTags(). This works for the current test fixtures (each docblock has exactly one @param), but nothing enforces that invariant — a docblock documenting both the hook name and the filtered value (e.g. @param string $hook_name, @param array $value) would silently return the wrong type. Consider matching against the specific parameter representing the filtered value (e.g. by position/name) rather than "whichever is first."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/PHPStan/WPCliDoHookDynamicReturnTypeExtension.php` around lines 48 - 65,
Update the parameter-type lookup in the resolved PHPDoc handling of the
extension so it selects the tag corresponding to the filtered value parameter by
its known name or position, rather than returning the first entry from
getParamTags(). Preserve returning that matched parameter’s type and define the
existing behavior when no matching tag is present.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/data/do_hook.php`:
- Around line 43-49: Update the assertType call for $formats_result in the
formatter_available_formats hook test to assert array<int, string> instead of
array<string>, matching the integer-keyed string array type documented by the
$formats annotation.

---

Nitpick comments:
In `@src/PHPStan/WPCliDoHookDynamicReturnTypeExtension.php`:
- Around line 48-65: Update the parameter-type lookup in the resolved PHPDoc
handling of the extension so it selects the tag corresponding to the filtered
value parameter by its known name or position, rather than returning the first
entry from getParamTags(). Preserve returning that matched parameter’s type and
define the existing behavior when no matching tag is present.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0ff2159b-7d31-4bac-9621-fff389be8e38

📥 Commits

Reviewing files that changed from the base of the PR and between e307fc6 and 8cbc8c9.

📒 Files selected for processing (4)

• extension.neon
• src/PHPStan/WPCliDoHookDynamicReturnTypeExtension.php
• tests/data/do_hook.php
• tests/tests/PHPStan/TestDynamicReturnTypeExtension.php