Error in docs of get_home_url() and home_url()

[thomaswm]

In the docs of get_home_url() and home_url(), it says:

Returns the ‘home’ option with the appropriate protocol, ‘https’ if is_ssl() and ‘http’ otherwise. If $scheme is ‘http’ or ‘https’, is_ssl() is overridden.

That's not entirely correct. If get_home_url() is called without the $scheme parameter, then:

• If is_ssl() is true, then get_home_url() will return a URL with the HTTPS scheme.
• If is_ssl() is false, then get_home_url() will return a URL with the same scheme as the home option. That can be either HTTP or HTTPS.

[jeremyfelt]

Docs added in [12598] and [12978]

[thomaswm]

Originally, the docs matched the actual behaviour of the functions. In [21937], however, the code for choosing the scheme has changed, but the docs haven't been updated.

[thomaswm]

I've just realized that [35274] has introduced another error in the documentation of get_home_url() and home_url(): The docs now say about the $scheme parameter:

Accepts 'http', 'https', 'relative', 'rest', or null.

That's not correct. get_home_url() and home_url() only accept three different non-null values for $scheme: 'http', 'https' and 'relative'. Setting $scheme = 'rest' will have the same effect as setting $scheme = null. See lines 2977ff. in link-template.php:

    if ( ! in_array( $scheme, array( 'http', 'https', 'relative' ) ) ) {
        if ( is_ssl() && ! is_admin() && 'wp-login.php' !== $pagenow )
            $scheme = 'https';
        else
            $scheme = parse_url( $url, PHP_URL_SCHEME );
    }

[DrewAPicture]

@thomaswm: Documentation on $scheme accepting 'rest' isn't incorrect, it's just maybe not well-explained.

As mentioned in the linked Slack discussion above this comment, support for a 'rest' pseudo-scheme was added for the benefit of filters applied in conjunction with REST requests. This is why the pseudo-scheme was added to the docs for get_home_url() et al at the same time as the rest functions.

So while functions like get_home_url() do not themselves handle the 'rest' pseudo-scheme, they are technically supported.

[morganestes]

It sounds like we need to standardize on what documentation to include for $scheme = 'rest', and what other functions this would apply to.

[stevenlinx]

1.) A patch was uploaded, which addressed the opening issue raised by @thomaswm

2.) The second issue raised was addressed by the comment from @DrewAPicture

[DrewAPicture]

In 39054:

Docs: Clarify descriptions for home_url() and get_home_url() on the true effect of the $scheme parameter.

Part props thomaswm.
Props stevenlinx.
Fixes #36468.