/**
 * Sets the scheme for a URL.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $url Absolute URL that includes a scheme
 * @param string|null $scheme Optional. Scheme to give $url. Currently, 'http', 'https', 'login',
 *                            'admin', 'relative', 'rest' or null. Default null.
 * @return string $url URL with chosen scheme.
 * @throws Exception
 */
function set_url_scheme(string $url, ?string $scheme = null): string;

/**
 * Retrieves a modified URL query string.
 *
 * Uses `query.arg.port` filter hook.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $key A query variable key.
 * @param string $value A query variable value, or a URL to act upon.
 * @param string $url A URL to act upon.
 * @return string Returns modified url query string.
 * @throws Exception
 */
function add_query_arg(string $key, string $value, string $url): string;

/**
 * Returns the url based on route.
 *
 * @file core/Shared/Helpers/url.php
 * @param string|null $path Relative path.
 * @return string
 */
function url(?string $path = null): string;

/**
 * Returns the url for a given site.
 *
 * Returns 'https' if `is_ssl()` evaluates to true and 'http' otherwise. If `$scheme` is
 * 'http' or 'https', `is_ssl(`) is overridden.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $path   Optional. Route name or route relative to the site url. Default '/'.
 * @param string|null $scheme Optional. Scheme to give the site URL context. Accepts
 *                       'http', 'https', 'login', 'admin', or 'relative'.
 *                       Default null.
 * @return string Site url link.
 * @throws Exception
 */
function cms_site_url(string $path = '', ?string $scheme = null): string;

/**
 * Returns the url to the admin area for a given site.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $path Optional. Path relative to the admin url. Default empty.
 * @param string $scheme Optional. The scheme to use. Accepts 'http' or 'https',
 *                       to force those schemes. Default 'admin'.
 * @return string Admin url link with optional path appended.
 * @throws Exception
 */
function cms_admin_url(string $path = '', string $scheme = 'admin'): string;

/**
 * Returns the url for a given site where the front end is accessible.
 *
 * The protocol will be 'https' if `is_ssl()` evaluates to true; If `$scheme` is
 * 'http' or 'https', `is_ssl()` is overridden.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $path Optional. Path relative to the home url. Default empty.
 * @param string|null $scheme Optional. Scheme to give the home URL context. Accepts
 *                            'http', 'https', 'relative', or null. Default null.
 * @return string Home url link with optional path appended.
 * @throws Exception
 */
function cms_home_url(string $path = '', ?string $scheme = null): string;

/**
 * Returns the login url for a given site.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $redirect Path to redirect to on log in.
 * @param string $path Optional. Path relative to the login url. Default empty.
 * @param string|null $scheme Optional. Scheme to give the logout URL context. Accepts
 *                             'http', 'https', 'relative', or null. Default 'login'.
 * @return string Returns the login url.
 * @throws Exception
 */
function cms_login_url(string $redirect = '', string $path = '', ?string $scheme = 'login'): string;

/**
 * Returns the login url for a given site.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $redirect Path to redirect to on logout.
 * @param string $path Optional. Path relative to the logout url. Default empty.
 * @param string|null $scheme Optional. Scheme to give the logout URL context. Accepts
 *                             'http', 'https', 'relative', or null. Default 'logout'.
 * @return string Returns the logout url.
 * @throws Exception
 */
function cms_logout_url(string $redirect = '', string $path = '', ?string $scheme = 'logout'): string;

/**
 * Returns the url for a given site.
 *
 * Returns 'https' if `is_ssl()` evaluates to true and 'http' otherwise. If `$scheme` is
 * 'http' or 'https', `is_ssl()` is overridden.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $path Optional. Route relative to the site url. Default '/'.
 * @param string|null $scheme Optional. Scheme to give the site URL context. Accepts
 *                        'http', 'https', 'login', 'admin', or 'relative'.
 *                        Default null.
 * @return string Site url link.
 * @throws Exception
 */
function site_url(string $path = '', ?string $scheme = null): string;

/**
 * Returns the url to the admin area for a given site.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $path Optional. Path relative to the admin url. Default empty.
 * @param string $scheme Optional. The scheme to use. Accepts 'http' or 'https',
 *                        to force those schemes. Default 'admin'.
 * @return string Admin url link with optional path appended.
 * @throws Exception
 */
function admin_url(string $path = '', string $scheme = 'admin'): string;

/**
 * Returns the url for a given site where the front end is accessible.
 *
 * The protocol will be 'https' if `is_ssl()` evaluates to true; If `$scheme` is
 * 'http' or 'https', `is_ssl()` is overridden.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $path Optional. Path relative to the home url. Default empty.
 * @param string|null $scheme Optional. Scheme to give the home URL context. Accepts
 *                             'http', 'https', 'relative', or null. Default null.
 * @return string Home url link with optional path appended.
 * @throws Exception
 */
function home_url(string $path = '', ?string $scheme = null): string;

/**
 * Returns the login url for a given site.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $redirect Path to redirect to on log in.
 * @param string $path Optional. Path relative to the login url. Default empty.
 * @param string|null $scheme Optional. Scheme to give the home URL context. Accepts
 *                             'http', 'https', 'relative', or null. Default 'login'.
 * @return string Returns the login url.
 * @throws Exception
 */
function login_url(string $redirect = '', string $path = '', ?string $scheme = 'login'): string;

/**
 * Returns the login url for a given site.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $redirect Path to redirect to on logout.
 * @param string $path Optional. Path relative to the logout url. Default empty.
 * @param string|null $scheme Optional. Scheme to give the logout URL context. Accepts
 *                             'http', 'https', 'relative', or null. Default 'logout'.
 * @return string Returns the logout url.
 * @throws Exception
 */
function logout_url(string $redirect = '', string $path = '', ?string $scheme = 'logout'): string;

/**
 * Returns the admin login url for a given site.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $redirect Path to redirect to on log in.
 * @param string $path Optional. Path relative to the login url. Default empty.
 * @param string|null $scheme Optional. Scheme to give the home URL context. Accepts
 *                             'http', 'https', 'relative', or null. Default 'login'.
 * @return string Returns the login url.
 * @throws Exception
 */
function admin_login_url(string $redirect = '', string $path = '', ?string $scheme = 'login'): string;

/**
 * Returns the admin logout url for a given site.
 *
 * @file core/Shared/Helpers/url.php
 * @param string $redirect Path to redirect to on logout.
 * @param string $path Optional. Path relative to the logout url. Default empty.
 * @param string|null $scheme Optional. Scheme to give the logout URL context. Accepts
 *                             'http', 'https', 'relative', or null. Default 'logout'.
 * @return string Returns the logout url.
 * @throws Exception
 */
function admin_logout_url(string $redirect = '', string $path = '', ?string $scheme = 'login'): string;