X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=Civi.php;h=3c9d71f929859835f0d6b1f0d94552c240d5d84a;hb=d9d0e6a4d29ba30bb7bf141a339c2a2d07e70406;hp=828d58ecbd9032997d4d0a5ec3fef361384ce771;hpb=5e13f3883f8e33fcf4722af265b1db9ae5225506;p=civicrm-core.git

diff --git a/Civi.php b/Civi.php
index 828d58ecbd..3c9d71f929 100644
--- a/Civi.php
+++ b/Civi.php
@@ -105,6 +105,29 @@ class Civi {
     return \Civi\Core\Container::getBootService('paths');
   }
 
+  /**
+   * 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
+   *   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, array $params = []): CRM_Queue_Queue {
+    $defaults = ['reset' => FALSE, 'is_persistent' => TRUE];
+    $params = array_merge($defaults, $params, ['name' => $name]);
+    return CRM_Queue_Service::singleton()->create($params);
+  }
+
   /**
    * Obtain the formatting object.
    *
@@ -117,13 +140,27 @@ class Civi {
   /**
    * Initiate a bidirectional pipe for exchanging a series of multiple API requests.
    *
-   * @see \Civi\Pipe\BasicJsonSession
+   * @param string $negotiationFlags
+   *   List of pipe initialization flags. Some combination of the following:
+   *    - 'v': Report version in connection header.
+   *    - 'j': Report JSON-RPC flavors in connection header.
+   *    - 'l': Report on login support in connection header.
+   *    - 't': Trusted session. Logins do not require credentials. API calls may execute with or without permission-checks.
+   *    - 'u': Untrusted session. Logins require credentials. API calls may only execute with permission-checks.
+   *
+   *   The `Civi::pipe()` entry-point is designed to be amenable to shell orchestration (SSH/cv/drush/wp-cli/etc).
+   *   The negotiation flags are therefore condensed to individual characters.
+   *
+   *   It is possible to preserve compatibility while adding new default-flags. However, removing default-flags
+   *   is more likely to be a breaking-change.
+   *
+   *   When adding a new flag, consider whether mutable `option()`s may be more appropriate.
+   * @see \Civi\Pipe\PipeSession
    */
-  public static function pipe(string $protocol = 'jsonrpc20'): void {
-    Civi::service('pipe.' . $protocol)
+  public static function pipe(string $negotiationFlags = 'vtl'): void {
+    Civi::service('civi.pipe')
       ->setIO(STDIN, STDOUT)
-      ->setTrusted(TRUE)
-      ->run();
+      ->run($negotiationFlags);
   }
 
   /**