1. 6.x-1.x batch_example/batch_example.module
  2. 7.x-1.x batch_example/batch_example.module

Outlines how a module can use the Batch API.

File

batch_example/batch_example.module
View source
  1. <?php
  2. /**
  3. * @file
  4. * Outlines how a module can use the Batch API.
  5. */
  6. /**
  7. * @defgroup batch_example Example: Batch API
  8. * @ingroup examples
  9. * @{
  10. * Outlines how a module can use the Batch API.
  11. *
  12. * Batches allow heavy processing to be spread out over several page
  13. * requests, ensuring that the processing does not get interrupted
  14. * because of a PHP timeout, while allowing the user to receive feedback
  15. * on the progress of the ongoing operations. It also can prevent out of memory
  16. * situations.
  17. *
  18. * The @link batch_example.install .install file @endlink also shows how the
  19. * Batch API can be used to handle long-running hook_update_N() functions.
  20. *
  21. * Two harmless batches are defined:
  22. * - batch 1: Load the node with the lowest nid 100 times.
  23. * - batch 2: Load all nodes, 20 times and uses a progressive op, loading nodes
  24. * by groups of 5.
  25. * @see batch
  26. */
  27. /**
  28. * Implements hook_menu().
  29. */
  30. function batch_example_menu() {
  31. $items = array();
  32. $items['examples/batch_example'] = array(
  33. 'title' => 'Batch example',
  34. 'description' => 'Example of Drupal batch processing',
  35. 'page callback' => 'drupal_get_form',
  36. 'page arguments' => array('batch_example_simple_form'),
  37. 'access callback' => TRUE,
  38. );
  39. return $items;
  40. }
  41. /**
  42. * Form builder function to allow choice of which batch to run.
  43. */
  44. function batch_example_simple_form() {
  45. $form['description'] = array(
  46. '#type' => 'markup',
  47. '#markup' => t('This example offers two different batches. The first does 1000 identical operations, each completed in on run; the second does 20 operations, but each takes more than one run to operate if there are more than 5 nodes.'),
  48. );
  49. $form['batch'] = array(
  50. '#type' => 'select',
  51. '#title' => 'Choose batch',
  52. '#options' => array(
  53. 'batch_1' => t('batch 1 - 1000 operations, each loading the same node'),
  54. 'batch_2' => t('batch 2 - 20 operations. each one loads all nodes 5 at a time'),
  55. ),
  56. );
  57. $form['submit'] = array(
  58. '#type' => 'submit',
  59. '#value' => 'Go',
  60. );
  61. // If no nodes, prevent submission.
  62. // Find out if we have a node to work with. Otherwise it won't work.
  63. $nid = batch_example_lowest_nid();
  64. if (empty($nid)) {
  65. drupal_set_message(t("You don't currently have any nodes, and this example requires a node to work with. As a result, this form is disabled."));
  66. $form['submit']['#disabled'] = TRUE;
  67. }
  68. return $form;
  69. }
  70. /**
  71. * Submit handler.
  72. *
  73. * @param array $form
  74. * Form API form.
  75. * @param array $form_state
  76. * Form API form.
  77. */
  78. function batch_example_simple_form_submit($form, &$form_state) {
  79. $function = 'batch_example_' . $form_state['values']['batch'];
  80. // Reset counter for debug information.
  81. $_SESSION['http_request_count'] = 0;
  82. // Execute the function named batch_example_batch_1() or
  83. // batch_example_batch_2().
  84. $batch = $function();
  85. batch_set($batch);
  86. }
  87. /**
  88. * Batch 1 definition: Load the node with the lowest nid 1000 times.
  89. *
  90. * This creates an operations array defining what batch 1 should do, including
  91. * what it should do when it's finished. In this case, each operation is the
  92. * same and by chance even has the same $nid to operate on, but we could have
  93. * a mix of different types of operations in the operations array.
  94. */
  95. function batch_example_batch_1() {
  96. $nid = batch_example_lowest_nid();
  97. $num_operations = 1000;
  98. drupal_set_message(t('Creating an array of @num operations', array('@num' => $num_operations)));
  99. $operations = array();
  100. // Set up an operations array with 1000 elements, each doing function
  101. // batch_example_op_1.
  102. // Each operation in the operations array means at least one new HTTP request,
  103. // running Drupal from scratch to accomplish the operation. If the operation
  104. // returns with $context['finished'] != TRUE, then it will be called again.
  105. // In this example, $context['finished'] is always TRUE.
  106. for ($i = 0; $i < $num_operations; $i++) {
  107. // Each operation is an array consisting of
  108. // - The function to call.
  109. // - An array of arguments to that function.
  110. $operations[] = array(
  111. 'batch_example_op_1',
  112. array(
  113. $nid,
  114. t('(Operation @operation)', array('@operation' => $i)),
  115. ),
  116. );
  117. }
  118. $batch = array(
  119. 'operations' => $operations,
  120. 'finished' => 'batch_example_finished',
  121. );
  122. return $batch;
  123. }
  124. /**
  125. * Batch operation for batch 1: load a node.
  126. *
  127. * This is the function that is called on each operation in batch 1.
  128. */
  129. function batch_example_op_1($nid, $operation_details, &$context) {
  130. $node = node_load($nid, NULL, TRUE);
  131. // Store some results for post-processing in the 'finished' callback.
  132. // The contents of 'results' will be available as $results in the
  133. // 'finished' function (in this example, batch_example_finished()).
  134. $context['results'][] = $node->nid . ' : ' . check_plain($node->title);
  135. // Optional message displayed under the progressbar.
  136. $context['message'] = t('Loading node "@title"', array('@title' => $node->title)) . ' ' . $operation_details;
  137. _batch_example_update_http_requests();
  138. }
  139. /**
  140. * Batch 2 : Prepare a batch definition that will load all nodes 20 times.
  141. */
  142. function batch_example_batch_2() {
  143. $num_operations = 20;
  144. // Give helpful information about how many nodes are being operated on.
  145. $node_count = db_query('SELECT COUNT(DISTINCT nid) FROM {node}')->fetchField();
  146. drupal_set_message(
  147. t('There are @node_count nodes so each of the @num operations will require @count HTTP requests.',
  148. array(
  149. '@node_count' => $node_count,
  150. '@num' => $num_operations,
  151. '@count' => ceil($node_count / 5),
  152. )
  153. )
  154. );
  155. $operations = array();
  156. // 20 operations, each one loads all nodes.
  157. for ($i = 0; $i < $num_operations; $i++) {
  158. $operations[] = array(
  159. 'batch_example_op_2',
  160. array(t('(Operation @operation)', array('@operation' => $i))),
  161. );
  162. }
  163. $batch = array(
  164. 'operations' => $operations,
  165. 'finished' => 'batch_example_finished',
  166. // Message displayed while processing the batch. Available placeholders are:
  167. // @current, @remaining, @total, @percentage, @estimate and @elapsed.
  168. // These placeholders are replaced with actual values in _batch_process(),
  169. // using strtr() instead of t(). The values are determined based on the
  170. // number of operations in the 'operations' array (above), NOT by the number
  171. // of nodes that will be processed. In this example, there are 20
  172. // operations, so @total will always be 20, even though there are multiple
  173. // nodes per operation.
  174. // Defaults to t('Completed @current of @total.').
  175. 'title' => t('Processing batch 2'),
  176. 'init_message' => t('Batch 2 is starting.'),
  177. 'progress_message' => t('Processed @current out of @total.'),
  178. 'error_message' => t('Batch 2 has encountered an error.'),
  179. );
  180. return $batch;
  181. }
  182. /**
  183. * Batch operation for batch 2 : load all nodes, 5 by five.
  184. *
  185. * After each group of 5 control is returned to the batch API for later
  186. * continuation.
  187. */
  188. function batch_example_op_2($operation_details, &$context) {
  189. // Use the $context['sandbox'] at your convenience to store the
  190. // information needed to track progression between successive calls.
  191. if (empty($context['sandbox'])) {
  192. $context['sandbox'] = array();
  193. $context['sandbox']['progress'] = 0;
  194. $context['sandbox']['current_node'] = 0;
  195. // Save node count for the termination message.
  196. $context['sandbox']['max'] = db_query('SELECT COUNT(DISTINCT nid) FROM {node}')->fetchField();
  197. }
  198. // Process nodes by groups of 5 (arbitrary value).
  199. // When a group of five is processed, the batch update engine determines
  200. // whether it should continue processing in the same request or provide
  201. // progress feedback to the user and wait for the next request.
  202. // That way even though we're already processing at the operation level
  203. // the operation itself is interruptible.
  204. $limit = 5;
  205. // Retrieve the next group of nids.
  206. $result = db_select('node', 'n')
  207. ->fields('n', array('nid'))
  208. ->orderBy('n.nid', 'ASC')
  209. ->where('n.nid > :nid', array(':nid' => $context['sandbox']['current_node']))
  210. ->extend('PagerDefault')
  211. ->limit($limit)
  212. ->execute();
  213. foreach ($result as $row) {
  214. // Here we actually perform our dummy 'processing' on the current node.
  215. $node = node_load($row->nid, NULL, TRUE);
  216. // Store some results for post-processing in the 'finished' callback.
  217. // The contents of 'results' will be available as $results in the
  218. // 'finished' function (in this example, batch_example_finished()).
  219. $context['results'][] = $node->nid . ' : ' . check_plain($node->title) . ' ' . $operation_details;
  220. // Update our progress information.
  221. $context['sandbox']['progress']++;
  222. $context['sandbox']['current_node'] = $node->nid;
  223. $context['message'] = check_plain($node->title);
  224. }
  225. // Inform the batch engine that we are not finished,
  226. // and provide an estimation of the completion level we reached.
  227. if ($context['sandbox']['progress'] != $context['sandbox']['max']) {
  228. $context['finished'] = ($context['sandbox']['progress'] >= $context['sandbox']['max']);
  229. }
  230. _batch_example_update_http_requests();
  231. }
  232. /**
  233. * Batch 'finished' callback used by both batch 1 and batch 2.
  234. */
  235. function batch_example_finished($success, $results, $operations) {
  236. if ($success) {
  237. // Here we could do something meaningful with the results.
  238. // We just display the number of nodes we processed...
  239. drupal_set_message(t('@count results processed in @requests HTTP requests.', array('@count' => count($results), '@requests' => _batch_example_get_http_requests())));
  240. drupal_set_message(t('The final result was "%final"', array('%final' => end($results))));
  241. }
  242. else {
  243. // An error occurred.
  244. // $operations contains the operations that remained unprocessed.
  245. $error_operation = reset($operations);
  246. drupal_set_message(
  247. t('An error occurred while processing @operation with arguments : @args',
  248. array(
  249. '@operation' => $error_operation[0],
  250. '@args' => print_r($error_operation[0], TRUE),
  251. )
  252. ),
  253. 'error'
  254. );
  255. }
  256. }
  257. /**
  258. * Utility function - simply queries and loads the lowest nid.
  259. *
  260. * @return int|NULL
  261. * A nid or NULL if there are no nodes.
  262. */
  263. function batch_example_lowest_nid() {
  264. $select = db_select('node', 'n')
  265. ->fields('n', array('nid'))
  266. ->orderBy('n.nid', 'ASC')
  267. ->extend('PagerDefault')
  268. ->limit(1);
  269. $nid = $select->execute()->fetchField();
  270. return $nid;
  271. }
  272. /**
  273. * Utility function to increment HTTP requests in a session variable.
  274. */
  275. function _batch_example_update_http_requests() {
  276. $_SESSION['http_request_count']++;
  277. }
  278. /**
  279. * Utility function to count the HTTP requests in a session variable.
  280. *
  281. * @return int
  282. * Number of requests.
  283. */
  284. function _batch_example_get_http_requests() {
  285. return !empty($_SESSION['http_request_count']) ? $_SESSION['http_request_count'] : 0;
  286. }
  287. /**
  288. * @} End of "defgroup batch_example".
  289. */

Functions

Namesort descending Description
batch_example_batch_1 Batch 1 definition: Load the node with the lowest nid 1000 times.
batch_example_batch_2 Batch 2 : Prepare a batch definition that will load all nodes 20 times.
batch_example_finished Batch 'finished' callback used by both batch 1 and batch 2.
batch_example_lowest_nid Utility function - simply queries and loads the lowest nid.
batch_example_menu Implements hook_menu().
batch_example_op_1 Batch operation for batch 1: load a node.
batch_example_op_2 Batch operation for batch 2 : load all nodes, 5 by five.
batch_example_simple_form Form builder function to allow choice of which batch to run.
batch_example_simple_form_submit Submit handler.
_batch_example_get_http_requests Utility function to count the HTTP requests in a session variable.
_batch_example_update_http_requests Utility function to increment HTTP requests in a session variable.