WordPress.org

Make WordPress Core

Opened 13 months ago

Closed 6 months ago

#36468 closed defect (bug) (fixed)

Error in docs of get_home_url() and home_url()

Reported by: thomaswm Owned by: DrewAPicture
Milestone: 4.7 Priority: normal
Severity: normal Version: 3.0
Component: General Keywords: has-patch
Focuses: docs Cc:

Description

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.

Attachments (1)

36468.patch (1.3 KB) - added by stevenlinx 6 months ago.

Download all attachments as: .zip

Change History (12)

#1 @jeremyfelt
13 months ago

  • Version changed from trunk to 3.0

Docs added in [12598] and [12978]

#2 @thomaswm
13 months ago

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.

#3 @DrewAPicture
13 months ago

  • Keywords needs-patch added

#4 @thomaswm
9 months ago

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 );
    }

This ticket was mentioned in Slack in #core by drew. View the logs.


9 months ago

#6 @DrewAPicture
9 months ago

@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.

This ticket was mentioned in Slack in #docs by morganestes. View the logs.


7 months ago

#8 @morganestes
7 months ago

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

@stevenlinx
6 months ago

#9 @stevenlinx
6 months ago

  • Keywords has-patch added; needs-patch removed

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

#10 @DrewAPicture
6 months ago

  • Milestone changed from Awaiting Review to 4.7

#11 @DrewAPicture
6 months ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

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.

Note: See TracTickets for help on using tickets.