Correct the value type of parse_shell_arrays()'s $assoc_args

[swissspidy]

Utils\parse_shell_arrays() is annotated @param array<string, string> $assoc_args, but associative arguments are not all strings — a flag arrives as boolean true, and a key that has already been parsed arrives as an array.

The function has never required strings. It looks only at the keys named in $array_arguments, and acts only when is_json() returns true — which begins by rejecting anything that is not a string. Every other value is returned exactly as it came in.

Why it is worth fixing rather than working around

The narrow annotation is contagious, and it penalises the callers doing the right thing.

A command that documents its arguments accurately as array<string, mixed> cannot call this function without PHPStan reporting argument.type at level 9. A command whose $assoc_args parameter carries no type at all passes silently, because implicit mixed is not checked at that level and missingType.parameter is generally ignored.

That is exactly what happens in entity-command today: Post_Command and User_Command call it without complaint from untyped parameters, while Comment_Command — the one file that annotates its arguments correctly — fails. The available fixes there are to weaken an accurate annotation or to wrap the call, and neither is a good trade for a docblock that is simply wrong.

Safety

Widening a parameter type cannot break existing callers: everything that satisfied array<string, string> still satisfies array<string, mixed>. The return type is already array<string, mixed>.

The one thing worth checking was whether the @phpstan-ignore cast.useless inside the function would become an unmatched ignore once the value type is no longer known to be a string. It does not — is_json() carries @phpstan-assert-if-true =non-empty-string, so the value is still narrowed to a string inside the branch where the cast happens.

Testing

Four cases added to the existing dataParseShellArray provider, covering what the annotation had been hiding: a boolean flag, an already-decoded array, a non-JSON string, and a mixed set where one key decodes and another passes through.

$ phpunit --filter testParseShellArray tests/UtilsTest.php
OK (7 tests, 7 assertions)

PHPStan over the full analysed paths is unchanged at 1552 errors before and after in my environment (that absolute number is inflated — this environment cannot install the PHPStan extensions CI uses — but the before/after comparison is like-for-like, and the only differences are messages that embed line numbers, shifted by the five lines added to the docblock). PHPCS is clean on both changed files.

I also verified the effect downstream: with this branch in place, Comment_Command's plain Utils\parse_shell_arrays( $assoc_args, [ 'comment_meta' ] ) call reports no PHPStan errors, so wp-cli/entity-command#636 can drop its local workaround once this lands.

🤖 Generated with Claude Code

https://claude.ai/code/session_014SSZzqMJRDTiLiDxQEPYcL

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation

  • Clarified how mixed-value associative arguments are handled when parsing shell arrays.

• Bug Fixes

  • Ensured only configured values containing valid JSON strings are converted to arrays.
  • Preserved booleans, existing arrays, invalid JSON, and other non-string values unchanged.

• Tests

  • Added coverage for mixed-value inputs and combinations of valid and non-JSON values.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: bf2b2b0c-e7a8-4c96-8654-530883351657

📥 Commits

Reviewing files that changed from the base of the PR and between 12b8009 and 2e40a3a.

📒 Files selected for processing (2)

• php/utils.php
• tests/UtilsTest.php

Included review availability: Your plan includes up to 8 reviews per rolling hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

parse_shell_arrays() documentation now describes mixed associative values. Tests verify that only valid JSON strings for configured keys are decoded, while booleans, arrays, invalid JSON, and other values remain unchanged.

Changes

parse_shell_arrays behavior

Layer / File(s)	Summary
Mixed-value parsing contract and validation php/utils.php, tests/UtilsTest.php	The documentation permits mixed associative values. Tests cover valid JSON strings, booleans, arrays, invalid JSON, and mixed arguments.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 2e40a

This localized annotation correction is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

Suggested reviewers: copilot

🚥 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 identifies the main change: correcting the value type annotation for parse_shell_arrays()'s $assoc_args parameter.
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 claude/wp-cli-issue-5286-n50evd-parse-shell-arrays

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!