WordPress

How to add a custom WP CLI command in WordPress

By August 23, 2017 No Comments
WP CLI add custom command WordPress

What is WP CLI?

WP-CLI is the official command-line interface for WordPress. It helps developers automate tasks, and increase their productivity. It opens up a whole array of opportunities once you’ve started using it.

It comes with a whole bunch of useful commands like cache clearing, cron, media management, user management, and many other useful commands.

But if you’re building a custom website, chances are you’re going to need to write your own custom WP CLI command.

Adding a custom WP CLI command

Let’s add a simple WP CLI command, and the break it down. Add this to your functions.php file:

/**
* Updates a post's title.
*
* @param array $args
* @param array $assoc_args
*
* Usage: `wp jb-update-post-title --id=123 --title="New post title"`
*/
function jb_update_post_title( $args = array(), $assoc_args = array() ) {
	// Get arguments
	$arguments = wp_parse_args( $assoc_args, array(
		'id'    => 0,
		'title' => '',
	) );

	// Check if arguments are alright
	if ( $arguments['id'] > 0 && ! empty( $arguments['title'] ) ) {

		// Arguments are okay, update the post
		$post = array(
			'ID'         => $arguments['id'],
			'post_title' => $arguments['title'],
		);
		wp_update_post( $post );

		// Show success message
		WP_CLI::success( 'Updated post title successfully.' );

	} else {

		// Arguments not okay, show an error.
		WP_CLI::error( 'Invalid arguments.' );

	}
}
if ( defined( 'WP_CLI' ) && WP_CLI ) {
	WP_CLI::add_command( 'jb-update-post-title', 'jb_update_post_title' );
}

Let’s break the code down:

  • We first check if the constant WP_CLI is defined. If this line isn’t added, it will throw an error when you access your site normally. This is because the constant WP_CLI is only added when WP CLI is running. So when WordPress encounters this constant in your functions.php file when you access it from your browser, this constant will not be defined – throwing the error
  • WP_CLI::add_command( 'jb-update-post-title', 'jb_update_post_title' ); adds a new command jb-update-post-title which uses the function jb_update_post_title
  • The function passes two parameters $args and $args_assoc . The second parameter picks up anything that has two dashes, ie: --like-this . The first parameter picks up anything that does not have the two dashes. We’ve used the second parameter in the example above
  • We’re parsing the arguments and setting default values, if they were missing. We then check if the values the user entered are correct
  • If the values are correct, we update the post and show a success message via WP_CLI::success
  • If the values are incorrect, we show an error message via WP_CLI::error

Notes:

  1. Once we use WP_CLI::success or WP_CLI::error, we do not need to add a specific return statement in the function, because the function will terminate immediately
  2. If you’re using parameters without the two dashes, the $args variable will be a normal array. So the first value would be in $args[0], the second would be in $args[1] and so on

Usage

  1. Open up your terminal and navigate to your WordPress root folder (the one with wp-config.php in it)
  2. Make sure you’ve got WP CLI installed. You can do this by running wp --version . If it’s installed correctly, it should give you the version. If it’s not, you can install it by following these instructions
  3. Now just enter wp jb-update-post-title --id=123 --title="New post title" with the post ID and the title, and it should update the post with the new title!

Now that you know how to add a custom WP CLI command, you can use it to suit your need!

Happy coding! 🙂

Leave a Reply