Civi::queue() - Optionally accept more `array $params` to auto-initialize queue

diff --git a/Civi.php b/Civi.php
index d081572f992e8bde77fab68f07e5151b255b43e6..dfd8d9004b0e7bd501b58a907d8dfb9036ac4031 100644 (file)
--- a/Civi.php
+++ b/Civi.php
@@ -108,18 +108,24 @@ class Civi {
   /**
    * Fetch a queue object.
    *
+   * Note: Historically, `CRM_Queue_Queue` objects were not persistently-registered. Persistence
+   * is now encouraged. This facade has a bias towards persistently-registered queues.
+   *
    * @param string $name
-   *   Name of the queue.
-   *   The queue must be persistent (stored in `civicrm_queue`).
+   *   The name of a persistent/registered queue (stored in `civicrm_queue`)
+   * @param array{type: string, is_autorun: bool, reset: bool, is_persistent: bool} $params
+   *   Specification for a queue.
+   *   This is not required for accessing an existing queue.
+   *   Specify this if you wish to auto-create the queue or to include advanced options (eg `reset`).
+   *   Example: ['type' => 'SqlParallel']
+   *   Defaults: ['reset'=>FALSE, 'is_persistent'=>TRUE, 'is_autorun'=>FALSE]
    * @return \CRM_Queue_Queue
    * @see \CRM_Queue_Service
    */
-  public static function queue(string $name): CRM_Queue_Queue {
-    return CRM_Queue_Service::singleton()->create([
-      'name' => $name,
-      'reset' => FALSE,
-      'is_persistent' => TRUE,
-    ]);
+  public static function queue(string $name, array $params = []): CRM_Queue_Queue {
+    $defaults = ['reset' => FALSE, 'is_persistent' => TRUE];
+    $params = array_merge($defaults, ['name' => $name], $params);
+    return CRM_Queue_Service::singleton()->create($params);
   }
 
   /**

diff --git a/tests/phpunit/CRM/Queue/QueueTest.php b/tests/phpunit/CRM/Queue/QueueTest.php
index c4b37644b387e94f7f9f7ad83a877910bfbb2ba2..d2ef5b06a4db850c8280c124707edad7c31820b3 100644 (file)
--- a/tests/phpunit/CRM/Queue/QueueTest.php
+++ b/tests/phpunit/CRM/Queue/QueueTest.php
@@ -255,6 +255,32 @@ class CRM_Queue_QueueTest extends CiviUnitTestCase {
     }
   }
 
+  public function testFacadeAutoCreate() {
+    $this->assertDBQuery(0, 'SELECT count(*) FROM civicrm_queue');
+    $q1 = Civi::queue('testFacadeAutoCreate_q1', [
+      'type' => 'Sql',
+    ]);
+    $q2 = Civi::queue('testFacadeAutoCreate_q2', [
+      'type' => 'SqlParallel',
+    ]);
+    $q1Reload = Civi::queue('testFacadeAutoCreate_q1', [
+      /* q1 already exists, so it doesn't matter what type you give. */
+      'type' => 'ZoombaroombaFaketypeGoombapoompa',
+    ]);
+    $this->assertDBQuery(2, 'SELECT count(*) FROM civicrm_queue');
+    $this->assertInstanceOf('CRM_Queue_Queue_Sql', $q1);
+    $this->assertInstanceOf('CRM_Queue_Queue_SqlParallel', $q2);
+    $this->assertInstanceOf('CRM_Queue_Queue_Sql', $q1Reload);
+
+    try {
+      Civi::queue('testFacadeAutoCreate_q3' /* missing type */);
+      $this->fail('Queue lookup should fail. There is neither pre-existing registration nor new details.');
+    }
+    catch (CRM_Core_Exception $e) {
+      $this->assertRegExp(';Missing field "type";', $e->getMessage());
+    }
+  }
+
   /**
    * Test that queue content is reset when reset=>TRUE
    *