Handling Time-Consuming Tasks in CodeIgniter 4 Using Queue Jobs

Overview:

Learn how CodeIgniter 4 can be extended to support background processing of time-consuming tasks using queue jobs, allowing your application to handle operations like bulk email dispatching in the background—without blocking the user interface or requiring users to wait behind loading screens.

Let’s consider a practical example. Suppose your application provides an API endpoint that allows admins to perform bulk updates on user data—such as updating the status or settings of hundreds or even thousands of users at once. If this process is handled synchronously, the frontend must wait until the entire update completes, typically showing a loader or progress indicator to the user. This not only delays the response but also risks timeouts and user frustration.

To solve this, you can implement queue jobs in CodeIgniter 4 to offload such heavy operations to the background. When a bulk update request is received, instead of processing all updates immediately, you queue the job for later execution and return a fast response to the user (e.g., “Update started”). The background worker processes the updates asynchronously, ensuring that the frontend remains responsive and the system performs efficiently.

This article walks you through building a simple queue mechanism in CodeIgniter 4, focusing on sending bulk emails without delaying the user experience. You’ll learn how to push jobs to a queue, process them in the background using CLI commands, and schedule them via cron. By adopting this approach, you can significantly improve application performance, maintain a smooth user interface, and scale time-consuming features effectively.

What Are Queue Jobs?

Queue jobs are units of work or tasks that are pushed into a waiting line (queue) to be processed later, usually by a background worker or daemon. This approach lets you defer lengthy operations from the user’s request/response cycle and run them independently.

For example:

1. Sending bulk emails

2. Processing uploaded files

3. Generating reports

4. Updating large datasets

Why Use Queues for Heavy Tasks?

• ⇒ Improved User Experience: Users receive immediate responses without waiting for the task to finish.
• ⇒ Better Performance: Heavy processing moves out of the main request thread, preventing slow or timed-out requests.
• ⇒ Reliability: Failed jobs can be retried without affecting the user session.

Setting Up Queue Jobs in CodeIgniter 4

CodeIgniter doesn’t come with a built-in queue system, but the [`codeigniter4/queue`] ( https://github.com/codeigniter4/queue ) package provides everything needed to implement one.

Step 1: Install the Queue Package

Run the command:

composer require codeigniter4/queue 

If you run into a stability error, run:

composer config minimum-stability dev
composer config prefer-stable true
composer require codeigniter4/queue:dev-develop

Step 2: Run Migrations & Publish Config

Once installed, run the migration to set up the database:

php spark migrate --all

Then publish the config file:

php spark queue:publish

Step 3: Create a Job Class

Let’s say you want to send an email. Run this to create a new job class:

php spark queue:job SendEmail

Step 4: Register the Job Handler

Open app/Config/Queue.php, and register your job class in the $jobHandlers array:

public array $jobHandlers = [
    'sendemail' =>; \App\Jobs\SendEmailJob::class,
];

Step 5: Push Jobs to the Queue

Dispatch the job from your controller or service:

$jobData = [
    'email'       =>; $email,
    'subject'     =>; $subject,
    'body'        =>; $body,
    'from_email'  =>; $fromEmail,
    'accessToken' =>; $accessToken,
];

$queue = \Config\Services::queue();
$queue->push('sendemail', 'sendemail', $jobData);

Step 6: Write Your Job Logic

Example SendEmailJob class:

<?php
namespace App\Jobs;

use CodeIgniter\Queue\BaseJob;
use GuzzleHttp\Client;

class SendEmailJob extends BaseJob
{
    protected $emailData;

    public function __construct($emailData)
    {
        $this->emailData = $emailData;
    }

    public function process()
    {
        $email       = $this->emailData['email'];
        $subject     = $this->emailData['subject'];
        $body        = $this->emailData['body'];
        $fromEmail   = $this->emailData['from_email'];
        $accessToken = $this->emailData['accessToken'];

        $client = new Client();

        try {
            $response = $client->post("https://graph.microsoft.com/v1.0/me/sendMail", [
                'headers' =>; [
                    'Authorization' =>; "Bearer $accessToken",
                    'Content-Type'  =>; 'application/json',
                ],
                'json' =>; [
                    'message' =>; [
                        'subject' =>; $subject,
                        'body' =>; [
                            'contentType' =>; 'HTML',
                            'content' =>; $body,
                        ],
                        'toRecipients' =>; [
                            [
                                'emailAddress' =>; ['address' =>; trim($email)],
                            ],
                        ],
                    ],
                    'saveToSentItems' =>; 'true',
                ],
            ]);

            if ($response->getStatusCode() !== 202) {
                throw new \Exception("Failed to send email to $email");
            }
        } catch (\Exception $e) {
            log_message('error', "Error sending email to $email: " . $e->getMessage());
        }
    }
}

Step 7: Process the Queue Jobs

Start the worker:

php spark queue:work

Run a specific queue:

php spark queue:work sendemail

Running Workers in the Background (Production)

In production:

nohup php spark queue:work > /dev/null 2>&1 &

Run specific queue:

nohup php spark queue:work sendemail > /dev/null 2>&1 &

Log output:

nohup php spark queue:work sendemail > /var/log/queue-worker.log 2>&1 &

With queue jobs in CodeIgniter 4, you can:

• ⇒ Offload heavy processing from user requests
• ⇒ Keep your API and frontend lightning-fast
• ⇒ Scale bulk email sending, large data imports, scheduled reports, and background notifications

This approach is especially useful for applications with features like:

• Bulk email sending
• Large data imports
• Scheduled reports
• Background notifications