BaseUrl

API reference › yii › helpers › BaseUrl

class	yii\helpers\BaseUrl
Since	2.0
Source	framework/helpers/BaseUrl.php

1 subclass

• Url

BaseUrl provides concrete implementation for Url.

Do not use BaseUrl. Use Url instead.

Properties

Property	Type	Description	Defined by
$urlManager static	yii\web\UrlManager	URL manager to use for creating URLs Default: null. Available since 2.0.8.	BaseUrl

Methods

Method	Description	Defined by
base() static	Returns the base URL of the current request.	BaseUrl
canonical() static	Returns the canonical URL of the currently requested page.	BaseUrl
current() static	Creates a URL by using the current route and the GET parameters.	BaseUrl
ensureScheme() static	Normalize the URL by ensuring it uses specified scheme.	BaseUrl
home() static	Returns the home URL.	BaseUrl
isRelative() static	Returns a value indicating whether a URL is relative.	BaseUrl
previous() static	Returns the URL previously remembered.	BaseUrl
remember() static	Remembers the specified URL so that it can be later fetched back by previous().	BaseUrl
to() static	Creates a URL based on the given parameters.	BaseUrl
toRoute() static	Creates a URL for the given route.	BaseUrl
getUrlManager() protected static		BaseUrl
normalizeRoute() protected static	Normalizes route and makes it suitable for UrlManager. Absolute routes are staying as is while relative routes are converted to absolute ones.	BaseUrl
resolveCurrentRoute() protected static	Resolves the route of the currently requested page.	BaseUrl

Method details

base()

public static function base(bool|string $scheme = false): string

Returns the base URL of the current request.

Parameters

Parameter	Type	Description
$scheme	bool|string	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 UrlManager::$hostInfo. - string: returning an absolute base URL with the specified scheme (either http, https or empty string for protocol-relative URL).

Returns

string

canonical()

public static function canonical(): string

Returns the canonical URL of the currently requested page.

The canonical URL is constructed using the current controller’s Controller::$route and Controller::$actionParams. You may use the following code in the layout view to add a link tag about canonical URL:

$this->registerLinkTag(['rel' => 'canonical', 'href' => Url::canonical()]);

When no controller is active (for example, a standalone action dispatched through Module::$actionMap or Module::$actionNamespace), the route falls back to Application::$requestedRoute and no action parameters are appended.

Returns

string: The canonical URL of the currently requested page

current()

public static function current(array $params = [], bool|string $scheme = false): string

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,

// 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:

// index.php?r=post%2Findex&PostSearchForm%5Bid%5D=100&PostSearchForm%5Bsrc%5D=google
echo Url::current([
    $postSearch->formName() => ['id' => 100, 'src' => 'google'],
]);

Parameters

Parameter	Type	Description
$params	array	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.
$scheme	bool|string	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 UrlManager::$hostInfo. - string: generating an absolute URL with the specified scheme (either http, https or empty string for protocol-relative URL).

Returns

string: The generated URL

Since

2.0.3

ensureScheme()

public static function ensureScheme(string $url, string $scheme): string

Normalize the URL by ensuring it uses specified scheme.

If the URL is relative or the scheme is not a string, normalization is skipped.

Parameters

Parameter	Type	Description
$url	string	The URL to process
$scheme	string	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)

Returns

string: The processed URL

Since

2.0.11

home()

public static function home(bool|string $scheme = false): string

Returns the home URL.

Parameters

Parameter	Type	Description
$scheme	bool|string	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 UrlManager::$hostInfo. - string: returning an absolute URL with the specified scheme (either http, https or empty string for protocol-relative URL).

Returns

string: Home URL

isRelative()

public static function isRelative(string $url): bool

Returns a value indicating whether a URL is relative.

A relative URL does not have host info part.

Parameters

Parameter	Type	Description
$url	string	The URL to be checked

Returns

bool: Whether the URL is relative

previous()

public static function previous(string|null $name = null): string|null

Returns the URL previously remembered.

Parameters

Parameter	Type	Description
$name	string|null	The named associated with the URL that was remembered previously. If not set, User::getReturnUrl() will be used to obtain remembered URL.

Returns

string|null: The URL previously remembered. Null is returned if no URL was remembered with the given name and $name is not specified.

See also

• remember()
• User::getReturnUrl()

remember()

public static function remember(string|array $url = '', string|null $name = null): mixed

Remembers the specified URL so that it can be later fetched back by previous().

Parameters

Parameter	Type	Description
$url	string|array	The URL to remember. Please refer to to() for acceptable formats. If this parameter is not specified, the currently requested URL will be used.
$name	string|null	The name associated with the URL to be remembered. This can be used later by previous(). If not set, User::setReturnUrl() will be used with passed URL.

Returns

mixed

See also

• previous()
• User::setReturnUrl()

to()

public static function to(array|string $url = '', bool|string $scheme = false): string

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 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:

// /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', '');

Parameters

Parameter	Type	Description
$url	array|string	The parameter to be used to generate a valid URL
$scheme	bool|string	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 UrlManager::$hostInfo. - string: generating an absolute URL with the specified scheme (either http, https or empty string for protocol-relative URL).

Returns

string: The generated URL

Throws

• yii\base\InvalidArgumentException: a relative route is given while there is no active controller

toRoute()

public static function toRoute(string|array $route, bool|string $scheme = false): string

Creates a URL for the given route.

This method will use 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:

// generates: /index.php?r=site/index&param1=value1&param2=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,

// generates: /index.php?r=site/index&param1=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 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 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 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:

// /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');

Parameters

Parameter	Type	Description
$route	string|array	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']).
$scheme	bool|string	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 UrlManager::$hostInfo. - string: generating an absolute URL with the specified scheme (either http, https or empty string for protocol-relative URL).

Returns

string: The generated URL

Throws

• yii\base\InvalidArgumentException: a relative route is given while there is no active controller

getUrlManager()

protected static function getUrlManager(): yii\web\UrlManager

Returns

yii\web\UrlManager: URL manager used to create URLs

Since

2.0.8

normalizeRoute()

protected static function normalizeRoute(string $route): string

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 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 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.

Parameters

Parameter	Type	Description
$route	string	The route. This can be either an absolute route or a relative route.

Returns

string: Normalized route suitable for UrlManager

Throws

• yii\base\InvalidArgumentException: a relative route is given while there is no active controller

resolveCurrentRoute()

protected static function resolveCurrentRoute(): string

Resolves the route of the currently requested page.

Returns the active controller’s route when a controller is handling the request. For standalone actions dispatched without a hosting controller (through Module::$actionMap or Module::$actionNamespace), falls back to Application::$requestedRoute.

Returns

string: Route of the currently requested page, without a leading slash.

Throws

• yii\base\InvalidConfigException: if no controller is active and Application::$requestedRoute is empty.

Since

22.0