Standardize plaintext format name across CLI commands#6298
Standardize plaintext format name across CLI commands#6298imsameer-dev wants to merge 1 commit intowp-cli:mainfrom
Conversation
|
Hello! 👋 Thanks for opening this pull request! Please check out our contributing guidelines. We appreciate you taking the initiative to contribute to this project. Contributing isn't limited to just code. We encourage you to contribute in the way that best fits your abilities, by writing tutorials, giving a demo at your local meetup, helping other users with their support questions, or revising our documentation. Here are some useful Composer commands to get you started:
To run a single Behat test, you can use the following command: # Run all tests in a single file
composer behat features/some-feature.feature
# Run only a specific scenario (where 123 is the line number of the "Scenario:" title)
composer behat features/some-feature.feature:123You can find a list of all available Behat steps in our handbook. |
github-actions
bot
added
command:cli-alias
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
Standardizes the plain-text output format name across WP-CLI “cli” subcommands by renaming the var_export format to plaintext, aiming to make --format usage more consistent for users.
Changes:
- Update
wp cli param-dumpdocs and switch the implementation check fromvar_exporttoplaintext. - Update
wp cli alias listdocumented/validated--formatoptions to useplaintextinstead ofvar_export.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| php/commands/src/CLI_Command.php | Renames the param-dump format flag from var_export to plaintext in docs and runtime branching. |
| php/commands/src/CLI_Alias_Command.php | Renames the alias list format option in the docblock options list to plaintext (affects runtime validation). |
Comments suppressed due to low confidence (2)
php/commands/src/CLI_Command.php:828
- Changing the allowed
--formatvalues here drops support for the previously documentedvar_exportformat. Becauseoptions:in the docblock is used for runtime validation, existing scripts using--format=var_exportwill now fail with a generic “Invalid value specified for 'format'” error. Consider keepingvar_exportas an accepted alias for now (and mapping it toplaintext, optionally emitting a deprecation notice to STDERR) to avoid a hard breaking change while still standardizing the preferred name.
* [--format=<format>]
* : Render output in a particular format.
* ---
* default: json
* options:
* - plaintext
* - json
* ---
*
* ## EXAMPLES
*
* # Dump the list of global parameters.
* $ wp cli param-dump --format=plaintext
* array (
* 'path' =>
* array (
* 'runtime' => '=<path>',
* 'file' => '<path>',
* 'synopsis' => '',
* 'default' => NULL,
* 'multiple' => false,
* 'desc' => 'Path to the WordPress files.',
* ),
* 'url' =>
* array (
*
* @subcommand param-dump
*/
public function param_dump( $_, $assoc_args ) {
$spec = WP_CLI::get_configurator()->get_spec();
if ( Utils\get_flag_value( $assoc_args, 'with-values' ) ) {
$config = WP_CLI::get_configurator()->to_array();
// Copy current config values to $spec.
foreach ( $spec as $key => $value ) {
$current = null;
if ( isset( $config[0][ $key ] ) ) {
$current = $config[0][ $key ];
}
$spec[ $key ]['current'] = $current;
}
}
if ( 'plaintext' === Utils\get_flag_value( $assoc_args, 'format' ) ) {
var_export( $spec );
} else {
echo json_encode( $spec );
}
php/commands/src/CLI_Command.php:828
- There are existing Behat scenarios covering
wp cli param-dumpdefault behavior, but none that exercise the new--format=plaintextpath (or the expected behavior for the oldvar_exportname). Adding coverage for theplaintextformat (and whichever behavior you choose forvar_export: rejection vs deprecation alias) would help prevent regressions, especially sinceoptions:drives runtime validation.
* [--format=<format>]
* : Render output in a particular format.
* ---
* default: json
* options:
* - plaintext
* - json
* ---
*
* ## EXAMPLES
*
* # Dump the list of global parameters.
* $ wp cli param-dump --format=plaintext
* array (
* 'path' =>
* array (
* 'runtime' => '=<path>',
* 'file' => '<path>',
* 'synopsis' => '',
* 'default' => NULL,
* 'multiple' => false,
* 'desc' => 'Path to the WordPress files.',
* ),
* 'url' =>
* array (
*
* @subcommand param-dump
*/
public function param_dump( $_, $assoc_args ) {
$spec = WP_CLI::get_configurator()->get_spec();
if ( Utils\get_flag_value( $assoc_args, 'with-values' ) ) {
$config = WP_CLI::get_configurator()->to_array();
// Copy current config values to $spec.
foreach ( $spec as $key => $value ) {
$current = null;
if ( isset( $config[0][ $key ] ) ) {
$current = $config[0][ $key ];
}
$spec[ $key ]['current'] = $current;
}
}
if ( 'plaintext' === Utils\get_flag_value( $assoc_args, 'format' ) ) {
var_export( $spec );
} else {
echo json_encode( $spec );
}
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * [--format=<format>] | ||
| * : Render output in a particular format. | ||
| * --- | ||
| * default: yaml | ||
| * options: | ||
| * - yaml | ||
| * - json | ||
| * - var_export | ||
| * - plaintext | ||
| * --- |
There was a problem hiding this comment.
options: in this docblock is used for runtime validation, so removing var_export here will make wp cli alias list --format=var_export start failing even though the underlying printer would otherwise handle it. If backward compatibility is a goal, consider allowing var_export as an alias (and optionally warning that var_export is deprecated in favor of plaintext).
| * [--format=<format>] | ||
| * : Render output in a particular format. | ||
| * --- | ||
| * default: yaml | ||
| * options: | ||
| * - yaml | ||
| * - json | ||
| * - var_export | ||
| * - plaintext | ||
| * --- |
There was a problem hiding this comment.
There are Behat scenarios for wp cli alias list in YAML/JSON, but none for the newly documented --format=plaintext (and none asserting what should happen with the previous var_export name). Adding a scenario for --format=plaintext (and for var_export depending on whether you keep it as an alias or reject it) would lock in the intended behavior and validation.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request renames the var_export output format to plaintext within the CLI_Alias_Command and CLI_Command classes. The review feedback correctly identifies that these changes are backward-incompatible, as they remove the var_export option from allowed lists and logic. It is recommended to support both plaintext and var_export to avoid breaking existing user scripts and automation.
| * - yaml | ||
| * - json | ||
| * - var_export | ||
| * - plaintext |
There was a problem hiding this comment.
Removing var_export from the allowed options list is a breaking change. Existing scripts or aliases that use --format=var_export will now fail validation. It is recommended to keep var_export in the list to maintain backward compatibility, even if plaintext is the new preferred name.
* - plaintext
* - var_export| * default: json | ||
| * options: | ||
| * - var_export | ||
| * - plaintext |
There was a problem hiding this comment.
Similar to the alias list command, removing var_export from the options list here will break existing usage. It is recommended to keep it as an available option for backward compatibility.
* - plaintext
* - var_export
php/commands/src/CLI_Command.php
Outdated
| } | ||
|
|
||
| if ( 'var_export' === Utils\get_flag_value( $assoc_args, 'format' ) ) { | ||
| if ( 'plaintext' === Utils\get_flag_value( $assoc_args, 'format' ) ) { |
There was a problem hiding this comment.
This logic change strictly enforces the plaintext format name. Any existing automation using --format=var_export will now fall through to the else block and output JSON instead of the expected PHP var_export format. To avoid breaking changes, both format names should be accepted.
if ( in_array( Utils\target_flag_value( $assoc_args, 'format' ), [ 'plaintext', 'var_export' ], true ) ) {- Rename 'var_export' format to 'plaintext' in param-dump command - Rename 'var_export' format to 'plaintext' in alias list command - Update documentation and examples to reflect new format name - var_export() function output behavior remains the same The plaintext format name is more descriptive and consistent across both the param-dump and alias list commands.
swissspidy
changed the title
|
Note that there is already another PR that aims to resolve the same issue: |
Description
Standardizes the format parameter name across WP-CLI commands for consistency.
Changes
Motivation
Different commands were using different names for the same plain-text output format, creating inconsistency in the user experience. This PR standardizes on 'plaintext' which is more descriptive.
Testing
Please verify:
wp cli param-dump --format=plaintextworks as expectedwp cli alias list --format=plaintextworks as expectedvar_exportformat name is no longer accepted (or shows deprecation warning if applicable)Fixes #4774