Make WordPress Core

Opened 8 years ago

Closed 8 years ago

#36468 closed defect (bug) (fixed)

Error in docs of get_home_url() and home_url()

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


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 8 years ago.

Download all attachments as: .zip

Change History (12)

#1 @jeremyfelt
8 years ago

  • Version changed from trunk to 3.0

Docs added in [12598] and [12978]

#2 @thomaswm
8 years 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
8 years ago

  • Keywords needs-patch added

#4 @thomaswm
8 years 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';
            $scheme = parse_url( $url, PHP_URL_SCHEME );

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

8 years ago

#6 @DrewAPicture
8 years 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.

8 years ago

#8 @morganestes
8 years ago

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

8 years ago

#9 @stevenlinx
8 years 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
8 years ago

  • Milestone changed from Awaiting Review to 4.7

#11 @DrewAPicture
8 years 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.