Skip to content

Add --hook flag to validate WordPress hook execution before shell starts #82

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Copilot wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Add --hook flag to validate WordPress hook execution before shell starts #82

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0b57f1b
Initial plan
Copilot Feb 2, 2026
ea344fb
Add --hook parameter to shell command and tests
Copilot Feb 2, 2026
bb60d94
Refine hook implementation logic for shell command
Copilot Feb 2, 2026
81e5e72
Add validation and error handling for hook parameter
Copilot Feb 2, 2026
844f0bd
Refine documentation and remove redundant validation
Copilot Feb 2, 2026
ee5a48c
Improve code structure with early returns and better string formatting
Copilot Feb 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions features/shell.feature
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,39 @@ Feature: WordPress REPL
"""
history: -1: invalid option
"""

Scenario: Shell with hook parameter
Given a WP install
And a session file:
"""
did_action('init');
"""

When I run `wp shell --basic --hook=init < session`
Then STDOUT should contain:
"""
int(1)
"""

Scenario: Shell with hook parameter using plugins_loaded hook
Given a WP install
And a session file:
"""
did_action('plugins_loaded');
"""

When I run `wp shell --basic --hook=plugins_loaded < session`
Then STDOUT should contain:
"""
int(1)
"""

Scenario: Shell with hook parameter for hook that hasn't fired
Given a WP install

When I try `wp shell --basic --hook=shutdown < /dev/null`
Then STDERR should contain:
"""
Error: The 'shutdown' hook has not fired yet
"""
And the return code should be 1
43 changes: 43 additions & 0 deletions src/Shell_Command.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,57 @@ class Shell_Command extends WP_CLI_Command {
* : Force the use of WP-CLI's built-in PHP REPL, even if the Boris or
* PsySH PHP REPLs are available.
*
* [--hook=<hook>]
* : Ensure that a specific WordPress action hook has fired before starting the shell.
* This validates that the preconditions associated with that hook are met.
* Only hooks that have already been triggered can be used (e.g., init, plugins_loaded, wp_loaded).
* ---
* default: ''
* ---
*
* ## EXAMPLES
*
* # Call get_bloginfo() to get the name of the site.
* $ wp shell
* wp> get_bloginfo( 'name' );
* => string(6) "WP-CLI"
*
* # Start a shell, ensuring the 'init' hook has already fired.
* $ wp shell --hook=init
*/
public function __invoke( $_, $assoc_args ) {
$hook = Utils\get_flag_value( $assoc_args, 'hook', '' );

// No hook specified, start immediately.
if ( ! $hook ) {
$this->start_shell( $assoc_args );
return;
}

// Check if the hook has already fired.
if ( did_action( $hook ) ) {
// Hook already fired, start the shell immediately.
$this->start_shell( $assoc_args );
return;
}

// Hook hasn't fired yet.
WP_CLI::error(
sprintf(
"The '%s' hook has not fired yet. " .
'The shell command runs after WordPress is loaded, so only hooks that have already been triggered can be used. ' .
'Common hooks that are available include: init, plugins_loaded, wp_loaded.',
$hook
)
);
}

/**
* Start the shell REPL.
*
* @param array<string,bool|string> $assoc_args Associative arguments.
*/
private function start_shell( $assoc_args ) {
$class = WP_CLI\Shell\REPL::class;

$implementations = array(
Expand Down