set_url_scheme( string $url, string|null $scheme = null )

Sets the scheme for a URL.


Description Description


Parameters Parameters

$url

(string) (Required) Absolute URL that includes a scheme

$scheme

(string|null) (Optional) Scheme to give $url. Currently 'http', 'https', 'login', 'login_post', 'admin', 'relative', 'rest', 'rpc', or null.

Default value: null


Top ↑

Return Return

(string) $url URL with chosen scheme.


Top ↑

Source Source

File: wp-includes/link-template.php

function set_url_scheme( $url, $scheme = null ) {
	$orig_scheme = $scheme;

	if ( ! $scheme ) {
		$scheme = is_ssl() ? 'https' : 'http';
	} elseif ( $scheme === 'admin' || $scheme === 'login' || $scheme === 'login_post' || $scheme === 'rpc' ) {
		$scheme = is_ssl() || force_ssl_admin() ? 'https' : 'http';
	} elseif ( $scheme !== 'http' && $scheme !== 'https' && $scheme !== 'relative' ) {
		$scheme = is_ssl() ? 'https' : 'http';
	}

	$url = trim( $url );
	if ( substr( $url, 0, 2 ) === '//' ) {
		$url = 'http:' . $url;
	}

	if ( 'relative' == $scheme ) {
		$url = ltrim( preg_replace( '#^\w+://[^/]*#', '', $url ) );
		if ( $url !== '' && $url[0] === '/' ) {
			$url = '/' . ltrim( $url, "/ \t\n\r\0\x0B" );
		}
	} else {
		$url = preg_replace( '#^\w+://#', $scheme . '://', $url );
	}

	/**
	 * Filters the resulting URL after setting the scheme.
	 *
	 * @since 3.4.0
	 *
	 * @param string      $url         The complete URL including scheme and path.
	 * @param string      $scheme      Scheme applied to the URL. One of 'http', 'https', or 'relative'.
	 * @param string|null $orig_scheme Scheme requested for the URL. One of 'http', 'https', 'login',
	 *                                 'login_post', 'admin', 'relative', 'rest', 'rpc', or null.
	 */
	return apply_filters( 'set_url_scheme', $url, $scheme, $orig_scheme );
}

Top ↑

Changelog Changelog

Changelog
Version Description
4.4.0 The 'rest' scheme was added.
3.4.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Drew Jaynes

    Important Note: set_url_scheme() does NOT add a scheme to a bare URL. If you pass in ‘example.org/what/ever’, you’ll get ‘example.org/what/ever’ out the other side. For this reason, you should always add a basic scheme to URLs if you know the input URL won’t have one, e.g. ‘https://’.

    $url = 'example.org/what/ever/'
    print_r( set_url_scheme( $url, 'https' ) );
    // Result: 'example.org/what/ever'
    
    print_r( set_url_scheme( 'http://' . $url, 'https' ) );
    // Result: 'https://example.org/what/ever ('https' if is_ssl() is true, otherwise 'http')
    
  2. Skip to note 2 content
    Contributed by Drew Jaynes

    Usage with is_ssl()

    One of the nice things about set_url_scheme() is that if you’re in an SSL environment and everything is working properly, you don’t necessarily need to define a scheme, as set_url_scheme() will do that for you.

    For example:

    $url = 'http://example.org/some/permalink';
    
    print_r( set_url_scheme( $url ) );
    // If is_ssl() is true:
    // Result: 'https://example.org/some/permalink
    //
    // If is_ssl() is false:
    // Result: 'http://example.org/some/permalink (no change)
    

You must log in before being able to contribute a note or feedback.