From c45c4222804ada753027fcc15be6c5ee2967df8c Mon Sep 17 00:00:00 2001 From: Isla Waters Date: Wed, 20 Mar 2024 11:59:31 -0400 Subject: [PATCH 1/9] Include any non default hook information in CompositeCommand This would be a first step towards addressing #5838 and including details on when a specific command is run in the handbook documentation. I've added the output to the help command as well so there will be parody between that and the handbook. --- php/WP_CLI/Dispatcher/CompositeCommand.php | 14 ++++++++++++++ php/commands/src/CLI_Command.php | 1 + php/commands/src/Help_Command.php | 4 ++++ templates/man.mustache | 6 ++++++ 4 files changed, 25 insertions(+) diff --git a/php/WP_CLI/Dispatcher/CompositeCommand.php b/php/WP_CLI/Dispatcher/CompositeCommand.php index 1715926811..bf85b77f29 100644 --- a/php/WP_CLI/Dispatcher/CompositeCommand.php +++ b/php/WP_CLI/Dispatcher/CompositeCommand.php @@ -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,17 @@ 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. * diff --git a/php/commands/src/CLI_Command.php b/php/commands/src/CLI_Command.php index adea80fbc3..541415fb7a 100644 --- a/php/commands/src/CLI_Command.php +++ b/php/commands/src/CLI_Command.php @@ -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 ) { diff --git a/php/commands/src/Help_Command.php b/php/commands/src/Help_Command.php index a617d95633..f08c5e7497 100644 --- a/php/commands/src/Help_Command.php +++ b/php/commands/src/Help_Command.php @@ -157,6 +157,10 @@ private static function get_initial_markdown( $command ) { if ( $alias ) { $binding['alias'] = $alias; } + $hook = $command->get_hook(); + if ( $hook ) { + $binding['hook'] = $hook; + } if ( $command->can_have_subcommands() ) { $binding['has-subcommands']['subcommands'] = self::render_subcommands( $command ); diff --git a/templates/man.mustache b/templates/man.mustache index fbb2e9bd6b..ece23b43ae 100644 --- a/templates/man.mustache +++ b/templates/man.mustache @@ -8,6 +8,12 @@ {{shortdesc}} {{/shortdesc}} +{{#hook}} +## HOOK + + {{hook}} + +{{/hook}} ## SYNOPSIS {{synopsis}} From 497ec5ae8b48498162d1446762d3c1a9d28ad387 Mon Sep 17 00:00:00 2001 From: Isla Waters Date: Fri, 26 Apr 2024 10:59:50 -0400 Subject: [PATCH 2/9] Use util helper for hook descriptions --- php/commands/src/Help_Command.php | 7 ++++--- php/utils.php | 24 ++++++++++++++++++++++++ templates/man.mustache | 6 ------ 3 files changed, 28 insertions(+), 9 deletions(-) diff --git a/php/commands/src/Help_Command.php b/php/commands/src/Help_Command.php index f08c5e7497..0fdefa5532 100644 --- a/php/commands/src/Help_Command.php +++ b/php/commands/src/Help_Command.php @@ -157,9 +157,10 @@ private static function get_initial_markdown( $command ) { if ( $alias ) { $binding['alias'] = $alias; } - $hook = $command->get_hook(); - if ( $hook ) { - $binding['hook'] = $hook; + $hook_name = $command->get_hook(); + $hook_description = $hook_name ? Utils\get_hook_description( $hook_name ) : null; + if ( $hook_description ) { + $binding['shortdesc'] .= "\n\nThis command runs when the '$hook_name' hook is called, $hook_description"; } if ( $command->can_have_subcommands() ) { diff --git a/php/utils.php b/php/utils.php index 2f1ca58523..27da22015b 100644 --- a/php/utils.php +++ b/php/utils.php @@ -1865,3 +1865,27 @@ 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; +} diff --git a/templates/man.mustache b/templates/man.mustache index ece23b43ae..fbb2e9bd6b 100644 --- a/templates/man.mustache +++ b/templates/man.mustache @@ -8,12 +8,6 @@ {{shortdesc}} {{/shortdesc}} -{{#hook}} -## HOOK - - {{hook}} - -{{/hook}} ## SYNOPSIS {{synopsis}} From a04d6fadd10d04f2d444f26201a76b7f7777e503 Mon Sep 17 00:00:00 2001 From: isla w Date: Fri, 26 Apr 2024 11:13:10 -0400 Subject: [PATCH 3/9] Update php/WP_CLI/Dispatcher/CompositeCommand.php Co-authored-by: Pascal Birchler --- php/WP_CLI/Dispatcher/CompositeCommand.php | 2 -- 1 file changed, 2 deletions(-) diff --git a/php/WP_CLI/Dispatcher/CompositeCommand.php b/php/WP_CLI/Dispatcher/CompositeCommand.php index bf85b77f29..07c5a62430 100644 --- a/php/WP_CLI/Dispatcher/CompositeCommand.php +++ b/php/WP_CLI/Dispatcher/CompositeCommand.php @@ -134,8 +134,6 @@ public function get_shortdesc() { public function get_hook() { return $this->hook; } - - /** * Set the short description for this composite command. * From 65aac151b955ebc8a47d1f6f82bfe89a961d1827 Mon Sep 17 00:00:00 2001 From: Isla Waters Date: Fri, 26 Apr 2024 11:36:21 -0400 Subject: [PATCH 4/9] Add behat tests --- features/help.feature | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/features/help.feature b/features/help.feature index 43a1202459..3cc3826c43 100644 --- a/features/help.feature +++ b/features/help.feature @@ -51,7 +51,19 @@ Feature: Get help about WP-CLI commands """ wp post list """ - And STDERR should be empty + And STDERR should be empty + + When I try `wp help db` + Then STDOUT should contain: + """ + This command runs when the 'after_wp_config_load' hook is called, after wp-config.php has been loaded into scope. + """ + + When I try `wp help db size` + Then STDOUT should contain: + """ + This command runs when the 'after_wp_load' hook is called, just after the WP load process has completed. + """ Scenario: Hide Global parameters when requested Given an empty directory From 9f57e825d47f4dd30bc59f23b8d5ed336e6f7ce9 Mon Sep 17 00:00:00 2001 From: Isla Waters Date: Fri, 26 Apr 2024 12:06:03 -0400 Subject: [PATCH 5/9] Specify number of columns in output This string can wrap depending on settings, so hardcode various column numbers for consistency. --- features/help.feature | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/features/help.feature b/features/help.feature index 3cc3826c43..8f109fdd4d 100644 --- a/features/help.feature +++ b/features/help.feature @@ -51,15 +51,16 @@ Feature: Get help about WP-CLI commands """ wp post list """ - And STDERR should be empty + And STDERR should be empty - When I try `wp help db` + When I try `COLUMNS=80 wp help db` Then STDOUT should contain: """ - This command runs when the 'after_wp_config_load' hook is called, after wp-config.php has been loaded into scope. + This command runs when the 'after_wp_config_load' hook is called, after + wp-config.php has been loaded into scope. """ - When I try `wp help db size` + When I try `COLUMNS=150 wp help db size` Then STDOUT should contain: """ This command runs when the 'after_wp_load' hook is called, just after the WP load process has completed. From 67b101fe23b6943aad34892993bba339b418713c Mon Sep 17 00:00:00 2001 From: isla w Date: Fri, 26 Apr 2024 16:57:12 -0400 Subject: [PATCH 6/9] Apply suggestions from code review Co-authored-by: Pascal Birchler --- php/WP_CLI/Dispatcher/CompositeCommand.php | 1 + php/utils.php | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/php/WP_CLI/Dispatcher/CompositeCommand.php b/php/WP_CLI/Dispatcher/CompositeCommand.php index 07c5a62430..c8408fd453 100644 --- a/php/WP_CLI/Dispatcher/CompositeCommand.php +++ b/php/WP_CLI/Dispatcher/CompositeCommand.php @@ -134,6 +134,7 @@ public function get_shortdesc() { public function get_hook() { return $this->hook; } + /** * Set the short description for this composite command. * diff --git a/php/utils.php b/php/utils.php index 27da22015b..6b448f8cab 100644 --- a/php/utils.php +++ b/php/utils.php @@ -1873,7 +1873,6 @@ function has_stdin() { * * @return string|null */ - function get_hook_description( $hook ) { $events = [ 'find_command_to_run_pre' => 'just before WP-CLI finds the command to run.', From 05ea4ec87429863abca8b0766970af3e24fa43ca Mon Sep 17 00:00:00 2001 From: Daniel Bachhuber Date: Fri, 26 Apr 2024 18:59:47 -0700 Subject: [PATCH 7/9] Tweak language and distinguish between root commands and subcommands --- features/help.feature | 9 ++++++--- php/commands/src/Help_Command.php | 6 +++++- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/features/help.feature b/features/help.feature index 8f109fdd4d..a47aa0b6fb 100644 --- a/features/help.feature +++ b/features/help.feature @@ -53,17 +53,20 @@ 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 try `COLUMNS=80 wp help db` Then STDOUT should contain: """ - This command runs when the 'after_wp_config_load' hook is called, after - wp-config.php has been loaded into scope. + Unless overridden, these commands run on the 'after_wp_config_load' hook, + after wp-config.php has been loaded into scope. """ When I try `COLUMNS=150 wp help db size` Then STDOUT should contain: """ - This command runs when the 'after_wp_load' hook is called, just after the WP load process has completed. + This command runs on the 'after_wp_load' hook, just after the WP load process has completed. """ Scenario: Hide Global parameters when requested diff --git a/php/commands/src/Help_Command.php b/php/commands/src/Help_Command.php index 0fdefa5532..f419d72808 100644 --- a/php/commands/src/Help_Command.php +++ b/php/commands/src/Help_Command.php @@ -160,7 +160,11 @@ private static function get_initial_markdown( $command ) { $hook_name = $command->get_hook(); $hook_description = $hook_name ? Utils\get_hook_description( $hook_name ) : null; if ( $hook_description ) { - $binding['shortdesc'] .= "\n\nThis command runs when the '$hook_name' hook is called, $hook_description"; + 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() ) { From bbc0218e3a3a8cd3a217fe8ffefcb67f70691fdc Mon Sep 17 00:00:00 2001 From: Daniel Bachhuber Date: Fri, 26 Apr 2024 19:01:56 -0700 Subject: [PATCH 8/9] `'after_wp_load'` is the standard hook, so don't need to mention it --- features/help.feature | 10 ++++++++-- php/commands/src/Help_Command.php | 2 +- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/features/help.feature b/features/help.feature index a47aa0b6fb..7a506195f6 100644 --- a/features/help.feature +++ b/features/help.feature @@ -63,10 +63,16 @@ Feature: Get help about WP-CLI commands after wp-config.php has been loaded into scope. """ - When I try `COLUMNS=150 wp help db size` + When I try `COLUMNS=150 wp help db check` Then STDOUT should contain: """ - This command runs on the 'after_wp_load' hook, just after the WP load process has completed. + This command runs on the 'after_wp_config_load' hook, after wp-config.php has been loaded into scope. + """ + + When I try `COLUMNS=150 wp help db size` + Then STDOUT should not contain: + """ + This command runs on the """ Scenario: Hide Global parameters when requested diff --git a/php/commands/src/Help_Command.php b/php/commands/src/Help_Command.php index f419d72808..b5fa08f240 100644 --- a/php/commands/src/Help_Command.php +++ b/php/commands/src/Help_Command.php @@ -159,7 +159,7 @@ private static function get_initial_markdown( $command ) { } $hook_name = $command->get_hook(); $hook_description = $hook_name ? Utils\get_hook_description( $hook_name ) : null; - if ( $hook_description ) { + 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 { From 19615c4f047673fe820ecc9838c6514ef362d489 Mon Sep 17 00:00:00 2001 From: Daniel Bachhuber Date: Fri, 26 Apr 2024 19:02:35 -0700 Subject: [PATCH 9/9] Use `When I run` when no errors are expected --- features/help.feature | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/features/help.feature b/features/help.feature index 7a506195f6..449eeabb40 100644 --- a/features/help.feature +++ b/features/help.feature @@ -56,20 +56,20 @@ Feature: Get help about WP-CLI commands Scenario: Include when the command is run if a non-standard hook. Given an empty directory - When I try `COLUMNS=80 wp help db` + 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 try `COLUMNS=150 wp help db check` + 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 try `COLUMNS=150 wp help db size` + When I run `COLUMNS=150 wp help db size` Then STDOUT should not contain: """ This command runs on the