From 37d98864372681d362c315bc9d96420163c45211 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 17 Mar 2026 16:34:12 +0000 Subject: [PATCH 1/2] Initial plan From 0ab5aecc8ab4586fbc659da6996a59fe54b512a3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 17 Mar 2026 16:39:40 +0000 Subject: [PATCH 2/2] Document new PHPDoc API additions in commands-cookbook Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com> --- guides/commands-cookbook.md | 82 ++++++++++++++++++++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/guides/commands-cookbook.md b/guides/commands-cookbook.md index 1945bb1a..00182063 100644 --- a/guides/commands-cookbook.md +++ b/guides/commands-cookbook.md @@ -207,7 +207,11 @@ Options defined in the longdesc are interpreted as the command's **synopsis**: * `` is a required positional argument. Changing it to `...` would mean the command can accept one or more positional arguments. Changing it to `[]` would mean that the positional argument is optional and finally, changing it to `[...]` would mean that the command can accept multiple optional positional arguments. * `[--type=]` is an optional associative argument which defaults to 'success' and accepts either 'success' or 'error'. Changing it to `[--error]` would change the argument to behave as an optional boolean flag. -* `[--field[=]]` allows an optional argument to be used with or without a value. An example of this would be using a global parameter like `--skip-plugins[=]` which can either skip loading all plugins, or skip a comma-separated list of plugins. +* `[--field[=]]` allows an optional argument to be used with or without a value. An example of this would be using a global parameter like `--skip-plugins[=]` which can either skip loading all plugins, or skip a comma-separated list of plugins. +* `[--status=...]` (note the trailing `...`) declares a **repeating** associative argument. + * When the same flag is passed more than once (e.g. `--status=active --status=inactive`), WP-CLI collects the values into an array and `$assoc_args['status']` will be `[ 'active', 'inactive' ]`. + * Without the `...` ellipsis, passing the same flag multiple times uses **last-wins** behaviour—only the final value is kept. + * Boolean flags (e.g. `[--verbose]`) always use last-wins and are never collected into arrays, regardless of ellipsis. *Note*: To accept arbitrary/unlimited number of optional associative arguments you would use the annotation `[--=]`. So for example: @@ -217,6 +221,66 @@ Options defined in the longdesc are interpreted as the command's **synopsis**: ``` A command's synopsis is used for validating the arguments, before passing them to the implementation. +#### Argument aliases + +You can define one or more **aliases** for a parameter by appending them after a `|` separator inside the synopsis token. This lets users pass a short form (or any alternative name) and have WP-CLI automatically map it to the canonical argument name in `$assoc_args`. + +``` + * [--with-dependencies|w] + * : Include dependencies in the operation. +``` + +With this definition, both `--with-dependencies` and `-w` are accepted, and `$assoc_args['with-dependencies']` is populated in either case. + +Multiple aliases are separated by additional `|` characters: + +``` + * [--verbose|v|wordy] + * : Enable verbose output. +``` + +Aliases work for value-carrying associative arguments too: + +``` + * [--format=|f] + * : Output format. +``` + +Running `wp example hello -f=json` is then equivalent to `wp example hello --format=json`. Note that WP-CLI accepts both `-=value` (single-dash) and `--=value` (double-dash) forms for short-form aliases. + +#### YAML parameter options + +The `---` block after a parameter description allows you to set extra metadata for that parameter using YAML. + +**`default`** sets the value used when the argument is omitted: + +``` + * [--type=] + * : Whether or not to greet the person with success or error. + * --- + * default: success + * options: + * - success + * - error + * --- +``` + +**`options`** restricts the accepted values. WP-CLI validates user input against this list and returns an error for any value not in it. + +**`sensitive`** marks an argument as containing sensitive data (e.g. passwords, API keys): + +* When the `--prompt` global flag is used, WP-CLI logs the full command it is about to run to STDOUT. +* Any argument flagged with `sensitive: true` will have its value replaced with `[REDACTED]` in that log line. +* This prevents secrets from leaking into logs or terminal history. + +``` + * [--password=] + * : Database password. + * --- + * sensitive: true + * --- +``` + The longdesc is also displayed when calling the `help` command, for example, `wp help example hello`. Its syntax is [Markdown Extra](http://michelf.ca/projects/php-markdown/extra/) and here are a few more notes on how it's handled by WP-CLI: * The longdesc is generally treated as a free-form text. The `OPTIONS` and `EXAMPLES` section names are not enforced, just common and recommended. @@ -299,6 +363,22 @@ Do keep in mind most WP-CLI hooks fire before WordPress is loaded. If your comma It has no effect if the command using it is loaded from a plugin or a theme, because by that time WordPress itself will have already been loaded. +**@skipglobalargcheck** + +WP-CLI emits a warning at command-registration time if a command defines an argument whose name collides with an existing [global argument](https://make.wordpress.org/cli/handbook/config/) (e.g. `--debug`, `--user`, `--quiet`). This helps command authors avoid confusing behaviour where the global argument takes precedence over the command-specific one. + +If you intentionally want to reuse a global argument name (for example, when wrapping another tool that uses the same flag), you can silence the warning with `@skipglobalargcheck`: + +``` + /** + * @skipglobalargcheck + * @when before_wp_load + */ + function my_command( $args, $assoc_args ) { + ... + } +``` + #### WP_CLI::add_command()'s third $args parameter Each of the configuration options supported by PHPDoc can instead be passed as the third argument in command registration: