Merge pull request #8512 from kenjis/docs-base-url-protocol-relative

docs: add undocumented `base_url()` protocol-relative link

Author: kenjis

system/HTTP/SiteURI.php

@@ -369,8 +369,10 @@ protected function applyParts(array $parts): void
     /**
      * For base_url() helper.
      *
-     * @param array|string $relativePath URI string or array of URI segments
-     * @param string|null  $scheme       URI scheme. E.g., http, ftp
+     * @param array|string $relativePath URI string or array of URI segments.
+     * @param string|null  $scheme       URI scheme. E.g., http, ftp. If empty
+     *                                   string '' is set, a protocol-relative
+     *                                   link is returned.
      */
     public function baseUrl($relativePath = '', ?string $scheme = null): string
     {
@@ -406,9 +408,11 @@ private function stringifyRelativePath($relativePath): string
     /**
      * For site_url() helper.
      *
-     * @param array|string $relativePath URI string or array of URI segments
-     * @param string|null  $scheme       URI scheme. E.g., http, ftp
-     * @param App|null     $config       Alternate configuration to use
+     * @param array|string $relativePath URI string or array of URI segments.
+     * @param string|null  $scheme       URI scheme. E.g., http, ftp. If empty
+     *                                   string '' is set, a protocol-relative
+     *                                   link is returned.
+     * @param App|null     $config       Alternate configuration to use.
      */
     public function siteUrl($relativePath = '', ?string $scheme = null, ?App $config = null): string
     {

system/Helpers/url_helper.php

@@ -23,9 +23,11 @@
     /**
      * Returns a site URL as defined by the App config.
      *
-     * @param array|string $relativePath URI string or array of URI segments
-     * @param string|null  $scheme       URI scheme. E.g., http, ftp
-     * @param App|null     $config       Alternate configuration to use
+     * @param array|string $relativePath URI string or array of URI segments.
+     * @param string|null  $scheme       URI scheme. E.g., http, ftp. If empty
+     *                                   string '' is set, a protocol-relative
+     *                                   link is returned.
+     * @param App|null     $config       Alternate configuration to use.
      */
     function site_url($relativePath = '', ?string $scheme = null, ?App $config = null): string
     {
@@ -42,8 +44,10 @@ function site_url($relativePath = '', ?string $scheme = null, ?App $config = nul
      * Returns the base URL as defined by the App config.
      * Base URLs are trimmed site URLs without the index page.
      *
-     * @param array|string $relativePath URI string or array of URI segments
-     * @param string|null  $scheme       URI scheme. E.g., http, ftp
+     * @param array|string $relativePath URI string or array of URI segments.
+     * @param string|null  $scheme       URI scheme. E.g., http, ftp. If empty
+     *                                   string '' is set, a protocol-relative
+     *                                   link is returned.
      */
     function base_url($relativePath = '', ?string $scheme = null): string
     {

user_guide_src/source/helpers/url_helper.rst

@@ -20,9 +20,9 @@ The following functions are available:
 
 .. php:function:: site_url([$uri = ''[, $protocol = null[, $altConfig = null]]])
 
-    :param  array|string         $uri: URI string or array of URI segments
-    :param  string        $protocol: Protocol, e.g., 'http' or 'https'
-    :param  \\Config\\App $altConfig: Alternate configuration to use
+    :param  array|string         $uri: URI string or array of URI segments.
+    :param  string        $protocol: Protocol, e.g., 'http' or 'https'. If empty string '' is set, a protocol-relative link is returned.
+    :param  \\Config\\App $altConfig: Alternate configuration to use.
     :returns: Site URL
     :rtype:    string
 
@@ -56,8 +56,8 @@ The following functions are available:
 
 .. php:function:: base_url([$uri = ''[, $protocol = null]])
 
-    :param  array|string   $uri: URI string or array of URI segments
-    :param  string  $protocol: Protocol, e.g., 'http' or 'https'
+    :param  array|string   $uri: URI string or array of URI segments.
+    :param  string  $protocol: Protocol, e.g., 'http' or 'https'. If empty string '' is set, a protocol-relative link is returned.
     :returns: Base URL
     :rtype: string
 
@@ -83,6 +83,11 @@ The following functions are available:
     The above example would return something like:
     **http://example.com/blog/post/123**
 
+    If you pass an empty string ``''`` as the second parameter, it returns
+    the protocol-relative link:
+
+    .. literalinclude:: url_helper/026.php
+
     This is useful because unlike :php:func:`site_url()`, you can supply a
     string to a file, such as an image or stylesheet. For example:
 

user_guide_src/source/helpers/url_helper/004.php

@@ -1,3 +1,4 @@
 <?php
 
+// Returns like `http://example.com/blog/post/123`
 echo base_url('blog/post/123');

user_guide_src/source/helpers/url_helper/026.php

@@ -0,0 +1,4 @@
+<?php
+
+// Returns like `//example.com/blog/post/123`
+echo base_url('blog/post/123', '');