CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

Troubleshooting Queue Jobs with Queue Monitor Plugin

Written by Arusinowski on December 11, 2024
2780 VIEWS

This article is part of the CakeDC Advent Calendar 2024 (December 11th 2024)

In this article we'll show how to easily monitor the queue jobs in CakePHP 5.0 using the CakePHP Queue Monitor plugin.

Queue Monitor Plugin is a companion plugin for the official CakePHP Queue plugin .

Why I should monitor the queues

Monitoring queue jobs is crucial for maintaining the health and efficiency of your application's background processing. Here are some compelling reasons why you should monitor queue jobs:

  • Performance and Throughput: Monitoring helps ensure that your jobs are processed within acceptable time frames, preventing bottlenecks and ensuring that your application runs smoothly.
  • Error Detection and Handling: By keeping an eye on your queue jobs, you can quickly identify and address errors or failures in the jobs. This allows you to reduce the potential downtime.
  • Scalability: As your application grows, monitoring helps you understand how the queue system is handling the increased load, guiding decisions about scaling up or distributing workloads among multiple workers to speed up the job processing.
  • User Experience: Ensuring that background tasks are processed efficiently directly impacts the user experience. For example, timely processing of tasks like email notifications or data updates keeps users satisfied.

By monitoring your queue jobs, you can maintain a robust and efficient application that enhances performance and ensures reliability.

Key Features

This plugin will allow you to monitor the queue, in particular:

  • monitor and notify about jobs that exceed the specified working time
  • check if configured queues are working correctly
  • clear the queue of queued jobs
  • inspect job messages that have been processed

Getting Started

Before we discuss the functionality, we will go through the installation and configuration of the plugin.

Step 1: Installing the plugin

First you need to install the plugin into your CakePHP 5 application. To do this, you will need to run this command in the root of your project:

composer require cakedc/queue-monitor

When the plugin is installed please load it into your application:

bin/cake plugin load CakeDC/QueueMonitor

After the plugin is loaded please run the required migrations:

bin/cake migrations migrate -p CakeDC/QueueMonitor

Step 2: Configuring the monitoring

To configure monitoring, place the following directives in your config/app_local.php and adjust values if needed.

// ...
    'QueueMonitor' => [
        'disable' => false,
        'mailerConfig' => 'default',
        'longJobInMinutes' => 30,
        'purgeLogsOlderThanDays' => 7,
        'notificationRecipients' => '[email protected],[email protected],[email protected]',
    ],
// ...

Options explained:

  • QueueMonitor.disable - With this setting you can enable or disable the queue monitoring, as the queue monitoring is enabled by default.
  • QueueMonitor.mailerConfig - mailer config used for notification, the default is default mailer.
  • QueueMonitor.longJobInMinutes - This is the time in minutes after which the job will be considered as working too long, and will be taken into account when sending notifications. The default values is 30 minutes.
  • QueueMonitor.purgeLogsOlderThanDays - This is the time in days after which logs will be deleted from the database to keep the log table small. The default value is 7 days.
  • QueueMonitor.notificationRecipients - This is a comma-separated list of recipients of notifications about jobs exceeding the configured working time.

Step 3: Configuring queue to use the monitoring

To enable the monitoring capabilities to a queue, you will need to add the listener to the queue configurations that you want monitor:

    'Queue' => [
        'default' => [
            // ...
            'listener' => \CakeDC\QueueMonitor\Listener\QueueMonitorListener::class,
            // ...
        ]
    ],

Step 4: Configure notification cronjob

To receive emails about jobs that take too long to process, you need to add the following command to cron:

bin/cake queue-monitor notify

It is best to configure this command to run every few minutes.

Step 5: Configure the log purging

To keep the log table size small, you need to add automatic log purging to cron:

bin/cake queue-monitor purge-logs

It is best to configure this command to run every day.

Features

Continuous queue job monitoring

With the Queue Monitoring plugin installed and configured, all of your queued jobs are logged with time points and full message content. The entire processing of each job is also logged, starting from the moment the job is enqueued until one of the many ways the job ends.

When any of the jobs exceeds the configured working time, you will be notified by email.

Inspecting the queue logs

Using CakeDC\QueueMonitor\Model\Table\LogsTable you can view all logged job messages. This functionality will be expanded in subsequent versions of the plugin.

Testing the queues

To quickly test if all queues are running correctly, run this command (replace [email protected] with working email address:

bin/cake queue-monitor test-enqueue [email protected]

This command will send the email through all configured queues.

Purging the queues

To purge the content of a specified queue you can use the purge queue command:

bin/cake queue-monitor purge-queue your-queue-name

The above command will remove all pending queue jobs from the specified queue.

To purge all queues you can use command:

bin/cake queue-monitor purge-queue --all



Conclusion

And that's it, you have successfully enabled queue monitoring and troubleshooting tools in your application.

This plugin is in active development and more features will be added to it soon, some of them are:

  • browsing the content of messages in the queue
  • deleting a specified number of messages from the queue
  • deleting the first job in the queue
  • CRUD for queue logs
  • asynchronous queue logging to prevent degradation of job processing performance in case of high job frequency

We look forward to your feedback and contributions as we continue to enhance this plugin for the benefit of the entire CakePHP community.

This article is part of the CakeDC Advent Calendar 2024 (December 11th 2024)

Latest articles

58 Views

Goodbye to 2025!

Well bakers… another advent calendar is coming to an end. I hope you enjoyed all of the topics covered each day. We are also closing the year with so much gratitude.    2025 was the 20th year of CakePHP, can you believe it? We had an amazing year with our team, the community and the CakePHP core. It was great connecting with those who attended CakeFest in Madrid, and we hope to have the opportunity to see more of you in 2026.    I cannot let the year end without getting a little sentimental. There is no better way to say it… THANK YOU. Thank you to the team who worked so hard, the core team that keeps pumping out releases, and most of all … thank you to our clients that trust us with their projects. CakeDC is successful because of the strong relationships we build with our network, and we hope to continue working with all of you for many years.    There are a lot of great things still to come in year 21! Could 2026 will be bringing us CakePHP 6?! Considering 2 is rhe legal drinking age in the US, maybe CakePHP 6 should be beer cake? Delicious. Stay tuned to find out.    Before I go, I am leaving you with something special. A note from Larry!   As we close out this year, I just want to say thank you from the bottom of my heart. Twenty years ago, CakePHP started as a simple idea shared by a few of us who wanted to make building on the web easier and more enjoyable. Seeing how far it has come, and more importantly, seeing how many lives and careers it has impacted, is something I never take for granted. I am deeply grateful for our team, the core contributors, the community, and our clients who continue to believe in what we do. You are the reason CakePHP and CakeDC are still here, still growing, and still relevant after two decades. Here is to what we have built together, and to what is still ahead. Thank you for being part of this journey. Larry

Written by Amanda on December 24, 2025

66 Views

Pagination of multiple queries in CakePHP

Pagination of multiple queries in CakePHP

A less typical use case for pagination in an appication is the need to paginate multiples queries. In CakePHP you can achieve this with pagination scopes.

Users list

Lest use as an example a simple users list. // src/Controller/UsersController.php class UsersController extends AppController { protected array $paginate = [ 'limit' => 25, ]; public function index() { // Default model pagination $this->set('users', $this->paginate($this->Users)); } } // templates/Users/index.php <h2><?= __('Users list') ?>/h2> <table> <thead> <tr> <th><?= $this->Paginator->sort('name', __('Name')) ?></th> <th><?= $this->Paginator->sort('email', __('Email')) ?></th> <th><?= $this->Paginator->sort('active', __('Active')) ?></th> </tr> </thead> <tbody> <?php foreach ($users as $user): ?> <tr> <td><?= h($user->name) ?></td> <td><?= h($user->email) ?></td> <td><?= $user->active ? 'Yes' : 'No' ?></td> </tr> <?php endforeach; ?> </tbody> </table> <?= $this->Paginator->counter() ?> <?= $this->Paginator->prev('« Previous') ?> <?= $this->Paginator->numbers() ?> <?= $this->Paginator->next('Next »') ?>

Pagination of multiple queries

Now, we want to display two paginated tables, one with the active users and the other with the inactive ones. // src/Controller/UsersController.php class UsersController extends AppController { protected array $paginate = [ 'Users' => [ 'scope' => 'active_users', 'limit' => 25, ], 'InactiveUsers' => [ 'scope' => 'inactive_users', 'limit' => 10, ], ]; public function index() { $activeUsers = $this->paginate( $this->Users->find()->where(['active' => true]), [scope: 'active_users'] ); // Load an additional table object with the custom alias set in the paginate property $inactiveUsersTable = $this->fetchTable('InactiveUsers', [ 'className' => \App\Model\Table\UsersTable::class, 'table' => 'users', 'entityClass' => 'App\Model\Entity\User', ]); $inactiveUsers = $this->paginate( $inactiveUsersTable->find()->where(['active' => false]), [scope: 'inactive_users'] ); $this->set(compact('users', 'inactiveUsers')); } } // templates/Users/index.php <?php // call `setPaginated` first with the results to be displayed next, so the paginator use the correct scope for the links $this->Paginator->setPaginated($users); ?> <h2><?= __('Active Users') ?>/h2> <table> <thead> <tr> <th><?= $this->Paginator->sort('name', __('Name')) ?></th> <th><?= $this->Paginator->sort('email', __('Email')) ?></th> <th><?= $this->Paginator->sort('active', __('Active')) ?></th> </tr> </thead> <tbody> <?php foreach ($users as $user): ?> <tr> <td><?= h($user->name) ?></td> <td><?= h($user->email) ?></td> <td><?= $user->active ? 'Yes' : 'No' ?></td> </tr> <?php endforeach; ?> </tbody> </table> <?= $this->Paginator->counter() ?> <?= $this->Paginator->prev('« Previous') ?> <?= $this->Paginator->numbers() ?> <?= $this->Paginator->next('Next »') ?> <?php // call `setPaginated` first with the results to be displayed next, so the paginator use the correct scope for the links $this->Paginator->setPaginated($inactiveUsers); ?> <h2><?= __('Inactive Users') ?>/h2> <table> <thead> <tr> <th><?= $this->Paginator->sort('name', __('Name')) ?></th> <th><?= $this->Paginator->sort('email', __('Email')) ?></th> <th><?= $this->Paginator->sort('active', __('Active')) ?></th> </tr> </thead> <tbody> <?php foreach ($inactiveUsers as $inactiveUser): ?> <tr> <td><?= h($inactiveUser->name) ?></td> <td><?= h($inactiveUser->email) ?></td> <td><?= $inactiveUser->active ? 'Yes' : 'No' ?></td> </tr> <?php endforeach; ?> </tbody> </table> <?= $this->Paginator->counter() ?> <?= $this->Paginator->prev('« Previous') ?> <?= $this->Paginator->numbers() ?> <?= $this->Paginator->next('Next »') ?> And with this you have two paginated tables in the same request.

Written by Rperez on December 23, 2025

139 Views

Clean DI in CakePHP 5.3: Say Goodbye to fetchTable()

This article is part of the CakeDC Advent Calendar 2025 (December 23rd, 2025)

Introduction: The Death of the "Hidden" Dependency

For years, accessing data in CakePHP meant "grabbing" it from the global state. Whether using TableRegistry::getTableLocator()->get() or the LocatorAwareTrait’s $this->fetchTable(), your classes reached out to a locator to find what they needed. While convenient, this created hidden dependencies. A class constructor might look empty, despite the class being secretly reliant on multiple database tables. This made unit testing cumbersome, forcing you to stub the global TableLocator just to inject a mock. CakePHP 5.3 changes the game with Inversion of Control. With the framework currently in its Release Candidate (RC) stage and a stable release expected soon, now is the perfect time to explore these architectural improvements. By using the new TableContainer as a delegate for your PSR-11 container, tables can now be automatically injected directly into your constructors. This shift to explicit dependencies makes your code cleaner, fully type-hinted, and ready for modern testing standards. The Old Way (Hidden Dependency): public function execute() { $users = $this->fetchTable('Users'); // Where did this come from? } The 5.3 Way (Explicit Dependency): public function __construct(protected UsersTable $users) {} public function execute() { $this->users->find(); // Explicit and testable. }

Enabling the Delegate

Open src/Application.php and update the services() method by delegating table resolution to the TableContainer. // src/Application.php use Cake\ORM\TableContainer; public function services(ContainerInterface $container): void { // Register the TableContainer as a delegate $container->delegate(new TableContainer()); }

How it works under the hood

When you type-hint a class ending in Table (e.g., UsersTable), the main PSR-11 container doesn't initially know how to instantiate it. Because you've registered a delegate, it passes the request to the TableContainer, which then:
  1. Validates: It verifies the class name and ensures it is a subclass of \Cake\ORM\Table.
  2. Locates: It uses the TableLocator to fetch the correct instance (handling all the usual CakePHP ORM configuration behind the scenes).
  3. Resolves: It returns the fully configured Table object back to the main container to be injected.
Note: The naming convention is strict. The TableContainer specifically looks for the Table suffix. If you have a custom class that extends the base Table class but is named UsersRepository, the delegate will skip it, and the container will fail to resolve the dependency.

Practical Example: Cleaner Services

Now, your domain services no longer need to know about the LocatorAwareTrait. They simply ask for what they need. namespace App\Service; use App\Model\Table\UsersTable; class UserManagerService { // No more TableRegistry::get() or $this->fetchTable() public function __construct( protected UsersTable $users ) {} public function activateUser(int $id): void { $user = $this->users->get($id); // ... logic } } Next, open src/Application.php and update the services() method by delegating table resolution to the TableContainer. // src/Application.php use App\Model\Table\UsersTable; use App\Service\UserManagerService; use Cake\ORM\TableContainer; public function services(ContainerInterface $container): void { // Register the TableContainer as a delegate $container->delegate(new TableContainer()); // Register your service with the table as constructor argument $container ->add(UserManagerService::class) ->addArgument(UsersTable::class); }

Why this is a game changer for Testing

Because the table is injected via the constructor, you can now swap it for a mock effortlessly in your test suite without touching the global state of the application. $mockUsers = $this->createMock(UsersTable::class); $service = new UserManagerService($mockUsers); // Pure injection!

Conclusion: Small Change, Big Impact

At first glance, adding a single line to your Application::services() method might seem like a minor update. However, TableContainer represents a significant shift in how we approach CakePHP architecture. By delegating table resolution to the container, we gain:
  • True Type-Safety: Your IDE and static analysis tools now recognize the exact Table class being used. This is a massive win for PHPStan users—no more "Call to an undefined method" errors or messy @var docblock workarounds just to prove to your CI that a method exists.
  • Zero-Effort Mocking: Testing a service no longer requires manipulating the global TableRegistry state. Simply pass a mock object into the constructor and move on.
  • Standardization: Your CakePHP code now aligns with modern PHP practices found in any PSR-compliant ecosystem, making your application more maintainable and easier for new developers to understand.
If you plan to upgrade to CakePHP 5.3 upon its release, this is one of the easiest wins for your codebase. It’s time to stop fetching your tables and start receiving them. This article is part of the CakeDC Advent Calendar 2025 (December 23rd, 2025)

Written by Arusinowski on December 23, 2025

We Bake with CakePHP