batch_example.module

You are here

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

Outlines how a module can use the Batch API.

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.

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_1 or batch_example_2.
  83. $batch = $function();
  84. batch_set($batch);
  85. }
  86. /**
  87. * Batch 1 definition: Load the node with the lowest nid 1000 times.
  88. *
  89. * This creates an operations array defining what batch 1 should do, including
  90. * what it should do when it's finished. In this case, each operation is the
  91. * same and by chance even has the same $nid to operate on, but we could have
  92. * a mix of different types of operations in the operations array.
  93. */
  94. function batch_example_batch_1() {
  95. $nid = batch_example_lowest_nid();
  96. $num_operations = 1000;
  97. drupal_set_message(t('Creating an array of @num operations', array('@num' => $num_operations)));
  98. $operations = array();
  99. // Set up an operations array with 1000 elements, each doing function
  100. // batch_example_op_1.
  101. // Each operation in the operations array means at least one new HTTP request,
  102. // running Drupal from scratch to accomplish the operation. If the operation
  103. // returns with $context['finished'] != TRUE, then it will be called again.
  104. // In this example, $context['finished'] is always TRUE.
  105. for ($i = 0; $i < $num_operations; $i++) {
  106. // Each operation is an array consisting of
  107. // - The function to call.
  108. // - An array of arguments to that function.
  109. $operations[] = array(
  110. 'batch_example_op_1',
  111. array(
  112. $nid,
  113. t('(Operation @operation)', array('@operation' => $i)),
  114. ),
  115. );
  116. }
  117. $batch = array(
  118. 'operations' => $operations,
  119. 'finished' => 'batch_example_finished',
  120. );
  121. return $batch;
  122. }
  123. /**
  124. * Batch operation for batch 1: load a node.
  125. *
  126. * This is the function that is called on each operation in batch 1.
  127. */
  128. function batch_example_op_1($nid, $operation_details, &$context) {
  129. $node = node_load($nid, NULL, TRUE);
  130. // Store some results for post-processing in the 'finished' callback.
  131. // The contents of 'results' will be available as $results in the
  132. // 'finished' function (in this example, batch_example_finished()).
  133. $context['results'][] = $node->nid . ' : ' . check_plain($node->title);
  134. // Optional message displayed under the progressbar.
  135. $context['message'] = t('Loading node "@title"', array('@title' => $node->title)) . ' ' . $operation_details;
  136. _batch_example_update_http_requests();
  137. }
  138. /**
  139. * Batch 2 : Prepare a batch definition that will load all nodes 20 times.
  140. */
  141. function batch_example_batch_2() {
  142. $num_operations = 20;
  143. // Give helpful information about how many nodes are being operated on.
  144. $node_count = db_query('SELECT COUNT(DISTINCT nid) FROM {node}')->fetchField();
  145. drupal_set_message(
  146. t('There are @node_count nodes so each of the @num operations will require @count HTTP requests.',
  147. array(
  148. '@node_count' => $node_count,
  149. '@num' => $num_operations,
  150. '@count' => ceil($node_count / 5),
  151. )
  152. )
  153. );
  154. $operations = array();
  155. // 20 operations, each one loads all nodes.
  156. for ($i = 0; $i < $num_operations; $i++) {
  157. $operations[] = array(
  158. 'batch_example_op_2',
  159. array(t('(Operation @operation)', array('@operation' => $i))),
  160. );
  161. }
  162. $batch = array(
  163. 'operations' => $operations,
  164. 'finished' => 'batch_example_finished',
  165. // Message displayed while processing the batch. Available placeholders are:
  166. // @current, @remaining, @total, @percentage, @estimate and @elapsed.
  167. // These placeholders are replaced with actual values in _batch_process(),
  168. // using strtr() instead of t(). The values are determined based on the
  169. // number of operations in the 'operations' array (above), NOT by the number
  170. // of nodes that will be processed. In this example, there are 20
  171. // operations, so @total will always be 20, even though there are multiple
  172. // nodes per operation.
  173. // Defaults to t('Completed @current of @total.').
  174. 'title' => t('Processing batch 2'),
  175. 'init_message' => t('Batch 2 is starting.'),
  176. 'progress_message' => t('Processed @current out of @total.'),
  177. 'error_message' => t('Batch 2 has encountered an error.'),
  178. );
  179. return $batch;
  180. }
  181. /**
  182. * Batch operation for batch 2 : load all nodes, 5 by five.
  183. *
  184. * After each group of 5 control is returned to the batch API for later
  185. * continuation.
  186. */
  187. function batch_example_op_2($operation_details, &$context) {
  188. // Use the $context['sandbox'] at your convenience to store the
  189. // information needed to track progression between successive calls.
  190. if (empty($context['sandbox'])) {
  191. $context['sandbox'] = array();
  192. $context['sandbox']['progress'] = 0;
  193. $context['sandbox']['current_node'] = 0;
  194. // Save node count for the termination message.
  195. $context['sandbox']['max'] = db_query('SELECT COUNT(DISTINCT nid) FROM {node}')->fetchField();
  196. }
  197. // Process nodes by groups of 5 (arbitrary value).
  198. // When a group of five is processed, the batch update engine determines
  199. // whether it should continue processing in the same request or provide
  200. // progress feedback to the user and wait for the next request.
  201. // That way even though we're already processing at the operation level
  202. // the operation itself is interruptible.
  203. $limit = 5;
  204. // Retrieve the next group of nids.
  205. $result = db_select('node', 'n')
  206. ->fields('n', array('nid'))
  207. ->orderBy('n.nid', 'ASC')
  208. ->where('n.nid > :nid', array(':nid' => $context['sandbox']['current_node']))
  209. ->extend('PagerDefault')
  210. ->limit($limit)
  211. ->execute();
  212. foreach ($result as $row) {
  213. // Here we actually perform our dummy 'processing' on the current node.
  214. $node = node_load($row->nid, NULL, TRUE);
  215. // Store some results for post-processing in the 'finished' callback.
  216. // The contents of 'results' will be available as $results in the
  217. // 'finished' function (in this example, batch_example_finished()).
  218. $context['results'][] = $node->nid . ' : ' . check_plain($node->title) . ' ' . $operation_details;
  219. // Update our progress information.
  220. $context['sandbox']['progress']++;
  221. $context['sandbox']['current_node'] = $node->nid;
  222. $context['message'] = check_plain($node->title);
  223. }
  224. // Inform the batch engine that we are not finished,
  225. // and provide an estimation of the completion level we reached.
  226. if ($context['sandbox']['progress'] != $context['sandbox']['max']) {
  227. $context['finished'] = ($context['sandbox']['progress'] >= $context['sandbox']['max']);
  228. }
  229. _batch_example_update_http_requests();
  230. }
  231. /**
  232. * Batch 'finished' callback used by both batch 1 and batch 2.
  233. */
  234. function batch_example_finished($success, $results, $operations) {
  235. if ($success) {
  236. // Here we could do something meaningful with the results.
  237. // We just display the number of nodes we processed...
  238. drupal_set_message(t('@count results processed in @requests HTTP requests.', array('@count' => count($results), '@requests' => _batch_example_get_http_requests())));
  239. drupal_set_message(t('The final result was "%final"', array('%final' => end($results))));
  240. }
  241. else {
  242. // An error occurred.
  243. // $operations contains the operations that remained unprocessed.
  244. $error_operation = reset($operations);
  245. drupal_set_message(
  246. t('An error occurred while processing @operation with arguments : @args',
  247. array(
  248. '@operation' => $error_operation[0],
  249. '@args' => print_r($error_operation[0], TRUE),
  250. )
  251. )
  252. );
  253. }
  254. }
  255. /**
  256. * Utility function - simply queries and loads the lowest nid.
  257. *
  258. * @return int|NULL
  259. * A nid or NULL if there are no nodes.
  260. */
  261. function batch_example_lowest_nid() {
  262. $select = db_select('node', 'n')
  263. ->fields('n', array('nid'))
  264. ->orderBy('n.nid', 'ASC')
  265. ->extend('PagerDefault')
  266. ->limit(1);
  267. $nid = $select->execute()->fetchField();
  268. return $nid;
  269. }
  270. /**
  271. * Utility function to increment HTTP requests in a session variable.
  272. */
  273. function _batch_example_update_http_requests() {
  274. $_SESSION['http_request_count']++;
  275. }
  276. /**
  277. * Utility function to count the HTTP requests in a session variable.
  278. *
  279. * @return int
  280. * Number of requests.
  281. */
  282. function _batch_example_get_http_requests() {
  283. return !empty($_SESSION['http_request_count']) ? $_SESSION['http_request_count'] : 0;
  284. }
  285. /**
  286. * @} End of "defgroup batch_example".
  287. */