Understanding the WP CLI associate arguments

Advertisement

In a recent article, we learn about WP CLI arguments or $args. If you have not read it yet then you can first read the article Understanding the WP CLI arguments.

Below is some code which may you already have done in a recent article. So, you can skip some below steps.

Okay. In this article, we are going to understand the $assoc_args parameter.

Let’s create a simple plugin and then understand the $assoc_args.

Create Empty Plugin Create Empty Plugin

  • Create a new folder wordpress-examples into plugins directory /wp-content/plugins/
  • Create a file wordpress-examples.php and add the below code into it.
<?php
 /**
 Plugin Name: WordPress Examples
 */ 

Note: If you want to add some additional information then you can get it from gist snippet – WordPress Complete Plugin Readme File.

Now you can see our WordPress Examples plugin exists into the plugins list.

  • Now, Activate the plugin.

Top ↑

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. The 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 associated_arguments sub command Add associated_arguments sub command

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

Here,

We have added a function associated_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 associated_arguments

You can see the output something like below:

 位 wp examples associated_arguments
 Hello

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

Example 1

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

Let’s execute our command wp examples associated_arguments.

位 wp examples associated_arguments
 Hello                  
 Array                  
 (                      
 )                      
 1

Oh! This is something similar like $args. Right, Becase of the $assoc_args is also an array.

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

But, If instead of command wp examples associated_arguments if we execute the command wp examples associated_arguments --one=One --two=Two --three=Three then output as below:

位 wp examples associated_arguments --one=One --two=One --three=Three
 Hello                                
 Array                                
 (
     [one] => One
     [two] => Two
     [three] => Three
 )                                 
 1                                    

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

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

Example 2

public function associated_arguments( $args, $assoc_args ) {

	WP_CLI::line( 'Hello' );
	WP_CLI::line( $assoc_args['one'] );
	WP_CLI::line( $assoc_args['two'] );
	WP_CLI::line( $assoc_args['three'] );

}

Execute the command wp examples associated_arguments --one=One --two=Two --three=Three

位 wp examples associated_arguments --one=One --two=Two --three=Three
 Hello
 one
 two
 three

Here,

  • WP_CLI::line( $assoc_args['one'] ); contain the value one
  • WP_CLI::line( $assoc_args['two] ); contain the value two
  • WP_CLI::line( $assoc_args['three] ); contain the value three

Example 3

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

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

位 wp examples associated_arguments
 Notice: Undefined index: name in D:\xampp\htdocs\dev.test\wp-content\plugins\wordpress-examples\wordpress-examples.php on line 12
 Hello

Now, Set some default values as below:

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

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

位 wp examples associated_arguments
 Hello World

If we execute the command wp examples associated_arguments --name=Mahesh then we get the output as below:

位 wp examples associated_arguments --name=Mahesh
 Hello Mahesh

If we execute the command wp examples associated_arguments --name=Mahesh Waghmare then we get the output as below:

 位 wp examples associated_arguments --name=Mahesh Waghmare
Hello Mahesh 

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

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

E.g.

位 wp examples associated_arguments --name="Mahesh Waghmare"
 Hello Mahesh Waghmare

Top ↑

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

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

The WP_CLIUtilsget_flag_value() is one of them which allow us to get the value of the $assoc_args.

Let’s see it with a below simple example.

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

	// With helper function WP_CLIUtilsget_flag_value().
	$first = \WP_CLI\Utils\get_flag_value( $assoc_args, 'name', 'World' );
	WP_CLI::line( 'Hello ' . $value );
}

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

位 wp examples associated_arguments
 Hello World
 Hello World

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

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

Understanding the WP CLI associate arguments.

One thought on “Understanding the WP CLI associate arguments

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: