When working with WP CLI, I often have data to output and instead of looking up how to do it each time, I wanted to make myself some notes.
WP_CLI\Utils\format_items()
The WP_CLI\Utils\format_items() command takes a set of data and outputs it in your desired format (e.g. a table).
WP_CLI\Utils\format_items( $format, $items, $fields );
The formats available are:
tablejsoncsvyamlidscount
$items is an array of key/value arrays
$fields is comma separated string of keys to display as headings (or an array of keys)
Example WP_CLI\Utils\format_items()
WP_CLI::add_command( 'example1', function( $args, $assoc_args ) {
$items = [
[
'name' => 'Tron',
'team' => 'Users',
'score' => 111,
],
[
'name' => 'Archimedes',
'team' => 'Sicilians',
'score' => 114,
],
];
WP_CLI\Utils\format_items(
'table',
$items,
[ 'name', 'team', 'score' ]
);
} );
Output
$ wp example1
+------------+-----------+-------+
| name | team | score |
+------------+-----------+-------+
| Tron | Users | 111 |
| Archimedes | Sicilians | 114 |
+------------+-----------+-------+
WP_CLI\Utils\get_flag_value()
A WP CLI command can accept arguments in two ways, as positional arguments and as flag arguments. (See WP CLI Accepting Arguments). We’re going to look at flag arguments.
Positional arguments appear after your command, e.g. stop-emails in the following command
wp plugin get stop-emails
Flag arguments are prefixed with a double-dash (--), e.g. --format=csv or --fields=name,version,status
wp plugin list --format=csv --fields=name,version,status
The WP_CLI\Utils\get_flag_value() function helps with using flag arguments.
Format Flag Argument
The core WP CLI commands accept a format argument, so you can define the format at run time. You can get this same behavior in your own code.
The following will give you the format value defined on the command line, while defaulting to table if no value is defined.
$format = WP_CLI\Utils\get_flag_value( $assoc_args, 'format', 'table' );
Fields
The core WP CLI commands accept a fields argument, so you can define the fields you want to display. You can get this same behavior in your own code.
The following will give you a string of fields defined on the command line, while using a default set of values if it is not defined on the command line.
$fields = WP_CLI\Utils\get_flag_value( $assoc_args, 'fields', [ 'name', 'team', 'score' ] );
Example
This example will give us the same default output as our original code. However, it will also support both the format and fields flag arguments, allowing us to customize out output via command line parameters.
WP_CLI::add_command( 'example2', function( $args, $assoc_args ) {
$items = [
[
'name' => 'Tron',
'team' => 'Users',
'score' => 111,
],
[
'name' => 'Archimedes',
'team' => 'Sicilians',
'score' => 114,
],
];
$format = WP_CLI\Utils\get_flag_value( $assoc_args, 'format', 'table' );
$fields = WP_CLI\Utils\get_flag_value( $assoc_args, 'fields', [ 'name', 'team', 'score' ] );
WP_CLI\Utils\format_items(
$format,
$items,
$fields
);
} );
Output
$ wp example
+------------+-----------+-------+
| name | team | score |
+------------+-----------+-------+
| Tron | Users | 111 |
| Archimedes | Sicilians | 114 |
+------------+-----------+-------+
$ wp example2 --format=yaml --fields=name,score
---
-
name: Tron
score: 111
-
name: Archimedes
score: 114
Add example using
idsfor format. The `–format=ids` is an odd case where the items are displayed as a list of values with spaces in between.Try it with
In order to get this behavior in our own code (assuming we have
idas one of our fields) we can add this conditional that checks if format isids, in which case we use array_map() to transform each item array into a single value (theidvalue).