From 524699483ed8ebe2503e015081f888d276650543 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Fri, 21 Jul 2023 15:25:46 -0700
Subject: [PATCH] (NFC) Civi::url() - Various docblocks

---
 Civi.php          | 17 ++++++-----------
 Civi/Core/Url.php | 45 +++++++++++++++++++++++++++++++++++++++------
 2 files changed, 45 insertions(+), 17 deletions(-)

diff --git a/Civi.php b/Civi.php
index c2a025d38e..70afbdd396 100644
--- a/Civi.php
+++ b/Civi.php
@@ -251,27 +251,22 @@ class Civi {
    *   $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
-   * a different URL-formula. But in Drupal, all use the same formula. To
-   *
    * @param string $logicalUri
    *   Logical URI. The scheme of the URI may be one of:
    *     - 'frontend://' (Front-end page-route for constituents)
    *     - 'backend://' (Back-end page-route for staff)
    *     - 'service://` (Web-service page-route for automated integrations; aka webhooks and IPNs)
    *     - 'current://' (Whichever UI is currently active)
-   *     - 'assetBuilder://' (Dynamically-generated asset-file)
+   *     - 'assetBuilder://' (Dynamically-generated asset-file; see \Civi\Core\AssetBuilder)
    *     - 'ext://' (Static asset-file provided by an extension)
    *   An empty scheme (`//hello.txt`) is equivalent to `current://hello.txt`.
    * @param string|null $flags
    *   List of flags. Some combination of the following:
-   *   - 'a': absolute
-   *   - 'r': relative
-   *   - 'h': html
-   *   - 'p': plain text
-   *   - 's': ssl
+   *   - 'a': absolute (aka `setPreferFormat('absolute')`)
+   *   - 'r': relative (aka `setPreferFormat('relative')`)
+   *   - 'h': html (aka `setHtmlEscape(TRUE)`)
+   *   - 'p': plain text (aka `setHtmlEscape(FALSE)`)
+   *   - 's': ssl (aka `setSsl(TRUE)`)
    *   FIXME: Should we have a flag for appending 'resCacheCode'?
    * @return \Civi\Core\Url
    *   URL object which may be modified or rendered as text.
diff --git a/Civi/Core/Url.php b/Civi/Core/Url.php
index 6e9a1e0a47..b14ca4ab56 100644
--- a/Civi/Core/Url.php
+++ b/Civi/Core/Url.php
@@ -8,6 +8,11 @@ namespace Civi\Core;
  * As input, this class takes a *logical URI*, which may include a range of configurable sub-parts (path, query, fragment, etc).
  *
  * As output, it provides a *concrete URL* that can be used by a web-browser to make requests.
+ *
+ * The typical way to construct a URL object is through `Civi::url()`, which features more
+ * documentation and examples.
+ *
+ * @see \Civi::url()
  */
 final class Url {
 
@@ -207,7 +212,13 @@ final class Url {
   }
 
   /**
+   * Specify whether to prefer absolute or relative formatting.
+   *
    * @param string|null $preferFormat
+   *   One of:
+   *   - 'relative': Prefer relative format, if available
+   *   - 'absolute': Prefer absolute format
+   *   - NULL: Decide format based on current environment/request. (Ordinary web UI requests prefer 'relative'.)
    */
   public function setPreferFormat(?string $preferFormat): Url {
     $this->preferFormat = $preferFormat;
@@ -222,7 +233,10 @@ final class Url {
   }
 
   /**
+   * Specify whether to enable HTML escaping of the final output.
+   *
    * @param bool $htmlEscape
+   * @return $this
    */
   public function setHtmlEscape(bool $htmlEscape): Url {
     $this->htmlEscape = $htmlEscape;
@@ -237,7 +251,12 @@ final class Url {
   }
 
   /**
+   * Specify whether the hyperlink should use SSL.
+   *
    * @param bool|null $ssl
+   *   TRUE: Force SSL on. (Convert "http:" to "https:")
+   *   FALSE: Force SSL off. (Convert "https:" to "http:")
+   *   NULL: Inherit current SSL-ness
    */
   public function setSsl(?bool $ssl): Url {
     $this->ssl = $ssl;
@@ -252,7 +271,15 @@ final class Url {
   }
 
   /**
+   * Specify a list of variables. After composing all parts of the URL, variables will be replaced
+   * with their URL-encoded values.
+   *
+   * Example:
+   *   Civi::url('frontend://civicrm/greeter?cid=[contact]&msg=[message]')
+   *     ->setVars(['contact' => 123, 'message' => 'Hello to you & you & you!');
+   *
    * @param string[]|null $vars
+   * @return $this
    */
   public function setVars(?array $vars): Url {
     $this->vars = $vars;
@@ -260,8 +287,14 @@ final class Url {
   }
 
   /**
-   * @param string[] $vars
+   * Add more variables. After composing all parts of the URL, variables will be replaced
+   * with their URL-encoded values.
    *
+   * Example:
+   *   Civi::url('frontend://civicrm/greeter?cid=[contact]&msg=[message]')
+   *     ->addVars(['contact' => 123, 'message' => 'Hello to you & you & you!');
+   *
+   * @param string[] $vars
    * @return $this
    */
   public function addVars(array $vars): Url {
@@ -270,12 +303,12 @@ final class Url {
   }
 
   /**
+   * Apply a series of flags using short-hand notation.
+   *
    * @param string $flags
-   *   A series of flag-letters. Any of the following:
-   *   - [a]bsolute
-   *   - [r]elative
-   *   - [h]tml
-   *   - [s]sl
+   *   List of flag-letters, such as (a)bsolute or (r)elative
+   *   For a full list, see Civi::url().
+   * @see Civi::url()
    * @return $this
    */
   public function useFlags(string $flags): Url {
-- 
2.25.1