Merge branch 'main' into copilot/add-suppress-output-option

swissspidy · swissspidy · commit 688d397b4c29 · 2026-03-17T10:56:25.000+01:00
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,14 @@
+/.actrc export-ignore
+/.distignore export-ignore
+/.editorconfig export-ignore
+/.github export-ignore
+/.gitignore export-ignore
+/.typos.toml export-ignore
+/AGENTS.md export-ignore
+/behat.yml export-ignore
+/features export-ignore
+/phpcs.xml.dist export-ignore
+/phpstan.neon.dist export-ignore
+/phpunit.xml.dist export-ignore
+/tests export-ignore
+/wp-cli.yml export-ignore
diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
@@ -21,13 +21,11 @@ jobs:
 
       - name: Check existence of composer.json file
         id: check_composer_file
-        uses: andstor/file-existence-action@076e0072799f4942c8bc574a82233e1e4d13e9d6 # v3
-        with:
-          files: "composer.json"
+        run: echo "files_exists=$(test -f composer.json && echo true || echo false)" >> "$GITHUB_OUTPUT"
 
       - name: Set up PHP environment
         if: steps.check_composer_file.outputs.files_exists == 'true'
-        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # v2
+        uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # v2
         with:
           php-version: 'latest'
           ini-values: zend.assertions=1, error_reporting=-1, display_errors=On
@@ -38,7 +36,7 @@ jobs:
 
       - name: Install Composer dependencies & cache dependencies
         if: steps.check_composer_file.outputs.files_exists == 'true'
-        uses: ramsey/composer-install@3cf229dc2919194e9e36783941438d17239e8520 # v3
+        uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # v3
         env:
           COMPOSER_ROOT_VERSION: dev-${{ github.event.repository.default_branch }}
         with:
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@ Quick links: [Using](#using) | [Installing](#installing) | [Contributing](#contr
 ## Using
 
 ~~~
-wp shell [--basic] [--hook=<hook>]
+wp shell [--basic] [--watch=<path>] [--hook=<hook>]
 ~~~
 
 `wp shell` allows you to evaluate PHP statements and expressions
@@ -19,12 +19,21 @@ hit enter, and see the code execute right before you. Because WordPress
 is loaded, you have access to all the functions, classes and globals
 that you can use within a WordPress plugin, for example.
 
+The `restart` command reloads the shell by spawning a new PHP process,
+allowing modified code to be fully reloaded. Note that this requires
+the `pcntl_exec()` function. If not available, the shell restarts
+in-process, which resets variables but doesn't reload PHP files.
+
 **OPTIONS**
 
 	[--basic]
 		Force the use of WP-CLI's built-in PHP REPL, even if the Boris or
 		PsySH PHP REPLs are available.
 
+	[--watch=<path>]
+		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.
@@ -40,6 +49,18 @@ that you can use within a WordPress plugin, for example.
     wp> get_bloginfo( 'name' );
     => string(6) "WP-CLI"
 
+    # Restart the shell to reload code changes.
+    $ wp shell
+    wp> restart
+    Restarting shell in new process...
+    wp>
+
+    # Watch a directory for changes and auto-restart.
+    $ wp shell --watch=wp-content/plugins/my-plugin
+    wp> // Make changes to files in the plugin directory
+    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
 
diff --git a/composer.json b/composer.json
@@ -12,7 +12,7 @@
         }
     ],
     "require": {
-        "wp-cli/wp-cli": "^2.12"
+        "wp-cli/wp-cli": "^2.13"
     },
     "require-dev": {
         "wp-cli/wp-cli-tests": "^5"
diff --git a/features/shell.feature b/features/shell.feature
@@ -61,6 +61,75 @@ Feature: WordPress REPL
       """
     And STDERR should be empty
 
+  Scenario: Restart shell
+    Given a WP install
+    And a session file:
+      """
+      $a = 1;
+      restart
+      $b = 2;
+      """
+
+    When I run `wp shell --basic < session`
+    Then STDOUT should contain:
+      """
+      Restarting shell...
+      """
+    And STDOUT should contain:
+      """
+      => int(2)
+      """
+
+  Scenario: Exit shell
+    Given a WP install
+    And a session file:
+      """
+      $a = 1;
+      exit
+      """
+
+    When I run `wp shell --basic < session`
+    Then STDOUT should contain:
+      """
+      => int(1)
+      """
+    And STDOUT should not contain:
+      """
+      exit
+      """
+
+  Scenario: Use SHELL environment variable as fallback for bash
+    Given a WP install
+
+    And a session file:
+      """
+      return true;
+      """
+
+    # SHELL pointing to bash should work (when bash is available).
+    When I try `SHELL=/bin/bash wp shell --basic < session`
+    Then STDOUT should contain:
+      """
+      bool(true)
+      """
+    And STDERR should be empty
+
+    # SHELL pointing to non-bash binary should be ignored and fall back to /bin/bash.
+    When I try `SHELL=/bin/sh wp shell --basic < session`
+    Then STDOUT should contain:
+      """
+      bool(true)
+      """
+    And STDERR should be empty
+
+    # SHELL pointing to invalid path should be ignored and fall back to /bin/bash.
+    When I try `SHELL=/nonsense/path wp shell --basic < session`
+    Then STDOUT should contain:
+      """
+      bool(true)
+      """
+    And STDERR should be empty
+
   Scenario: Input starting with dash
     Given a WP install
     And a session file:
diff --git a/src/Shell_Command.php b/src/Shell_Command.php
@@ -13,12 +13,21 @@ class Shell_Command extends WP_CLI_Command {
 	 * is loaded, you have access to all the functions, classes and globals
 	 * that you can use within a WordPress plugin, for example.
 	 *
+	 * The `restart` command reloads the shell by spawning a new PHP process,
+	 * allowing modified code to be fully reloaded. Note that this requires
+	 * the `pcntl_exec()` function. If not available, the shell restarts
+	 * in-process, which resets variables but doesn't reload PHP files.
+	 *
 	 * ## OPTIONS
 	 *
 	 * [--basic]
 	 * : Force the use of WP-CLI's built-in PHP REPL, even if the Boris or
 	 * PsySH PHP REPLs are available.
 	 *
+	 * [--watch=<path>]
+	 * : 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.
@@ -34,15 +43,37 @@ class Shell_Command extends WP_CLI_Command {
 	 *     wp> get_bloginfo( 'name' );
 	 *     => string(6) "WP-CLI"
 	 *
+	 *     # Restart the shell to reload code changes.
+	 *     $ wp shell
+	 *     wp> restart
+	 *     Restarting shell in new process...
+	 *     wp>
+	 *
+	 *     # Watch a directory for changes and auto-restart.
+	 *     $ wp shell --watch=wp-content/plugins/my-plugin
+	 *     wp> // Make changes to files in the plugin directory
+	 *     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
 	 *
 	 *     # Start a shell in quiet mode, suppressing return value output.
 	 *     $ wp shell --quiet
 	 *     wp> $a = "hello";
 	 *     wp>
+	 *
+	 * @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 );
+
+		if ( $watch_path && ! Utils\get_flag_value( $assoc_args, 'basic' ) ) {
+			WP_CLI::warning( 'The --watch option only works with the built-in REPL. Enabling --basic mode.' );
+			$assoc_args['basic'] = true;
+		}
+
 		$hook = Utils\get_flag_value( $assoc_args, 'hook', '' );
 
 		// No hook specified, start immediately.
@@ -72,9 +103,16 @@ public function __invoke( $_, $assoc_args ) {
 	/**
 	 * Start the shell REPL.
 	 *
-	 * @param array<string,bool|string> $assoc_args Associative arguments.
+	 * @param array{basic?: bool, watch?: string} $assoc_args Associative arguments.
 	 */
 	private function start_shell( $assoc_args ) {
+		$watch_path = Utils\get_flag_value( $assoc_args, 'watch', '' );
+
+		if ( $watch_path && ! Utils\get_flag_value( $assoc_args, 'basic' ) ) {
+			WP_CLI::warning( 'The --watch option only works with the built-in REPL. Enabling --basic mode.' );
+			$assoc_args['basic'] = true;
+		}
+
 		$class = WP_CLI\Shell\REPL::class;
 		$quiet = (bool) WP_CLI::get_config( 'quiet' );
 
@@ -107,8 +145,116 @@ private function start_shell( $assoc_args ) {
 			/**
 			 * @var class-string<WP_CLI\Shell\REPL> $class
 			 */
-			$repl = new $class( 'wp> ', $quiet );
-			$repl->start();
+			if ( $watch_path ) {
+				$watch_path = $this->resolve_watch_path( $watch_path );
+			}
+
+			do {
+				$repl = new $class( 'wp> ', $quiet );
+				if ( $watch_path ) {
+					$repl->set_watch_path( $watch_path );
+				}
+				$exit_code = $repl->start();
+
+				// If restart requested, exec a new PHP process to reload all code
+				if ( WP_CLI\Shell\REPL::EXIT_CODE_RESTART === $exit_code ) {
+					$this->restart_process( $assoc_args );
+					// If restart_process() returns, pcntl_exec is not available, continue in-process
+				}
+			} while ( WP_CLI\Shell\REPL::EXIT_CODE_RESTART === $exit_code );
+		}
+	}
+
+	/**
+	 * Resolve and validate the watch path.
+	 *
+	 * @param string $path Path to watch.
+	 * @return string|never Absolute path to watch.
+	 */
+	private function resolve_watch_path( $path ) {
+		if ( ! file_exists( $path ) ) {
+			WP_CLI::error( "Watch path does not exist: {$path}" );
+		}
+
+		$realpath = realpath( $path );
+		if ( false === $realpath ) {
+			WP_CLI::error( "Could not resolve watch path: {$path}" );
+		}
+
+		return $realpath;
+	}
+
+	/**
+	 * Restart the shell by spawning a new PHP process.
+	 *
+	 * This replaces the current process with a new one to fully reload all code.
+	 * Falls back to in-process restart if pcntl_exec is not available.
+	 *
+	 * @param array{basic?: bool, watch?: string} $assoc_args Command arguments to preserve.
+	 */
+	private function restart_process( $assoc_args ) {
+		/**
+		 * @var array{0?: string} $argv
+		 */
+		global $argv;
+
+		// Check if pcntl_exec is available
+		if ( ! function_exists( 'pcntl_exec' ) ) {
+			WP_CLI::debug( 'pcntl_exec not available, falling back to in-process restart', 'shell' );
+			return;
+		}
+
+		// Build the command to restart wp shell with the same arguments
+		$php_binary = Utils\get_php_binary();
+
+		/**
+		 * @var array{argv: array{0?: string}} $_SERVER
+		 */
+
+		// Get the WP-CLI script path
+		$wp_cli_script = null;
+		if ( isset( $argv[0] ) ) {
+			$wp_cli_script = $argv[0];
+		} elseif ( isset( $_SERVER['argv'][0] ) ) {
+			$wp_cli_script = $_SERVER['argv'][0];
 		}
+
+		if ( ! $wp_cli_script ) {
+			WP_CLI::debug( 'Could not determine WP-CLI script path, falling back to in-process restart', 'shell' );
+			return;
+		}
+
+		// Build arguments array
+		$args = array( $php_binary, $wp_cli_script, 'shell' );
+
+		if ( Utils\get_flag_value( $assoc_args, 'basic' ) ) {
+			$args[] = '--basic';
+		}
+
+		$watch_path = Utils\get_flag_value( $assoc_args, 'watch', false );
+		if ( $watch_path ) {
+			$args[] = '--watch=' . $watch_path;
+		}
+
+		// Add global config values to preserve the environment after restart
+		$config = WP_CLI::get_runner()->config;
+		if ( isset( $config['path'] ) ) {
+			$args[] = '--path=' . $config['path'];
+		}
+		if ( isset( $config['user'] ) ) {
+			$args[] = '--user=' . $config['user'];
+		}
+		if ( isset( $config['url'] ) ) {
+			$args[] = '--url=' . $config['url'];
+		}
+
+		WP_CLI::log( 'Restarting shell in new process...' );
+
+		// Replace the current process with a new one
+		// Note: pcntl_exec does not return on success
+		pcntl_exec( $php_binary, array_slice( $args, 1 ) );
+
+		// If we reach here, exec failed
+		WP_CLI::warning( 'Failed to restart process, falling back to in-process restart' );
 	}
 }
diff --git a/src/WP_CLI/Shell/REPL.php b/src/WP_CLI/Shell/REPL.php

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@`
`12`	`12`	`}`
`13`	`13`	`],`
`14`	`14`	`"require": {`
`15`		`- "wp-cli/wp-cli": "^2.12"`
	`15`	`+ "wp-cli/wp-cli": "^2.13"`
`16`	`16`	`},`
`17`	`17`	`"require-dev": {`
`18`	`18`	`"wp-cli/wp-cli-tests": "^5"`