set_url_scheme()
云策文档标注
概述
set_url_scheme() 是 WordPress 核心函数，用于设置或修改 URL 的协议方案。它支持多种预定义方案，并能根据 SSL 环境自动处理，常用于确保 URL 在安全或非安全上下文中的一致性。
关键要点
- 函数接受两个参数：$url（必需，绝对 URL）和 $scheme（可选，可为 'http'、'https'、'login'、'login_post'、'admin'、'relative'、'rest'、'rpc' 或 null，默认 null）。
- 当 $scheme 为 null 时，函数基于 is_ssl() 自动选择 'http' 或 'https'；对于 'admin'、'login'、'login_post'、'rpc' 方案，会检查 force_ssl_admin() 以决定是否使用 HTTPS。
- 函数不会为无协议 URL 添加方案，输入 URL 必须包含基础协议（如 'http://'）才能正确替换。
- 输出通过 apply_filters('set_url_scheme', ...) 钩子可过滤，允许开发者自定义结果。
- 相关函数包括 is_ssl() 和 force_ssl_admin()，用于 SSL 检测。
代码示例
$url = 'example.org/what/ever/';
print_r( set_url_scheme( $url, 'https' ) );
// 结果: 'example.org/what/ever'（无变化，因为输入缺少协议）
print_r( set_url_scheme( 'http://' . $url, 'https' ) );
// 结果: 'https://example.org/what/ever'（如果 is_ssl() 为真则为 'https'，否则为 'http'）注意事项
- 确保输入 URL 包含协议（如 'http://'），否则函数无法添加方案，可能导致意外输出。
- 在 SSL 环境中，利用 is_ssl() 自动处理可简化代码，但需注意 force_ssl_admin() 对管理相关方案的影响。
- 函数自 WordPress 3.4.0 引入，4.4.0 版本添加了 'rest' 方案支持。
原文内容
Sets the scheme for a URL.
Parameters
$urlstringrequired-
Absolute URL that includes a scheme
$schemestring|nulloptional-
Scheme to give $url. Currently
'http','https','login','login_post','admin','relative','rest','rpc', or null.Default:
null
Source
function set_url_scheme( $url, $scheme = null ) {
$orig_scheme = $scheme;
if ( ! $scheme ) {
$scheme = is_ssl() ? 'https' : 'http';
} elseif ( 'admin' === $scheme || 'login' === $scheme || 'login_post' === $scheme || 'rpc' === $scheme ) {
$scheme = is_ssl() || force_ssl_admin() ? 'https' : 'http';
} elseif ( 'http' !== $scheme && 'https' !== $scheme && 'relative' !== $scheme ) {
$scheme = is_ssl() ? 'https' : 'http';
}
$url = trim( $url );
if ( str_starts_with( $url, '//' ) ) {
$url = 'http:' . $url;
}
if ( 'relative' === $scheme ) {
$url = ltrim( preg_replace( '#^w+://[^/]*#', '', $url ) );
if ( '' !== $url && '/' === $url[0] ) {
$url = '/' . ltrim( $url, "/ tnrx0B" );
}
} 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 );
}
Hooks
- apply_filters( ‘set_url_scheme’, string $url, string $scheme, string|null $orig_scheme )
-
Filters the resulting URL after setting the scheme.
Skip to note 3 content
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')Skip to note 4 content
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, asset_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)