Associate Arguments

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.

Tweet