Civi::url() - Add support for vars

Author: totten

Civi.php

@@ -247,6 +247,10 @@ public static function settings($domainID = NULL) {
    * Ex: Link to a static asset (resource-file) in an extension.
    *   $url = Civi::url('ext://org.civicrm.search_kit/css/crmSearchTasks.css');
    *
+   * Ex: Link with variable substitution
+   *   $url = Civi::url('frontend://civicrm/ajax/api4/[entity]/[action]')
+   *      ->addVars(['entity' => 'Foo', 'action' => 'bar']);
+   *
    * NOTE: CiviCRM is integrated into many environments, and they handle URL-construction different ways.
    * For example, in Joomla+WordPress, there are separate sub-applications for the public-facing
    * frontend UI (`/`) and the staff-facing backend UI (`/wp-admin/` or `/administrator/`) -- each follows

Civi/Core/Url.php

@@ -64,6 +64,13 @@ final class Url {
    */
   private $ssl = NULL;
 
+  /**
+   * List of values to mix-in to the final/rendered URL.
+   *
+   * @var string[]|null
+   */
+  private $vars;
+
   /**
    * @param string $logicalUri
    * @param string|null $flags
@@ -237,6 +244,31 @@ public function setSsl(?bool $ssl): Url {
     return $this;
   }
 
+  /**
+   * @return string[]|null
+   */
+  public function getVars(): ?array {
+    return $this->vars;
+  }
+
+  /**
+   * @param string[]|null $vars
+   */
+  public function setVars(?array $vars): Url {
+    $this->vars = $vars;
+    return $this;
+  }
+
+  /**
+   * @param string[] $vars
+   *
+   * @return $this
+   */
+  public function addVars(array $vars): Url {
+    $this->vars = array_merge($this->vars ?: [], $vars);
+    return $this;
+  }
+
   /**
    * @param string $flags
    *   A series of flag-letters. Any of the following:
@@ -339,6 +371,14 @@ public function __toString(): string {
       $result = 'http:' . substr($result, 6);
     }
 
+    if ($this->vars !== NULL) {
+      // Replace variables
+      $result = preg_replace_callback('/\[(\w+)\]/', function($m) {
+        $var = $m[1];
+        return isset($this->vars[$var]) ? urlencode($this->vars[$var]) : "[$var]";
+      }, $result);
+    }
+
     return $this->htmlEscape ? htmlentities($result) : $result;
   }