• Skip to primary navigation
  • Skip to main content
Sal Ferrarello
  • About Sal Ferrarello
  • Speaking
  • Connect
    Mastodon GitHub Twitter (inactive)
You are here: Home / Draft / WP CLI Output Results

WP CLI Output Results

Last updated on January 31, 2019 by Sal Ferrarello

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:

  • table
  • json
  • csv
  • yaml
  • ids
  • count

$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
Sal Ferrarello
Sal Ferrarello (@salcode)
Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.

Share this post:

Share on TwitterShare on FacebookShare on LinkedInShare on EmailShare on Reddit
Warning! This is a draft, not a finalized post. See full draft disclosure.

Filed Under: Draft, Programming Tagged With: wp-cli

Reader Interactions

Comments

  1. Sal Ferrarello says

    March 15, 2019 at 3:14 pm

    Add example using ids for 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

    
    wp post list --posts_per_page=5 --format=ids
    

    In order to get this behavior in our own code (assuming we have id as one of our fields) we can add this conditional that checks if format is ids, in which case we use array_map() to transform each item array into a single value (the id value).

    
    $items = [
    	[
    		'id' => 1,
    		'name' => 'Tron',
    		'team' => 'Users',
    		'score' => 111,
    	],
    	[
    		'id' => 2,
    		'name' => 'Archimedes',
    		'team' => 'Sicilians',
    		'score' => 114,
    	],
    ];
    $default_fields = [
    	'id',
    	'name',
    	'team',
    	'score',
    ];
    $format = Utils\get_flag_value( $assoc_args, 'format', 'table' );
    $fields = WP_CLI\Utils\get_flag_value( $assoc_args, 'fields', $default_fields );
    if ( 'ids' === $format ) {
    	$items = array_map( function( $item ) { return $item['id']; }, $result );
    }
    Utils\format_items(
    	$format,
    	$items,
    	$fields
    );
    
    Reply

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Copyright © 2023 · Bootstrap4 Genesis on Genesis Framework · WordPress · Log in