framework/helpers/BaseUrl.php
<?php
/**
* @link https://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license https://www.yiiframework.com/license/
*/
namespace yii\helpers;
use Yii;
use yii\base\InvalidArgumentException;
/**
* BaseUrl provides concrete implementation for [[Url]].
*
* Do not use BaseUrl. Use [[Url]] instead.
*
* @author Alexander Makarov <sam@rmcreative.ru>
* @since 2.0
*/
class BaseUrl
{
/**
* @var \yii\web\UrlManager URL manager to use for creating URLs
* @since 2.0.8
*/
public static $urlManager;
/**
* Creates a URL for the given route.
*
* This method will use [[\yii\web\UrlManager]] to create a URL.
*
* You may specify the route as a string, e.g., `site/index`. You may also use an array
* if you want to specify additional query parameters for the URL being created. The
* array format must be:
*
* ```php
* // generates: /index.php?r=site/index¶m1=value1¶m2=value2
* ['site/index', 'param1' => 'value1', 'param2' => 'value2']
* ```
*
* If you want to create a URL with an anchor, you can use the array format with a `#` parameter.
* For example,
*
* ```php
* // generates: /index.php?r=site/index¶m1=value1#name
* ['site/index', 'param1' => 'value1', '#' => 'name']
* ```
*
* A route may be either absolute or relative. An absolute route has a leading slash (e.g. `/site/index`),
* while a relative route has none (e.g. `site/index` or `index`). A relative route will be converted
* into an absolute one by the following rules:
*
* - If the route is an empty string, the current [[\yii\web\Controller::route|route]] will be used;
* - If the route contains no slashes at all (e.g. `index`), it is considered to be an action ID
* of the current controller and will be prepended with [[\yii\web\Controller::uniqueId]];
* - If the route has no leading slash (e.g. `site/index`), it is considered to be a route relative
* to the current module and will be prepended with the module's [[\yii\base\Module::uniqueId|uniqueId]].
*
* Starting from version 2.0.2, a route can also be specified as an alias. In this case, the alias
* will be converted into the actual route first before conducting the above transformation steps.
*
* Below are some examples of using this method:
*
* ```php
* // /index.php?r=site%2Findex
* echo Url::toRoute('site/index');
*
* // /index.php?r=site%2Findex&src=ref1#name
* echo Url::toRoute(['site/index', 'src' => 'ref1', '#' => 'name']);
*
* // https://www.example.com/index.php?r=site%2Findex
* echo Url::toRoute('site/index', true);
*
* // https://www.example.com/index.php?r=site%2Findex
* echo Url::toRoute('site/index', 'https');
*
* // /index.php?r=post%2Findex assume the alias "@posts" is defined as "post/index"
* echo Url::toRoute('@posts');
* ```
*
* @param string|array $route use a string to represent a route (e.g. `index`, `site/index`),
* or an array to represent a route with query parameters (e.g. `['site/index', 'param1' => 'value1']`).
* @param bool|string $scheme the URI scheme to use in the generated URL:
*
* - `false` (default): generating a relative URL.
* - `true`: returning an absolute base URL whose scheme is the same as that in [[\yii\web\UrlManager::$hostInfo]].
* - string: generating an absolute URL with the specified scheme (either `http`, `https` or empty string
* for protocol-relative URL).
*
* @return string the generated URL
* @throws InvalidArgumentException a relative route is given while there is no active controller
*/
public static function toRoute($route, $scheme = false)
{
$route = (array) $route;
$route[0] = static::normalizeRoute($route[0]);
if ($scheme !== false) {
return static::getUrlManager()->createAbsoluteUrl($route, is_string($scheme) ? $scheme : null);
}
return static::getUrlManager()->createUrl($route);
}
/**
* Normalizes route and makes it suitable for UrlManager. Absolute routes are staying as is
* while relative routes are converted to absolute ones.
*
* A relative route is a route without a leading slash, such as "view", "post/view".
*
* - If the route is an empty string, the current [[\yii\web\Controller::route|route]] will be used;
* - If the route contains no slashes at all, it is considered to be an action ID
* of the current controller and will be prepended with [[\yii\web\Controller::uniqueId]];
* - If the route has no leading slash, it is considered to be a route relative
* to the current module and will be prepended with the module's uniqueId.
*
* Starting from version 2.0.2, a route can also be specified as an alias. In this case, the alias
* will be converted into the actual route first before conducting the above transformation steps.
*
* @param string $route the route. This can be either an absolute route or a relative route.
* @return string normalized route suitable for UrlManager
* @throws InvalidArgumentException a relative route is given while there is no active controller
*/
protected static function normalizeRoute($route)
{
$route = Yii::getAlias((string) $route);
if (strncmp($route, '/', 1) === 0) {
// absolute route
return ltrim($route, '/');
}
// relative route
if (Yii::$app->controller === null) {
throw new InvalidArgumentException("Unable to resolve the relative route: $route. No active controller is available.");
}
if (strpos($route, '/') === false) {
// empty or an action ID
return $route === '' ? Yii::$app->controller->getRoute() : Yii::$app->controller->getUniqueId() . '/' . $route;
}
// relative to module
return ltrim(Yii::$app->controller->module->getUniqueId() . '/' . $route, '/');
}
/**
* Creates a URL based on the given parameters.
*
* This method is very similar to [[toRoute()]]. The only difference is that this method
* requires a route to be specified as an array only. If a string is given, it will be treated as a URL.
* In particular, if `$url` is
*
* - an array: [[toRoute()]] will be called to generate the URL. For example:
* `['site/index']`, `['post/index', 'page' => 2]`. Please refer to [[toRoute()]] for more details
* on how to specify a route.
* - a string with a leading `@`: it is treated as an alias, and the corresponding aliased string
* will be returned.
* - an empty string: the currently requested URL will be returned;
* - a normal string: it will be returned as is.
*
* When `$scheme` is specified (either a string or `true`), an absolute URL with host info (obtained from
* [[\yii\web\UrlManager::$hostInfo]]) will be returned. If `$url` is already an absolute URL, its scheme
* will be replaced with the specified one.
*
* Below are some examples of using this method:
*
* ```php
* // /index.php?r=site%2Findex
* echo Url::to(['site/index']);
*
* // /index.php?r=site%2Findex&src=ref1#name
* echo Url::to(['site/index', 'src' => 'ref1', '#' => 'name']);
*
* // /index.php?r=post%2Findex assume the alias "@posts" is defined as "/post/index"
* echo Url::to(['@posts']);
*
* // the currently requested URL
* echo Url::to();
*
* // /images/logo.gif
* echo Url::to('@web/images/logo.gif');
*
* // images/logo.gif
* echo Url::to('images/logo.gif');
*
* // https://www.example.com/images/logo.gif
* echo Url::to('@web/images/logo.gif', true);
*
* // https://www.example.com/images/logo.gif
* echo Url::to('@web/images/logo.gif', 'https');
*
* // //www.example.com/images/logo.gif
* echo Url::to('@web/images/logo.gif', '');
* ```
*
*
* @param array|string $url the parameter to be used to generate a valid URL
* @param bool|string $scheme the URI scheme to use in the generated URL:
*
* - `false` (default): generating a relative URL.
* - `true`: returning an absolute base URL whose scheme is the same as that in [[\yii\web\UrlManager::$hostInfo]].
* - string: generating an absolute URL with the specified scheme (either `http`, `https` or empty string
* for protocol-relative URL).
*
* @return string the generated URL
* @throws InvalidArgumentException a relative route is given while there is no active controller
*/
public static function to($url = '', $scheme = false)
{
if (is_array($url)) {
return static::toRoute($url, $scheme);
}
$url = Yii::getAlias($url);
if ($url === '') {
$url = Yii::$app->getRequest()->getUrl();
}
if ($scheme === false) {
return $url;
}
if (static::isRelative($url)) {
// turn relative URL into absolute
$url = static::getUrlManager()->getHostInfo() . '/' . ltrim($url, '/');
}
return static::ensureScheme($url, $scheme);
}
/**
* Normalize the URL by ensuring it uses specified scheme.
*
* If the URL is relative or the scheme is not a string, normalization is skipped.
*
* @param string $url the URL to process
* @param string $scheme the URI scheme used in the URL (e.g. `http` or `https`). Use an empty string to
* create protocol-relative URL (e.g. `//example.com/path`)
* @return string the processed URL
* @since 2.0.11
*/
public static function ensureScheme($url, $scheme)
{
if (static::isRelative($url) || !is_string($scheme)) {
return $url;
}
if (strncmp($url, '//', 2) === 0) {
// e.g. //example.com/path/to/resource
return $scheme === '' ? $url : "$scheme:$url";
}
if (($pos = strpos($url, '://')) !== false) {
if ($scheme === '') {
$url = substr($url, $pos + 1);
} else {
$url = $scheme . substr($url, $pos);
}
}
return $url;
}
/**
* Returns the base URL of the current request.
* @param bool|string $scheme the URI scheme to use in the returned base URL:
*
* - `false` (default): returning the base URL without host info.
* - `true`: returning an absolute base URL whose scheme is the same as that in [[\yii\web\UrlManager::$hostInfo]].
* - string: returning an absolute base URL with the specified scheme (either `http`, `https` or empty string
* for protocol-relative URL).
* @return string
*/
public static function base($scheme = false)
{
$url = static::getUrlManager()->getBaseUrl();
if ($scheme !== false) {
$url = static::getUrlManager()->getHostInfo() . $url;
$url = static::ensureScheme($url, $scheme);
}
return $url;
}
/**
* Remembers the specified URL so that it can be later fetched back by [[previous()]].
*
* @param string|array $url the URL to remember. Please refer to [[to()]] for acceptable formats.
* If this parameter is not specified, the currently requested URL will be used.
* @param string|null $name the name associated with the URL to be remembered. This can be used
* later by [[previous()]]. If not set, [[\yii\web\User::setReturnUrl()]] will be used with passed URL.
* @see previous()
* @see \yii\web\User::setReturnUrl()
*/
public static function remember($url = '', $name = null)
{
$url = static::to($url);
if ($name === null) {
Yii::$app->getUser()->setReturnUrl($url);
} else {
Yii::$app->getSession()->set($name, $url);
}
}
/**
* Returns the URL previously [[remember()|remembered]].
*
* @param string|null $name the named associated with the URL that was remembered previously.
* If not set, [[\yii\web\User::getReturnUrl()]] will be used to obtain remembered URL.
* @return string|null the URL previously remembered. Null is returned if no URL was remembered with the given name
* and `$name` is not specified.
* @see remember()
* @see \yii\web\User::getReturnUrl()
*/
public static function previous($name = null)
{
if ($name === null) {
return Yii::$app->getUser()->getReturnUrl();
}
return Yii::$app->getSession()->get($name);
}
/**
* Returns the canonical URL of the currently requested page.
*
* The canonical URL is constructed using the current controller's [[\yii\web\Controller::route]] and
* [[\yii\web\Controller::actionParams]]. You may use the following code in the layout view to add a link tag
* about canonical URL:
*
* ```php
* $this->registerLinkTag(['rel' => 'canonical', 'href' => Url::canonical()]);
* ```
*
* @return string the canonical URL of the currently requested page
*/
public static function canonical()
{
$params = Yii::$app->controller->actionParams;
$params[0] = Yii::$app->controller->getRoute();
return static::getUrlManager()->createAbsoluteUrl($params);
}
/**
* Returns the home URL.
*
* @param bool|string $scheme the URI scheme to use for the returned URL:
*
* - `false` (default): returning a relative URL.
* - `true`: returning an absolute base URL whose scheme is the same as that in [[\yii\web\UrlManager::$hostInfo]].
* - string: returning an absolute URL with the specified scheme (either `http`, `https` or empty string
* for protocol-relative URL).
*
* @return string home URL
*/
public static function home($scheme = false)
{
$url = Yii::$app->getHomeUrl();
if ($scheme !== false) {
$url = static::getUrlManager()->getHostInfo() . $url;
$url = static::ensureScheme($url, $scheme);
}
return $url;
}
/**
* Returns a value indicating whether a URL is relative.
* A relative URL does not have host info part.
* @param string $url the URL to be checked
* @return bool whether the URL is relative
*/
public static function isRelative($url)
{
return preg_match('~^[[:alpha:]][[:alnum:]+-.]*://|^//~', $url) === 0;
}
/**
* Creates a URL by using the current route and the GET parameters.
*
* You may modify or remove some of the GET parameters, or add additional query parameters through
* the `$params` parameter. In particular, if you specify a parameter to be null, then this parameter
* will be removed from the existing GET parameters; all other parameters specified in `$params` will
* be merged with the existing GET parameters. For example,
*
* ```php
* // assume $_GET = ['id' => 123, 'src' => 'google'], current route is "post/view"
*
* // /index.php?r=post%2Fview&id=123&src=google
* echo Url::current();
*
* // /index.php?r=post%2Fview&id=123
* echo Url::current(['src' => null]);
*
* // /index.php?r=post%2Fview&id=100&src=google
* echo Url::current(['id' => 100]);
* ```
*
* Note that if you're replacing array parameters with `[]` at the end you should specify `$params` as nested arrays.
* For a `PostSearchForm` model where parameter names are `PostSearchForm[id]` and `PostSearchForm[src]` the syntax
* would be the following:
*
* ```php
* // index.php?r=post%2Findex&PostSearchForm%5Bid%5D=100&PostSearchForm%5Bsrc%5D=google
* echo Url::current([
* $postSearch->formName() => ['id' => 100, 'src' => 'google'],
* ]);
* ```
*
* @param array $params an associative array of parameters that will be merged with the current GET parameters.
* If a parameter value is null, the corresponding GET parameter will be removed.
* @param bool|string $scheme the URI scheme to use in the generated URL:
*
* - `false` (default): generating a relative URL.
* - `true`: returning an absolute base URL whose scheme is the same as that in [[\yii\web\UrlManager::$hostInfo]].
* - string: generating an absolute URL with the specified scheme (either `http`, `https` or empty string
* for protocol-relative URL).
*
* @return string the generated URL
* @since 2.0.3
*/
public static function current(array $params = [], $scheme = false)
{
$currentParams = Yii::$app->getRequest()->getQueryParams();
$currentParams[0] = '/' . Yii::$app->controller->getRoute();
$route = array_replace_recursive($currentParams, $params);
return static::toRoute($route, $scheme);
}
/**
* @return \yii\web\UrlManager URL manager used to create URLs
* @since 2.0.8
*/
protected static function getUrlManager()
{
return static::$urlManager ?: Yii::$app->getUrlManager();
}
}