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!

[Copilot]

Pull request overview

This PR adds a --hook flag to the eval and eval-file commands, allowing users to defer code execution until a specific WordPress lifecycle hook fires. Previously, code always executed immediately after WordPress loaded, which prevented users from running code that depends on plugins or themes being fully initialized.

Changes:

• Adds --hook=<hook> parameter to control execution timing within the WordPress lifecycle
• Validates that --hook cannot be used with --skip-wordpress
• Maintains backward compatibility - without --hook, behavior is unchanged

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
src/Eval_Command.php	Implements hook registration logic, parameter validation, and conditional execution for the eval command
src/EvalFile_Command.php	Implements hook registration logic, parameter validation, and conditional execution for the eval-file command
features/eval.feature	Adds comprehensive test coverage for hook functionality, error conditions, and edge cases including positional arguments

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.