Add --hook flag to defer eval execution to WordPress lifecycle hooks

[Copilot]

Adds --hook=<hook> parameter to eval and eval-file commands to control execution timing within the WordPress lifecycle. Previously, code always executed immediately after WordPress loaded. Some use cases require deferring execution until specific preconditions are met (e.g., plugins loaded, theme initialized).

Implementation

• Registers code/file as action callback before WordPress loads when --hook specified
• WordPress lifecycle proceeds normally, firing the specified hook at the appropriate time
• Without --hook, behavior unchanged (immediate execution)
• Validates --hook incompatible with --skip-wordpress

Usage

# Execute after specific hook fires
wp eval 'echo current_action();' --hook=init

# Defer file execution until dependencies ready
wp eval-file check-plugin-active.php --hook=plugins_loaded

# Works with positional arguments
wp eval-file process-data.php arg1 arg2 --hook=wp_loaded

Changes

• src/Eval_Command.php: Hook registration logic, parameter validation
• src/EvalFile_Command.php: Hook registration logic, parameter validation
• features/eval.feature: Test coverage for hook functionality and edge cases

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add --hook=<hook> flag to eval and shell to choose timing</issue_title>
<issue_description>## Feature Request

For both the eval|eval-file commands as well as the shell command, there's a fixed point in time within the WordPress lifecycle that these are executed.

It would be great to have a --hook=<hook> flag for these that allows the user to postpone when they are being triggered, so that you can choose a specific time within the WordPress lifecycle to run them on.

• Yes, I reviewed the contribution guidelines.

Describe your use case and the problem you are facing

An example is using these commands to QA new code. Some code can only be executed once the preconditions are met, which means they need to be executed at or after a certain action.

Allowing these commands to be attached to a specific action/filter allows the user to choose when to execute them, so that they can ensure the preconditions for the code to be run are met.

Describe the solution you'd like

This can probably be done by dynamically creating a closure with the code to evaluate or the PsySh breakpoint and attaching that closure to the requested action, instead of immediately executing something.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add --hook=<hook> flag to eval and shell to choose timing ideas#146

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!