fix: add support for custom config files in commands

.github/workflows/deptrac.yml

@@ -20,4 +20,4 @@ on:
 
 jobs:
   deptrac:
-    uses: codeigniter4/.github/.github/workflows/deptrac.yml@main
+    uses: codeigniter4/.github/.github/workflows/deptrac.yml@CI46

LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
 Copyright (c) 2023 Michal Sniatala
-Copyright (c) 2023 CodeIgniter Foundation
+Copyright (c) 2023-2025 CodeIgniter Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/commands.md

@@ -63,6 +63,7 @@ Allows you to consume jobs from a specific queue.
 * `-priority` - The priority for the jobs from the queue (comma separated). If not provided explicit, will follow the priorities defined in the config via `$queuePriorities` for the given queue. Disabled by default.
 * `-tries` - The number of attempts after which the job will be considered as failed. Overrides settings from the Job class. Disabled by default.
 * `-retry-after` - The number of seconds after which the job is to be restarted in case of failure. Overrides settings from the Job class. Disabled by default.
+* `-config` - The alternative config file to use. Default value relies on `config('Queue')`. Use namespace to define an alternative, e.g. `Acme\\Config\\Queue`.
 * `--stop-when-empty` - Stop when the queue is empty.
 
 ##### Example
@@ -75,6 +76,10 @@ It will listen for 5 jobs from the `emails` queue and then stop.
 
 It will work the same as the previous command but will first consume jobs from the `emails` queue that were added with the `low` priority.
 
+    php spark queue:work email -config Acme\\Config\\Queue
+
+This is how we would use an alternative config file. However, usually, you will not need to specify it. It's recommended to use only a single config file across your application, **but** if you are building a modular system, you can use [Registrars](https://codeigniter.com/user_guide/general/configuration.html#registrars) to update the queue config file from within your module.
+
 ### queue:stop
 
 Allows you to stop a specific queue in a safe way. It does this as soon as the job that is running in the queue is completed.
@@ -83,6 +88,10 @@ Allows you to stop a specific queue in a safe way. It does this as soon as the j
 
 * `queueName` - Name of the queue we will work with.
 
+##### Options
+
+* `-config` - The alternative config file to use. Default value relies on `config('Queue')`.
+
 ##### Example
 
     php spark queue:stop emails
@@ -106,6 +115,7 @@ Allows you to view all failed jobs. Also only from a specific queue
 ##### Options
 
 * `-queue` - Queue name.
+* `-config` - The alternative config file to use. Default value relies on `config('Queue')`.
 
 ##### Example
 
@@ -124,6 +134,7 @@ Allows you to retry failed jobs back to the queue.
 ##### Options
 
 * `-queue` -  Queue name.
+* `-config` - The alternative config file to use. Default value relies on `config('Queue')`.
 
 ##### Example
 
@@ -139,6 +150,10 @@ Allows you to delete the failed job by ID
 
 * `id` - ID of the failed job.
 
+##### Options
+
+* `-config` - The alternative config file to use. Default value relies on `config('Queue')`.
+
 ##### Example
 
     php spark queue:forget 123
@@ -151,6 +166,7 @@ Allows you to delete many failed jobs at once. Based on the failed date and queu
 
 * `-hours` - Number of hours.
 * `-queue` - Queue name.
+* `-config` - The alternative config file to use. Default value relies on `config('Queue')`.
 
 ##### Example
 

src/Commands/QueueClear.php

@@ -13,18 +13,12 @@
 
 namespace CodeIgniter\Queue\Commands;
 
-use CodeIgniter\CLI\BaseCommand;
 use CodeIgniter\CLI\CLI;
+use CodeIgniter\Queue\Config\Queue as QueueConfig;
+use CodeIgniter\Queue\Exceptions\QueueException;
 
-class QueueClear extends BaseCommand
+class QueueClear extends QueueCommand
 {
-    /**
-     * The Command's Group
-     *
-     * @var string
-     */
-    protected $group = 'Queue';
-
     /**
      * The Command's Name
      *
@@ -55,6 +49,15 @@ class QueueClear extends BaseCommand
         'queueName' => 'Name of the queue we will work with.',
     ];
 
+    /**
+     * The Command's Options
+     *
+     * @var array<string, string>
+     */
+    protected $options = [
+        '-config' => 'The alternative config file to use. Default value: relies on config(\'Queue\')',
+    ];
+
     /**
      * Actually execute a command.
      */
@@ -68,7 +71,16 @@ public function run(array $params)
             return EXIT_ERROR;
         }
 
-        service('queue')->clear($queue);
+        try {
+            /** @var QueueConfig $config */
+            $config = $this->handleConfig($params);
+        } catch (QueueException $e) {
+            CLI::error($e->getMessage());
+
+            return EXIT_ERROR;
+        }
+
+        service('queue', $config)->clear($queue);
 
         CLI::print('Queue ', 'yellow');
         CLI::print($queue, 'light_yellow');

src/Commands/QueueCommand.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter Queue.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Queue\Commands;
+
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+use CodeIgniter\Queue\Config\Queue as QueueConfig;
+use CodeIgniter\Queue\Exceptions\QueueException;
+
+abstract class QueueCommand extends BaseCommand
+{
+    /**
+     * The Command's Group
+     *
+     * @var string
+     */
+    protected $group = 'Queue';
+
+    /**
+     * @throws QueueException
+     */
+    protected function handleConfig(array $params)
+    {
+        $configName = $params['config'] ?? CLI::getOption('config');
+
+        if ($configName !== null) {
+            $config = config($configName);
+
+            if ($config === null) {
+                throw QueueException::forIncorrectConfigFile();
+            }
+
+            return $config;
+        }
+
+        return config('Queue');
+    }
+
+    protected function getConfigHash(QueueConfig $config): string
+    {
+        return md5($config::class);
+    }
+}

src/Commands/QueueFailed.php

@@ -13,19 +13,12 @@
 
 namespace CodeIgniter\Queue\Commands;
 
-use CodeIgniter\CLI\BaseCommand;
 use CodeIgniter\CLI\CLI;
 use CodeIgniter\Queue\Config\Queue as QueueConfig;
+use CodeIgniter\Queue\Exceptions\QueueException;
 
-class QueueFailed extends BaseCommand
+class QueueFailed extends QueueCommand
 {
-    /**
-     * The Command's Group
-     *
-     * @var string
-     */
-    protected $group = 'Queue';
-
     /**
      * The Command's Name
      *
@@ -53,7 +46,8 @@ class QueueFailed extends BaseCommand
      * @var array<string, string>
      */
     protected $options = [
-        '-queue' => 'Queue name.',
+        '-queue'  => 'Queue name.',
+        '-config' => 'The alternative config file to use. Default value: relies on config(\'Queue\')',
     ];
 
     /**
@@ -64,10 +58,16 @@ public function run(array $params)
         // Read params
         $queue = $params['queue'] ?? CLI::getOption('queue');
 
-        /** @var QueueConfig $config */
-        $config = config('Queue');
+        try {
+            /** @var QueueConfig $config */
+            $config = $this->handleConfig($params);
+        } catch (QueueException $e) {
+            CLI::error($e->getMessage());
+
+            return EXIT_ERROR;
+        }
 
-        $results = service('queue')->listFailed($queue);
+        $results = service('queue', $config)->listFailed($queue);
 
         $thead = ['ID', 'Connection', 'Queue', 'Class', 'Failed At'];
         $tbody = [];

src/Commands/QueueFlush.php

@@ -13,18 +13,12 @@
 
 namespace CodeIgniter\Queue\Commands;
 
-use CodeIgniter\CLI\BaseCommand;
 use CodeIgniter\CLI\CLI;
+use CodeIgniter\Queue\Config\Queue as QueueConfig;
+use CodeIgniter\Queue\Exceptions\QueueException;
 
-class QueueFlush extends BaseCommand
+class QueueFlush extends QueueCommand
 {
-    /**
-     * The Command's Group
-     *
-     * @var string
-     */
-    protected $group = 'Queue';
-
     /**
      * The Command's Name
      *
@@ -52,8 +46,9 @@ class QueueFlush extends BaseCommand
      * @var array<string, string>
      */
     protected $options = [
-        '-hours' => 'Number of hours.',
-        '-queue' => 'Queue name.',
+        '-hours'  => 'Number of hours.',
+        '-queue'  => 'Queue name.',
+        '-config' => 'The alternative config file to use. Default value: relies on config(\'Queue\')',
     ];
 
     /**
@@ -65,11 +60,20 @@ public function run(array $params)
         $hours = $params['hours'] ?? CLI::getOption('hours');
         $queue = $params['queue'] ?? CLI::getOption('queue');
 
+        try {
+            /** @var QueueConfig $config */
+            $config = $this->handleConfig($params);
+        } catch (QueueException $e) {
+            CLI::error($e->getMessage());
+
+            return EXIT_ERROR;
+        }
+
         if ($hours !== null) {
             $hours = (int) $hours;
         }
 
-        service('queue')->flush($hours, $queue);
+        service('queue', $config)->flush($hours, $queue);
 
         if ($hours === null) {
             CLI::write(sprintf('All failed jobs has been removed from the queue %s', $queue), 'green');

src/Commands/QueueForget.php

@@ -13,18 +13,12 @@
 
 namespace CodeIgniter\Queue\Commands;
 
-use CodeIgniter\CLI\BaseCommand;
 use CodeIgniter\CLI\CLI;
+use CodeIgniter\Queue\Config\Queue as QueueConfig;
+use CodeIgniter\Queue\Exceptions\QueueException;
 
-class QueueForget extends BaseCommand
+class QueueForget extends QueueCommand
 {
-    /**
-     * The Command's Group
-     *
-     * @var string
-     */
-    protected $group = 'Queue';
-
     /**
      * The Command's Name
      *
@@ -55,6 +49,15 @@ class QueueForget extends BaseCommand
         'id' => 'ID of the failed job.',
     ];
 
+    /**
+     * The Command's Options
+     *
+     * @var array<string, string>
+     */
+    protected $options = [
+        '-config' => 'The alternative config file to use. Default value: relies on config(\'Queue\')',
+    ];
+
     /**
      * Actually execute a command.
      */
@@ -68,7 +71,16 @@ public function run(array $params)
             return EXIT_ERROR;
         }
 
-        if (service('queue')->forget((int) $id)) {
+        try {
+            /** @var QueueConfig $config */
+            $config = $this->handleConfig($params);
+        } catch (QueueException $e) {
+            CLI::error($e->getMessage());
+
+            return EXIT_ERROR;
+        }
+
+        if (service('queue', $config)->forget((int) $id)) {
             CLI::write(sprintf('Failed job with ID %s has been removed.', $id), 'green');
         } else {
             CLI::write(sprintf('Could not find the failed job with ID %s', $id), 'red');

src/Commands/QueuePublish.php

@@ -13,14 +13,12 @@
 
 namespace CodeIgniter\Queue\Commands;
 
-use CodeIgniter\CLI\BaseCommand;
 use CodeIgniter\CLI\CLI;
 use CodeIgniter\Publisher\Publisher;
 use Throwable;
 
-class QueuePublish extends BaseCommand
+class QueuePublish extends QueueCommand
 {
-    protected $group       = 'Queue';
     protected $name        = 'queue:publish';
     protected $description = 'Publish Queue config file into the current application.';