Merge branch 'main' into copilot/support-restarting-shell

Author: swissspidy

.github/workflows/code-quality.yml

@@ -6,6 +6,8 @@ on:
     branches:
       - main
       - master
+  schedule:
+     - cron: '17 2 * * *' # Run every day on a seemly random time.
 
 jobs:
   code-quality:

README.md

@@ -10,7 +10,7 @@ Quick links: [Using](#using) | [Installing](#installing) | [Contributing](#contr
 ## Using
 
 ~~~
-wp shell [--basic]
+wp shell [--basic] [--hook=<hook>]
 ~~~
 
 `wp shell` allows you to evaluate PHP statements and expressions
@@ -25,13 +25,24 @@ that you can use within a WordPress plugin, for example.
 		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
+
 ## Installing
 
 This package is included with WP-CLI itself, no additional installation necessary.

features/shell.feature

@@ -114,3 +114,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

src/Shell_Command.php

@@ -28,6 +28,14 @@ class Shell_Command extends WP_CLI_Command {
 	 * : Watch a file or directory for changes and automatically restart the shell.
 	 * Only works with the built-in REPL (--basic).
 	 *
+	 * [--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.
@@ -47,8 +55,12 @@ class Shell_Command extends WP_CLI_Command {
 	 *     Detected changes in wp-content/plugins/my-plugin, restarting shell...
 	 *     wp>
 	 *
+	 *     # Start a shell, ensuring the 'init' hook has already fired.
+	 *     $ wp shell --hook=init
+	 *
 	 * @param string[] $_ Positional arguments. Unused.
 	 * @param array{basic?: bool, watch?: string} $assoc_args Associative arguments.
+
 	 */
 	public function __invoke( $_, $assoc_args ) {
 		$watch_path = Utils\get_flag_value( $assoc_args, 'watch', false );
@@ -58,6 +70,38 @@ public function __invoke( $_, $assoc_args ) {
 			$assoc_args['basic'] = true;
 		}
 
+		$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(