Arguments

Advertisement

In a recent article, we learn about creating the first WP CLI Hello World program. If you read that article then you can skip some below steps.

Now, We are going to understand the WP CLI arguments or $args parameter from the WP CLI command.

Note: In this post, I’m focusing only on the main concepts. So, Not making the translation ready strings, not doing sanitization & escaping, also not adding class/function documentation, etc. Because I think beginners will not confuse the code.

E.g. For a beginner the code echo 'Hello'; is more understandable than esc_html_e( 'Hello', 'textdomain' );.

First, we’ll create a simple plugin and then understand the $args.

Register WP CLI Command Register WP CLI Command

Register PHP class WordPress_Examples_WP_CLI e.g.

if ( ! class_exists( 'WordPress_Examples_WP_CLI' ) && class_exists( 'WP_CLI_Command' ) ) :
       class WordPress_Examples_WP_CLI extends WP_CLI_Command {

       }
endif;

Here,

We have registered a new class WordPress_Examples_WP_CLI and extend it with WP_CLI_Command.

Top ↑

Add Example Command Add Example Command

Now let’s register the examples. E.g.

       WP_CLI::add_command( 'examples', 'WordPress_Examples_WP_CLI' ); 

Here,

We have used the function WP_CLI::add_command() to register our examples command.

The function WP_CLI::add_command() accepts 2 parameters. First parameter is the command name. Which is examples in our case.

And second is a callback class which is WordPress_Examples_WP_CLI

Top ↑

Add arguments sub command Add arguments sub command

         public function arguments( $args, $assoc_args ) {
           WP_CLI::line( 'Hello' );
         }

Here,

We have added a function arguments() with two parameters.

  • $args contain the arguments.
  • $assoc_args contain the associate arguments.

Top ↑

Testing Testing

Open command prompt/terminal. Go to your WordPress setup. I have set up WordPress in D:\xampp\htdocs\dev.test

So, Execute the below commands:

  • cd D:\xampp\htdocs\dev.test
  • wp examples arguments

You can see the output something like below:

 ? wp examples arguments
 Hello

This command just shows the string Hello. Now, Let’s try some examples:

Example 1

public function arguments( $args, $assoc_args ) {
	WP_CLI::line( 'Hello' );
	WP_CLI::line( print_r( $args ) );
}

Let’s execute our command wp examples arguments.

? wp examples arguments
 Hello                  
 Array                  
 (                      
 )                      
 1

Here, After executing above command WP_CLI::line( print_r( $args ) ); print an empty array because we don’t have any arguments in our CLI command.

But, If instead of command wp examples arguments if we execute the command wp examples arguments one two three then output as below:

? wp examples arguments one two three
 Hello                                
 Array                                
 (                                    
     [0] => one                       
     [1] => two                       
     [2] => three                     
 )                                    
 1                                    

Here, Code WP_CLI::line( print_r( $args ) ); print an array of arguments.

In the next example, Let’s access the argument one by one in the code.

Example 2

public function arguments( $args, $assoc_args ) {
	WP_CLI::line( 'Hello' );
	WP_CLI::line( $args[0] );
	WP_CLI::line( $args[1] );
	WP_CLI::line( $args[2] );
}

Execute the command wp examples arguments one two three

? wp examples arguments one two three
 Hello
 one
 two
 three

Here,

  • WP_CLI::line( $args[0] ); contain the value one
  • WP_CLI::line( $args[1] ); contain the value two
  • WP_CLI::line( $args[2] ); contain the value three

Example 3

public function arguments( $args, $assoc_args ) {
	WP_CLI::line( 'Hello ' . $args[0] );
}

If we execute the command wp examples arguments then we get an error as below:

? wp examples arguments
 Notice: Undefined offset: 0 in D:\xampp\htdocs\dev.test\wp-content\plugins\wordpress-examples\wordpress-examples.php on line 11
 Hello

Now, Set some default values as below:

public function arguments( $args, $assoc_args ) {
	$value = isset( $args[0] ) ? $args[0] : 'World';
	WP_CLI::line( 'Hello ' . $value );
}

If we execute the command wp examples arguments then we get the output as below:

? wp examples arguments
 Hello World

If we execute the command wp examples arguments Mahesh then we get the output as below:

? wp examples arguments Mahesh
 Hello Mahesh

If we execute the command wp examples arguments Mahesh Waghmare then we get the output as below:

 ? wp examples arguments Mahesh Waghmare
Hello Mahesh 

Why? Because of It consider Mahesh and Waghmare as two different arguments.

We can contact the string in a double quote. So, the CLI command understands that the parameter is a single attribute.

E.g.

? wp examples arguments "Mahesh Waghmare"
 Hello Mahesh Waghmare

Top ↑

Using \WP_CLI\Utils\get_flag_value() Using \WP_CLI\Utils\get_flag_value()

WP CLI have some helper functions which are more useful while developing some commands.

The \WP_CLI\Utils\get_flag_value() is one of them which allow us to get the value of the $args.

Let’s see it with a below simple example.

public function arguments( $args, $assoc_args ) {
	$value = isset( $args[0] ) ? $args[0] : 'World';
	WP_CLI::line( 'Hello ' . $value );
	// With helper function \WP_CLI\Utils\get_flag_value().
	$first = \WP_CLI\Utils\get_flag_value( $args, 0, 'World' );
	WP_CLI::line( 'Hello ' . $value );
}

If we execute the command wp examples arguments then we see something like below:

? wp examples arguments
 Hello World
 Hello World

We get the same result because the code \WP_CLI\Utils\get_flag_value( $args, 0, 'World' );

  • $args contains the list of all arguments.
  • 0 is the index of the argument.
  • World is the default value if we have not passed any parameter for 0 index.

Understanding the $args (arguments) from the WP CLI Program.