Backend Development - Batch API

In the previous topic, we explored the Queue API, which allows background processing through cron. Now we move to another powerful processing system in Drupal: the Batch API.

While Queue API is designed for deferred, background work, the Batch API is designed for progressive processing during a browser request.

Batch API is used when:

• A task may take a long time
• You want to avoid PHP timeouts
• You want to show progress to the user
• The process must run immediately, not later via cron

This topic continues the learning-by-building approach using the same weeklydrupal_demo module.

By the end of this article, you will understand:

• What the Batch API is
• When to use Batch vs Queue
• How to define batch operations
• How progress and state are maintained
• How Batch API fits into backend architecture

1. What Is the Batch API

The Batch API allows Drupal to:

• Break a large task into smaller operations
• Execute them across multiple HTTP requests
• Display a progress bar
• Avoid request timeouts

In simple terms:

Batch API = controlled multi-step processing in the browser

2. When to Use Batch API

Use Batch API when:

• Importing 500–5000 records from a CSV
• Updating many entities at once
• Running admin-triggered maintenance tasks
• Performing re-indexing operations

Do not use Batch API for:

• Background-only tasks (use Queue API)
• Small operations that complete quickly

3. Batch API vs Queue API

Queue API:

• Runs in background (cron)
• No user feedback
• Best for automation

Batch API:

• Runs immediately
• Shows progress bar
• User waits until completion

Both are important. They solve different problems.

4. Basic Batch Structure

A batch is defined using:

$batch = [
  'title' => t('Processing records'),
  'operations' => $operations,
  'finished' => 'weeklydrupal_demo_batch_finished',
];

batch_set($batch);

Operations are defined as arrays of callbacks.

5. Defining Batch Operations

Example: create 10 article nodes progressively.

$operations = [];

for ($i = 1; $i <= 10; $i++) {
  $operations[] = [
    'weeklydrupal_demo_batch_process',
    [$i],
  ];
}

Each operation receives parameters and a context array.

6. Batch Process Callback

function weeklydrupal_demo_batch_process($number, &$context) {

  $node = \Drupal::entityTypeManager()->getStorage('node')->create([
    'type' => 'article',
    'title' => 'Batch Article ' . $number,
    'status' => 1,
  ]);

  $node->save();

  $context['message'] = t('Processed article @num', ['@num' => $number]);
}

What is happening

• Each operation runs separately
• $context stores progress
• Drupal redirects automatically between steps

7. Finished Callback

function weeklydrupal_demo_batch_finished($success, $results, $operations) {
  if ($success) {
    \Drupal::messenger()->addStatus(t('Batch completed successfully.'));
  }
  else {
    \Drupal::messenger()->addError(t('Batch processing encountered an error.'));
  }
}

The finished callback runs after all operations complete.

8. How Batch Maintains State

Drupal stores batch data in the database.

Between each HTTP request:

• Progress is stored
• Remaining operations are tracked
• Messages are updated

This ensures long processes complete safely.

9. Using Batch in a Controller

Example route handler:

public function runBatch() {

  $operations = [];

  for ($i = 1; $i <= 10; $i++) {
    $operations[] = ['weeklydrupal_demo_batch_process', [$i]];
  }

  $batch = [
    'title' => t('Creating articles'),
    'operations' => $operations,
    'finished' => 'weeklydrupal_demo_batch_finished',
  ];

  batch_set($batch);

  return batch_process('/admin');
}

This starts the batch and redirects to progress UI.

10. Best Practices for Batch API

• Keep each operation small
• Avoid heavy memory usage per step
• Use services instead of static calls
• Provide clear progress messages
• Handle errors carefully

Batch API should feel stable and predictable.

11. Learning by Building: weeklydrupal_demo

To apply this topic:

• Add route /weeklydrupal/demo/batch
• Trigger batch to create 100 nodes
• Display progress
• Verify creation in content list

This connects:

• Routes
• Controllers
• Entity CRUD
• Progressive processing

12. Common Mistakes to Avoid

• Running entire workload in one operation
• Forgetting finished callback
• Mixing heavy business logic directly in callbacks
• Using Batch when Queue is more appropriate

Choose the right tool for the job.

13. Why Batch API Matters

Understanding the Batch API allows you to:

• Prevent timeouts
• Provide better admin UX
• Handle large data safely
• Build controlled processing workflows

Batch processing is essential for scalable backend administration.