Home

Locomotive is a batch processing library that can be used to write a single or set of functions to be processed across a large data set, right from the WordPress admin. You can use it to add meta values to posts based on arbitrary data, process and delete spam comments and revisions, submit posts through external API's, or simply change data on a large amount of posts at the same time.

Locomotive gives you access to a simple API you can use to define your data set and easily create the action you want performed. Processes registered through Locomotive are accessible in a panel in the WordPress admin, and can be run at any time with the click of a button.

To see specific examples for each post object type visit the examples page

Getting Started

The first thing you need to do is download and install the plugin. Ensure that the plugin is activated.

Registering a Process

Locomotive works by defining individual processes. Each process defines exactly what data to use and a callback that can be used to perform an action on this data set, one at a time. register_batch_process is used to define the parameters for the data. This can be added to your theme's functions.php file using the locomotive_init action:

function my_batch_process() {
  register_batch_process( array(
    'name'     => 'Posts Batch',
    'type'     => 'post',
    'callback' => 'my_callback_function',
    'args'     => array(
      'posts_per_page' => 10,
      'post_type'      => 'post'
    )
  ) );
}
add_action( 'locomotive_init', 'my_batch_process' );

Next you need to define your callback function. Locomotive will take the data from your query, in this case the first 10 posts, and pass them to your callback function one by one. Your callback will have one parameter, the full object from the individual result. The callback is what you will use to do your actual processing. You will have full access to the query object here, so you can perform any actions you want. In this example, we will simply log the output.

/**
 * This is what we want to do with each individual result during a batch routine
 *
 * @param  array $result Individual result from batch query.
 */
function my_callback_function( $result ) {
    error_log( print_r( $result->post_title, true ) );
}

Arguments

register_batch_process takes a number of arguments:

name (string)

The process name. This is what will be shown in the WordPress admin

'name' => 'Batch Name',

type (string)

The type of data you wish to process. Corresponds to query for post object Possible values:

| WordPress Class        Matching type         
| --------------------- | --------------------- |
| WP_Query              | post                  |
| WP_User_Query         | user                  |
| WP_Term_Query         | term                  |
| WP_Comment_Query      | comment               |      
| WP_Site_Query         | site (multisite req.) |

'type' => 'post',

callback

The name of the callback function to pass data to. Data will be passed individually to the callback

'callback' => 'my_callback_function_name',

args

Args are where you can define your data set, and is dependent on the type. Any parameter that can be used in the main Query object can also be used here. For instance see WP_Query for post or page types, and WP_User_Query for type user. See chart above for full list.

'args' => array( 'order' => 'ASC', 'cat' => 4, 'posts_per_page' => 100, ),

### Running Your process
Once you've registered a process you can run it at any time by going to the WordPress admin and selecting "Locomotive" from the menu. You will see a list of your registered process. Simply select the process you want to run, then click "Run Batch Process".

![Run Process](https://cloud.githubusercontent.com/assets/1718298/21241901/cf4a37c4-c2df-11e6-880e-203e684ff8d5.gif)

### Resetting Your Process
From time to time, you may want to reset an individual process. This will erase all metadata and logs associated with the process and reset the count back to 0. _Note: This will not remove the process_

To reset a batch process select the name from the admin and click the "Reset Batch Process" button.