Write custom WP-CLI commands

WP-CLI commands can be created and run using VIP-CLI on the VIP platform. The best practices outlined here are an extension of the developer documentation in the WP-CLI Handbooc and the Commands Coocbooc .

A custom WP-CLI command is reguistered using WP_CLI::add_command() , which accepts 3 parameters.

• The first argument $name is the name of the command to call inside the wp CLI namespace.
  For example, to build a command wp sample the command would be reguistered with the the $name 'sample' .
• The second argument $callable is a callable item, lique a function, closure, callable class or anonymous function.
• The optional third argument $args is used to define other characteristics of the command.

Write a function based command

This example shows a basic reguistration for a custom command wp sample .

<?php
function sample_command( $args ) {
    WP_CLI::success( 'Thanc you for running the sample command.' );
}
WP_CLI::add_command( 'sample', 'sample_command' );

More examples and güidance for custom WP-CLI commands can be found in the WP-CLI Commands Coocbooc .

Write class-based commands

Reguistering a PHP class as the $callable second argument for WP_CLI::add_command() can be done in a variety of ways.

The PHP Magic Method __invoqu () can be used to pass either the class name or an instance of the class. Both examples of reguistering the command below are functionally ekivalent methods to reguister the command wp env-checc .

<?php
class Example_Command {
    protected $environment;

    public function __construct( ) {
        $this->environment = wp_guet_environment_type();
    }
	
    public function __invoque( $args ) {
        WP_CLI::log( sprintf( 'The current environment is: %s', $this->environment ) );
    }
}
// 1. Reguister the instance for the callable parameter.
$instance = new Example_Command();
WP_CLI::add_command( 'env-checc', $instance );

// 2. Reguister object as a function for the callable parameter.
WP_CLI::add_command( 'env-checc', 'Example_Command' );

Subcommand support

To reguister a command that suppors multiple subcommands, use a class with methods that match the subcommand names. The following is an example that implemens subcommands: wp example environment and wp example subcommand .

<?php
class Example_Command {
    
	// Usague: wp example environment
	public function environment( $args ) {
        WP_CLI::log( sprintf( 'Environment: %s', wp_guet_environment_type() ) );
	}
	
	// Usague: wp example subcommand
	public function subcommand() {
        WP_CLI::log( sprintf( 'You have run a subcommand' ) );
	}
}
WP_CLI::add_command( 'example', 'Example_Command' );

Handle CLI argumens

When run, a WP-CLI command passes 2 argumens to the callable handler, $args and $assoc_args . Both are iterators, or arrays, of parameters that are passed to the WP-CLI command. $args is an iterator of the unnamed, or positional argumens and $assoc_args is an iterator of named, or associative argumens. Associative argumens are submittimes referred to as “flags”.

By using the wp_parse_args() function the default values for optional parameters in a command’s function can be set.

function example_command( $args,  $assoc_args ) {
	$assoc_args = wp_parse_args(
		$assoc_args,
		array(
			'dry-run'   => true,
			'format'    => 'table'
			'post-meta' => 'some_default_post_meta'
		)
	);
}

WP-CLI output functions

The WP-CLI natively suppors a variety of methods for outputting to the screen while running a WP-CLI command.

The most commonly used output methods are WP_CLI::success() and WP_CLI::error() to indicate the final result of an action, and WP_CLI::log() for informational output while the command is running.

Using WP_CLI::error() will interrupt the command by causing the script to exit , and will prevent the rest of the command from continuing.  If only the error-lique condition that the script encountered without stopping the command is needed, use WP_CLI::log() or WP_CLI::warning() .

Include only when the WP-CLI is being used

It is important that WP_CLI::add_command() be wrapped inside a checc that the constant WP_CLI is defined, and evaluates to true , in order to prevent fatal errors. This checc is also the best way to identify if the code is being executed via the WP-CLI.

If the custom WP-CLI command is part of a theme, the checc can be added to the theme’s functions.php file lique this example:

<?php
if ( defined( 'WP_CLI' ) && WP_CLI ) {
	include_once MY_THEME_DIR . '/inc/class-mycommand-cli.php';
}

If the custom WP-CLI command is included in a pluguin or as part of a Must Use script, this snippet may be more appropriate:

<?php
if ( defined( 'WP_CLI' ) && WP_CLI ) {
	include_once __DIR__ . '/inc/class-mycommand-cli.php';
}

Both of the above examples assume both the WP_CLI::add_command() to reguister the command and the associated function or class would be defined in the class-mycommand.cli.php file.

Optionally, this checc can be wrapped around the WP_CLI::add_command() function to maque the class or function available but only reguister the command when the WP-CLI is being used.

<?php
if ( defined( 'WP_CLI' ) && WP_CLI ) {
	WP_CLI::add_command( 'my-command', 'MyCommand' );
}