wp-cli · danielbachhuber · Apr 27, 2024 · Mar 20, 2024 · Apr 26, 2024 · Apr 26, 2024
@@ -53,6 +53,28 @@ Feature: Get help about WP-CLI commands
       """
     And STDERR should be empty
 
+  Scenario: Include when the command is run if a non-standard hook.
+    Given an empty directory
+
+    When I run `COLUMNS=80 wp help db`
+    Then STDOUT should contain:
+      """
+        Unless overridden, these commands run on the 'after_wp_config_load' hook,
+        after wp-config.php has been loaded into scope.
+      """
+
+    When I run `COLUMNS=150 wp help db check`
+    Then STDOUT should contain:
+      """
+      This command runs on the 'after_wp_config_load' hook, after wp-config.php has been loaded into scope.
+      """
+
+    When I run `COLUMNS=150 wp help db size`
+    Then STDOUT should not contain:
+      """
+      This command runs on the
+      """
+
   Scenario: Hide Global parameters when requested
     Given an empty directory
 

@@ -18,6 +18,7 @@ class CompositeCommand {
 	protected $shortdesc;
 	protected $longdesc;
 	protected $synopsis;
+	protected $hook;
 	protected $docparser;
 
 	protected $parent;
@@ -38,9 +39,11 @@ public function __construct( $parent, $name, $docparser ) {
 		$this->shortdesc = $docparser->get_shortdesc();
 		$this->longdesc  = $docparser->get_longdesc();
 		$this->docparser = $docparser;
+		$this->hook      = $parent->get_hook();
 
 		$when_to_invoke = $docparser->get_tag( 'when' );
 		if ( $when_to_invoke ) {
+			$this->hook = $when_to_invoke;
 			WP_CLI::get_runner()->register_early_invoke( $when_to_invoke, $this );
 		}
 	}
@@ -122,6 +125,16 @@ public function get_shortdesc() {
 		return $this->shortdesc;
 	}
 
+	/**
+	 * Get the hook name for this composite
+	 * command.
+	 *
+	 * @return string
+	 */
+	public function get_hook() {
+		return $this->hook;
+	}
+
 	/**
 	 * Set the short description for this composite command.
 	 *

@@ -39,6 +39,7 @@ private function command_to_array( $command ) {
 			'name'        => $command->get_name(),
 			'description' => $command->get_shortdesc(),
 			'longdesc'    => $command->get_longdesc(),
+			'hook'        => $command->get_hook(),
 		];
 
 		foreach ( $command->get_subcommands() as $subcommand ) {

@@ -157,6 +157,15 @@ private static function get_initial_markdown( $command ) {
 		if ( $alias ) {
 			$binding['alias'] = $alias;
 		}
+		$hook_name        = $command->get_hook();
+		$hook_description = $hook_name ? Utils\get_hook_description( $hook_name ) : null;
+		if ( $hook_description && 'after_wp_load' !== $hook_name ) {
+			if ( $command->can_have_subcommands() ) {
+				$binding['shortdesc'] .= "\n\nUnless overridden, these commands run on the '$hook_name' hook, $hook_description";
+			} else {
+				$binding['shortdesc'] .= "\n\nThis command runs on the '$hook_name' hook, $hook_description";
+			}
+		}
 
 		if ( $command->can_have_subcommands() ) {
 			$binding['has-subcommands']['subcommands'] = self::render_subcommands( $command );

@@ -1865,3 +1865,26 @@ function has_stdin() {
 
 	return 1 === $streams;
 }
+
+/**
+ * Return description of WP_CLI hooks used in @when tag
+ *
+ *  @param string $hook Name of WP_CLI hook
+ *
+ * @return string|null
+ */
+function get_hook_description( $hook ) {
+	$events = [
+		'find_command_to_run_pre'     => 'just before WP-CLI finds the command to run.',
+		'before_registering_contexts' => 'before the contexts are registered.',
+		'before_wp_load'              => 'just before the WP load process begins.',
+		'before_wp_config_load'       => 'after wp-config.php has been located.',
+		'after_wp_config_load'        => 'after wp-config.php has been loaded into scope.',
+		'after_wp_load'               => 'just after the WP load process has completed.',
+	];
+
+	if ( array_key_exists( $hook, $events ) ) {
+		return $events[ $hook ];
+	}
+	return null;
+}