X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=Civi.php;h=9e4b8dcbfd764a9e0243b80c7a0e54484d88ca19;hb=c218eb568cd6b967adc20ae7c30510a71da5b813;hp=b1e3e44eab0b593eb18144ee3c931c231fde7d18;hpb=1e88220aad73cb323dbf13e8b64e650801c7d1f7;p=civicrm-core.git

diff --git a/Civi.php b/Civi.php
index b1e3e44eab..9e4b8dcbfd 100644
--- a/Civi.php
+++ b/Civi.php
@@ -117,10 +117,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)->setIO(STDIN, STDOUT)->run();
+  public static function pipe(string $negotiationFlags = 'vtl'): void {
+    Civi::service('civi.pipe')
+      ->setIO(STDIN, STDOUT)
+      ->run($negotiationFlags);
   }
 
   /**