batch_set

  1. drupal
    1. 8
    2. 6
    3. 7
Versions
7 – 6 batch_set($batch_definition)

Opens a new batch.

Parameters

$batch An array defining the batch. The following keys can be used -- only 'operations' is required, and batch_init() provides default values for the messages.

  • 'operations': Array of function calls to be performed. Example:

<?php
    array(
      array('my_function_1', array($arg1)),
      array('my_function_2', array($arg2_1, $arg2_2)),
    )
    ?>
  • 'title': Title for the progress page. Only safe strings should be passed. Defaults to t('Processing').
  • 'init_message': Message displayed while the processing is initialized. Defaults to t('Initializing.').
  • 'progress_message': Message displayed while processing the batch. Available placeholders are @current, @remaining, @total, @percentage, @estimate and @elapsed. Defaults to t('Completed @current of @total.').
  • 'error_message': Message displayed if an error occurred while processing the batch. Defaults to t('An error has occurred.').
  • 'finished': Name of a function to be executed after the batch has completed. This should be used to perform any result massaging that may be needed, and possibly save data in $_SESSION for display after final page redirection.
  • 'file': Path to the file containing the definitions of the 'operations' and 'finished' functions, for instance if they don't reside in the main .module file. The path should be relative to base_path(), and thus should be built using drupal_get_path().
  • 'css': Array of paths to CSS files to be used on the progress page.
  • 'url_options': options passed to url() when constructing redirect URLs for the batch.

Operations are added as new batch sets. Batch sets are used to ensure clean code independence, ensuring that several batches submitted by different parts of the code (core / contrib modules) can be processed correctly while not interfering or having to cope with each other. Each batch set gets to specify his own UI messages, operates on its own set of operations and results, and triggers its own 'finished' callback. Batch sets are processed sequentially, with the progress bar starting fresh for every new set.

Related topics

▾ 23 functions call batch_set()

batch_example_simple_form_submit in examples/batch_example/batch_example.module
batch_test_chained_form_submit_1 in modules/simpletest/tests/batch_test.module
Submit handler #1 for the chained form.
batch_test_chained_form_submit_2 in modules/simpletest/tests/batch_test.module
Submit handler #2 for the chained form.
batch_test_chained_form_submit_4 in modules/simpletest/tests/batch_test.module
Submit handler #4 for the chained form.
batch_test_large_percentage in modules/simpletest/tests/batch_test.module
Menu callback: fire a batch process without a form submission.
batch_test_multistep_form_submit in modules/simpletest/tests/batch_test.module
Submit handler for the multistep form.
batch_test_nested_drupal_form_submit in modules/simpletest/tests/batch_test.module
Menu callback: programmatically submits a form within a batch.
batch_test_no_form in modules/simpletest/tests/batch_test.module
Menu callback: fire a batch process without a form submission.
batch_test_simple_form_submit in modules/simpletest/tests/batch_test.module
Submit handler for the simple form.
batch_test_theme_batch in modules/simpletest/tests/batch_test.module
Menu callback: run a batch for testing theme used on the progress page.
install_run_task in includes/install.core.inc
Runs an individual installation task.
locale_languages_predefined_form_submit in modules/locale/locale.admin.inc
Process the language addition form submission.
locale_system_update in modules/locale/locale.module
Imports translations when new modules or themes are installed.
node_access_rebuild in modules/node/node.module
Rebuild the node access database. This is occasionally needed by modules that make system-wide changes to access levels.
node_mass_update in modules/node/node.admin.inc
Make mass update of nodes, changing all nodes in the $nodes array to update them with the field values in $updates.
simpletest_run_tests in modules/simpletest/simpletest.module
Actually runs tests.
update_authorize_run_install in modules/update/update.authorize.inc
Callback invoked by authorize.php to install a new project.
update_authorize_run_update in modules/update/update.authorize.inc
Callback invoked by authorize.php to update existing projects.
update_batch in includes/update.inc
Start the database update batch process.
update_manager_update_form_submit in modules/update/update.manager.inc
Submit function for the main update form.
update_manual_status in modules/update/update.fetch.inc
Callback to manually check the update status without cron.
user_cancel in modules/user/user.module
Cancel a user account.
_batch_test_nested_batch_callback in modules/simpletest/tests/batch_test.callbacks.inc
Batch operation setting up its own batch.

Code

includes/form.inc, line 4222

<?php
function batch_set($batch_definition) {
  if ($batch_definition) {
    $batch = &batch_get();

    // Initialize the batch if needed.
    if (empty($batch)) {
      $batch = array(
        'sets' => array(), 
        'has_form_submits' => FALSE,
      );
    }

    // Base and default properties for the batch set.
    // Use get_t() to allow batches at install time.
    $t = get_t();
    $init = array(
      'sandbox' => array(), 
      'results' => array(), 
      'success' => FALSE, 
      'start' => 0, 
      'elapsed' => 0,
    );
    $defaults = array(
      'title' => $t('Processing'), 
      'init_message' => $t('Initializing.'), 
      'progress_message' => $t('Completed @current of @total.'), 
      'error_message' => $t('An error has occurred.'), 
      'css' => array(),
    );
    $batch_set = $init + $batch_definition + $defaults;

    // Tweak init_message to avoid the bottom of the page flickering down after
    // init phase.
    $batch_set['init_message'] .= '<br/>&nbsp;';

    // The non-concurrent workflow of batch execution allows us to save
    // numberOfItems() queries by handling our own counter.
    $batch_set['total'] = count($batch_set['operations']);
    $batch_set['count'] = $batch_set['total'];

    // Add the set to the batch.
    if (empty($batch['id'])) {
      // The batch is not running yet. Simply add the new set.
      $batch['sets'][] = $batch_set;
    }
    else {
      // The set is being added while the batch is running. Insert the new set
      // right after the current one to ensure execution order, and store its
      // operations in a queue.
      $index = $batch['current_set'] + 1;
      $slice1 = array_slice($batch['sets'], 0, $index);
      $slice2 = array_slice($batch['sets'], $index);
      $batch['sets'] = array_merge($slice1, array($batch_set), $slice2);
      _batch_populate_queue($batch, $index);
    }
  }
}
?>