Update profile commands examples (#189)

* Update profile commands examples * Update orderby argument description in profile commands * Update profile feature tests
wp-cli · Apr 5, 2024 · df98093 · df98093
1 parent 26107b5
commit df98093
Show file tree

Hide file tree

Showing 3 changed files with 163 additions and 85 deletions.
diff --git a/README.md b/README.md
@@ -24,7 +24,7 @@ This package implements the following commands:
 Profile each stage of the WordPress load process (bootstrap, main_query, template).
 
 ~~~
-wp profile stage [<stage>] [--all] [--spotlight] [--url=<url>] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<orderby>]
+wp profile stage [<stage>] [--all] [--spotlight] [--url=<url>] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<fields>]
 ~~~
 
 When WordPress handles a request from a browser, it’s essentially
@@ -38,36 +38,6 @@ into the primary WP_Query.
 * **template** is where WordPress determines which theme template to
 render based on the main query, and renders it.
 
-```
-# `wp profile stage` gives an overview of each stage.
-$ wp profile stage --fields=stage,time,cache_ratio
-+------------+---------+-------------+
-| stage      | time    | cache_ratio |
-+------------+---------+-------------+
-| bootstrap  | 0.7994s | 93.21%      |
-| main_query | 0.0123s | 94.29%      |
-| template   | 0.792s  | 91.23%      |
-+------------+---------+-------------+
-| total (3)  | 1.6037s | 92.91%      |
-+------------+---------+-------------+
-
-# Then, dive into hooks for each stage with `wp profile stage <stage>`
-$ wp profile stage bootstrap --fields=hook,time,cache_ratio --spotlight
-+--------------------------+---------+-------------+
-| hook                     | time    | cache_ratio |
-+--------------------------+---------+-------------+
-| muplugins_loaded:before  | 0.2335s | 40%         |
-| muplugins_loaded         | 0.0007s | 50%         |
-| plugins_loaded:before    | 0.2792s | 77.63%      |
-| plugins_loaded           | 0.1502s | 100%        |
-| after_setup_theme:before | 0.068s  | 100%        |
-| init                     | 0.2643s | 96.88%      |
-| wp_loaded:after          | 0.0377s |             |
-+--------------------------+---------+-------------+
-| total (7)                | 1.0335s | 77.42%      |
-+--------------------------+---------+-------------+
-```
-
 **OPTIONS**
 
 	[<stage>]
@@ -105,8 +75,38 @@ $ wp profile stage bootstrap --fields=hook,time,cache_ratio --spotlight
 		  - DESC
 		---
 
-	[--orderby=<orderby>]
-		Order by fields.
+	[--orderby=<fields>]
+		Set orderby which field.
+
+**EXAMPLES**
+
+    # See an overview for each stage of the load process.
+    $ wp profile stage --fields=stage,time,cache_ratio
+    +------------+---------+-------------+
+    | stage      | time    | cache_ratio |
+    +------------+---------+-------------+
+    | bootstrap  | 0.7994s | 93.21%      |
+    | main_query | 0.0123s | 94.29%      |
+    | template   | 0.792s  | 91.23%      |
+    +------------+---------+-------------+
+    | total (3)  | 1.6037s | 92.91%      |
+    +------------+---------+-------------+
+
+    # Dive into hook performance for a given stage.
+    $ wp profile stage bootstrap --fields=hook,time,cache_ratio --spotlight
+    +--------------------------+---------+-------------+
+    | hook                     | time    | cache_ratio |
+    +--------------------------+---------+-------------+
+    | muplugins_loaded:before  | 0.2335s | 40%         |
+    | muplugins_loaded         | 0.0007s | 50%         |
+    | plugins_loaded:before    | 0.2792s | 77.63%      |
+    | plugins_loaded           | 0.1502s | 100%        |
+    | after_setup_theme:before | 0.068s  | 100%        |
+    | init                     | 0.2643s | 96.88%      |
+    | wp_loaded:after          | 0.0377s |             |
+    +--------------------------+---------+-------------+
+    | total (7)                | 1.0335s | 77.42%      |
+    +--------------------------+---------+-------------+
 
 
 
@@ -115,7 +115,7 @@ $ wp profile stage bootstrap --fields=hook,time,cache_ratio --spotlight
 Profile key metrics for WordPress hooks (actions and filters).
 
 ~~~
-wp profile hook [<hook>] [--all] [--spotlight] [--url=<url>] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<orderby>]
+wp profile hook [<hook>] [--all] [--spotlight] [--url=<url>] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<fields>]
 ~~~
 
 In order to profile callbacks on a specific hook, the action or filter
@@ -158,8 +158,26 @@ will need to execute during the course of the request.
 		  - DESC
 		---
 
-	[--orderby=<orderby>]
-		Order by fields.
+	[--orderby=<fields>]
+		Set orderby which field.
+
+**EXAMPLES**
+
+    # Profile a hook.
+    $ wp profile hook template_redirect --fields=callback,cache_hits,cache_misses
+    +--------------------------------+------------+--------------+
+    | callback                       | cache_hits | cache_misses |
+    +--------------------------------+------------+--------------+
+    | _wp_admin_bar_init()           | 0          | 0            |
+    | wp_old_slug_redirect()         | 0          | 0            |
+    | redirect_canonical()           | 5          | 0            |
+    | WP_Sitemaps->render_sitemaps() | 0          | 0            |
+    | rest_output_link_header()      | 3          | 0            |
+    | wp_shortlink_header()          | 0          | 0            |
+    | wp_redirect_admin_locations()  | 0          | 0            |
+    +--------------------------------+------------+--------------+
+    | total (7)                      | 8          | 0            |
+    +--------------------------------+------------+--------------+
 
 
 
@@ -168,7 +186,7 @@ will need to execute during the course of the request.
 Profile arbitrary code execution.
 
 ~~~
-wp profile eval <php-code> [--hook[=<hook>]] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<orderby>]
+wp profile eval <php-code> [--hook[=<hook>]] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<fields>]
 ~~~
 
 Code execution happens after WordPress has loaded entirely, which means
@@ -206,8 +224,18 @@ current theme.
 		  - DESC
 		---
 
-	[--orderby=<orderby>]
-		Order by fields.
+	[--orderby=<fields>]
+		Set orderby which field.
+
+**EXAMPLES**
+
+    # Profile a function that makes one HTTP request.
+    $ wp profile eval 'wp_remote_get( "https://www.apple.com/" );' --fields=time,cache_ratio,request_count
+    +---------+-------------+---------------+
+    | time    | cache_ratio | request_count |
+    +---------+-------------+---------------+
+    | 0.1009s | 100%        | 1             |
+    +---------+-------------+---------------+
 
 
 
@@ -216,7 +244,7 @@ current theme.
 Profile execution of an arbitrary file.
 
 ~~~
-wp profile eval-file <file> [--hook[=<hook>]] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<orderby>]
+wp profile eval-file <file> [--hook[=<hook>]] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<fields>]
 ~~~
 
 File execution happens after WordPress has loaded entirely, which means
@@ -254,8 +282,18 @@ current theme.
 		  - DESC
 		---
 
-	[--orderby=<orderby>]
-		Order by fields.
+	[--orderby=<fields>]
+		Set orderby which field.
+
+**EXAMPLES**
+
+    # Profile from a file `request.php` containing `<?php wp_remote_get( "https://www.apple.com/" );`.
+    $ wp profile eval-file request.php --fields=time,cache_ratio,request_count
+    +---------+-------------+---------------+
+    | time    | cache_ratio | request_count |
+    +---------+-------------+---------------+
+    | 0.1009s | 100%        | 1             |
+    +---------+-------------+---------------+
 
 ## Installing
 

diff --git a/features/profile.feature b/features/profile.feature
@@ -6,10 +6,10 @@ Feature: Basic profile usage
     When I run `wp profile`
     Then STDOUT should be:
       """
-      usage: wp profile eval <php-code> [--hook[=<hook>]] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<orderby>]
-         or: wp profile eval-file <file> [--hook[=<hook>]] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<orderby>]
-         or: wp profile hook [<hook>] [--all] [--spotlight] [--url=<url>] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<orderby>]
-         or: wp profile stage [<stage>] [--all] [--spotlight] [--url=<url>] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<orderby>]
+      usage: wp profile eval <php-code> [--hook[=<hook>]] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<fields>]
+         or: wp profile eval-file <file> [--hook[=<hook>]] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<fields>]
+         or: wp profile hook [<hook>] [--all] [--spotlight] [--url=<url>] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<fields>]
+         or: wp profile stage [<stage>] [--all] [--spotlight] [--url=<url>] [--fields=<fields>] [--format=<format>] [--order=<order>] [--orderby=<fields>]
 
       See 'wp help profile <command>' for more information on a specific command.
       """

diff --git a/src/Command.php b/src/Command.php
@@ -37,6 +37,8 @@
  *     +--------------------------+---------+-------------+
  *     | total (7)                | 1.0335s | 77.42%      |
  *     +--------------------------+---------+-------------+
+ *
+ * @package wp-cli
  */
 class Command {
 
@@ -54,36 +56,6 @@ class Command {
 	 * * **template** is where WordPress determines which theme template to
 	 * render based on the main query, and renders it.
 	 *
-	 * ```
-	 * # `wp profile stage` gives an overview of each stage.
-	 * $ wp profile stage --fields=stage,time,cache_ratio
-	 * +------------+---------+-------------+
-	 * | stage      | time    | cache_ratio |
-	 * +------------+---------+-------------+
-	 * | bootstrap  | 0.7994s | 93.21%      |
-	 * | main_query | 0.0123s | 94.29%      |
-	 * | template   | 0.792s  | 91.23%      |
-	 * +------------+---------+-------------+
-	 * | total (3)  | 1.6037s | 92.91%      |
-	 * +------------+---------+-------------+
-	 *
-	 * # Then, dive into hooks for each stage with `wp profile stage <stage>`
-	 * $ wp profile stage bootstrap --fields=hook,time,cache_ratio --spotlight
-	 * +--------------------------+---------+-------------+
-	 * | hook                     | time    | cache_ratio |
-	 * +--------------------------+---------+-------------+
-	 * | muplugins_loaded:before  | 0.2335s | 40%         |
-	 * | muplugins_loaded         | 0.0007s | 50%         |
-	 * | plugins_loaded:before    | 0.2792s | 77.63%      |
-	 * | plugins_loaded           | 0.1502s | 100%        |
-	 * | after_setup_theme:before | 0.068s  | 100%        |
-	 * | init                     | 0.2643s | 96.88%      |
-	 * | wp_loaded:after          | 0.0377s |             |
-	 * +--------------------------+---------+-------------+
-	 * | total (7)                | 1.0335s | 77.42%      |
-	 * +--------------------------+---------+-------------+
-	 * ```
-	 *
 	 * ## OPTIONS
 	 *
 	 * [<stage>]
@@ -121,8 +93,38 @@ class Command {
 	 *   - DESC
 	 * ---
 	 *
-	 * [--orderby=<orderby>]
-	 * : Order by fields.
+	 * [--orderby=<fields>]
+	 * : Set orderby which field.
+	 *
+	 * ## EXAMPLES
+	 *
+	 *     # See an overview for each stage of the load process.
+	 *     $ wp profile stage --fields=stage,time,cache_ratio
+	 *     +------------+---------+-------------+
+	 *     | stage      | time    | cache_ratio |
+	 *     +------------+---------+-------------+
+	 *     | bootstrap  | 0.7994s | 93.21%      |
+	 *     | main_query | 0.0123s | 94.29%      |
+	 *     | template   | 0.792s  | 91.23%      |
+	 *     +------------+---------+-------------+
+	 *     | total (3)  | 1.6037s | 92.91%      |
+	 *     +------------+---------+-------------+
+	 *
+	 *     # Dive into hook performance for a given stage.
+	 *     $ wp profile stage bootstrap --fields=hook,time,cache_ratio --spotlight
+	 *     +--------------------------+---------+-------------+
+	 *     | hook                     | time    | cache_ratio |
+	 *     +--------------------------+---------+-------------+
+	 *     | muplugins_loaded:before  | 0.2335s | 40%         |
+	 *     | muplugins_loaded         | 0.0007s | 50%         |
+	 *     | plugins_loaded:before    | 0.2792s | 77.63%      |
+	 *     | plugins_loaded           | 0.1502s | 100%        |
+	 *     | after_setup_theme:before | 0.068s  | 100%        |
+	 *     | init                     | 0.2643s | 96.88%      |
+	 *     | wp_loaded:after          | 0.0377s |             |
+	 *     +--------------------------+---------+-------------+
+	 *     | total (7)                | 1.0335s | 77.42%      |
+	 *     +--------------------------+---------+-------------+
 	 *
 	 * @when before_wp_load
 	 */
@@ -227,8 +229,26 @@ public function stage( $args, $assoc_args ) {
 	 *   - DESC
 	 * ---
 	 *
-	 * [--orderby=<orderby>]
-	 * : Order by fields.
+	 * [--orderby=<fields>]
+	 * : Set orderby which field.
+	 *
+	 * ## EXAMPLES
+	 *
+	 *     # Profile a hook.
+	 *     $ wp profile hook template_redirect --fields=callback,cache_hits,cache_misses
+	 *     +--------------------------------+------------+--------------+
+	 *     | callback                       | cache_hits | cache_misses |
+	 *     +--------------------------------+------------+--------------+
+	 *     | _wp_admin_bar_init()           | 0          | 0            |
+	 *     | wp_old_slug_redirect()         | 0          | 0            |
+	 *     | redirect_canonical()           | 5          | 0            |
+	 *     | WP_Sitemaps->render_sitemaps() | 0          | 0            |
+	 *     | rest_output_link_header()      | 3          | 0            |
+	 *     | wp_shortlink_header()          | 0          | 0            |
+	 *     | wp_redirect_admin_locations()  | 0          | 0            |
+	 *     +--------------------------------+------------+--------------+
+	 *     | total (7)                      | 8          | 0            |
+	 *     +--------------------------------+------------+--------------+
 	 *
 	 * @when before_wp_load
 	 */
@@ -311,8 +331,18 @@ public function hook( $args, $assoc_args ) {
 	 *   - DESC
 	 * ---
 	 *
-	 * [--orderby=<orderby>]
-	 * : Order by fields.
+	 * [--orderby=<fields>]
+	 * : Set orderby which field.
+	 *
+	 * ## EXAMPLES
+	 *
+	 *     # Profile a function that makes one HTTP request.
+	 *     $ wp profile eval 'wp_remote_get( "https://www.apple.com/" );' --fields=time,cache_ratio,request_count
+	 *     +---------+-------------+---------------+
+	 *     | time    | cache_ratio | request_count |
+	 *     +---------+-------------+---------------+
+	 *     | 0.1009s | 100%        | 1             |
+	 *     +---------+-------------+---------------+
 	 *
 	 * @subcommand eval
 	 */
@@ -325,7 +355,7 @@ public function eval_( $args, $assoc_args ) {
 		self::profile_eval_ish(
 			$assoc_args,
 			function () use ( $statement ) {
-				eval( $statement ); // phpcs:ignore Squiz.PHP.Eval.Discouraged -- no other way oround here
+				eval( $statement ); // phpcs:ignore Squiz.PHP.Eval.Discouraged -- no other way around here
 			},
 			$order,
 			$orderby
@@ -370,8 +400,18 @@ function () use ( $statement ) {
 	 *   - DESC
 	 * ---
 	 *
-	 * [--orderby=<orderby>]
-	 * : Order by fields.
+	 * [--orderby=<fields>]
+	 * : Set orderby which field.
+	 *
+	 * ## EXAMPLES
+	 *
+	 *     # Profile from a file `request.php` containing `<?php wp_remote_get( "https://www.apple.com/" );`.
+	 *     $ wp profile eval-file request.php --fields=time,cache_ratio,request_count
+	 *     +---------+-------------+---------------+
+	 *     | time    | cache_ratio | request_count |
+	 *     +---------+-------------+---------------+
+	 *     | 0.1009s | 100%        | 1             |
+	 *     +---------+-------------+---------------+
 	 *
 	 * @subcommand eval-file
 	 */