0 關注者

類別 yii\helpers\Url

所有類別 | 屬性 | 方法
繼承yii\helpers\Url » yii\helpers\BaseUrl
自版本起可用2.0
原始碼 https://github.com/yiisoft/yii2/blob/master/framework/helpers/Url.php

Url 提供一組靜態方法來管理 URL。

關於 Url 的更多詳細資訊和使用方法，請參閱關於 URL 助手的使用指南文章。

公共屬性

隱藏繼承的屬性

屬性 類型 描述 定義於
$urlManager yii\web\UrlManager 用於建立 URL 的 URL 管理器 yii\helpers\BaseUrl

公共方法

隱藏繼承的方法

方法 描述 定義於
base() 返回當前請求的基礎 URL。 yii\helpers\BaseUrl
canonical() 傳回目前請求頁面的標準網址。 yii\helpers\BaseUrl
current() 使用目前的路由和 GET 參數建立網址。 yii\helpers\BaseUrl
ensureScheme() 透過確保網址使用指定的 scheme 來正規化網址。 yii\helpers\BaseUrl
home() 傳回首頁網址。 yii\helpers\BaseUrl
isRelative() 傳回一個值，指出網址是否為相對網址。 yii\helpers\BaseUrl
previous() 傳回先前 記住 的網址。 yii\helpers\BaseUrl
remember() 記住指定的網址，以便稍後可以透過 previous() 取回。 yii\helpers\BaseUrl
to() 根據給定的參數建立網址。 yii\helpers\BaseUrl
toRoute() 為給定的路由建立網址。 yii\helpers\BaseUrl

Protected Methods

隱藏繼承的方法

方法 描述 定義於
getUrlManager() yii\helpers\BaseUrl
normalizeRoute() 正規化路由並使其適用於 UrlManager。絕對路由保持不變，而相對路由則轉換為絕對路由。 yii\helpers\BaseUrl

Method Details

隱藏繼承的方法

base() public static method

Defined in: yii\helpers\BaseUrl::base()

返回當前請求的基礎 URL。

public static string base ( $scheme = false )
$scheme boolean|string

要在傳回的基礎網址中使用的 URI scheme

  • false (預設)：傳回不含主機資訊的基礎網址。
  • true：傳回絕對基礎網址，其 scheme 與 yii\web\UrlManager::$hostInfo 中的 scheme 相同。
  • string：傳回具有指定 scheme 的絕對基礎網址 (http、https 或空字串，用於協定相對網址)。
 

                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;
}
canonical() public static method

Defined in: yii\helpers\BaseUrl::canonical()

傳回目前請求頁面的標準網址。

標準網址是使用目前控制器的 yii\web\Controller::$route 和 yii\web\Controller::$actionParams 建構的。您可以在版面配置視圖中使用以下程式碼來新增關於標準網址的連結標籤

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

目前請求頁面的標準網址

 

                public static function canonical()
{
    $params = Yii::$app->controller->actionParams;
    $params[0] = Yii::$app->controller->getRoute();
    return static::getUrlManager()->createAbsoluteUrl($params);
}
current() public static method (available since version 2.0.3)

Defined in: yii\helpers\BaseUrl::current()

使用目前的路由和 GET 參數建立網址。

您可以修改或移除某些 GET 參數，或透過 $params 參數新增其他查詢參數。特別是，如果您將參數指定為 null，則此參數將從現有的 GET 參數中移除；$params 中指定的所有其他參數將與現有的 GET 參數合併。例如，

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

請注意，如果您要使用結尾為 [] 的陣列參數進行替換，則應將 $params 指定為巢狀陣列。對於參數名稱為 PostSearchForm[id] 和 PostSearchForm[src] 的 PostSearchForm 模型，語法如下

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

將與目前 GET 參數合併的參數關聯陣列。如果參數值為 null，則將移除對應的 GET 參數。
$scheme boolean|string

要在產生的網址中使用的 URI scheme

  • false (預設)：產生相對網址。
  • true：傳回絕對基礎網址，其 scheme 與 yii\web\UrlManager::$hostInfo 中的 scheme 相同。
  • string：產生具有指定 scheme 的絕對網址 (http、https 或空字串，用於協定相對網址)。
return string

產生的網址

 

                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);
}
ensureScheme() public static method (available since version 2.0.11)

Defined in: yii\helpers\BaseUrl::ensureScheme()

透過確保網址使用指定的 scheme 來正規化網址。

如果網址是相對網址，或 scheme 不是字串，則會略過正規化。

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

要處理的網址
$scheme string

網址中使用的 URI scheme (例如 http 或 https)。使用空字串來建立協定相對網址 (例如 //example.com/path)
return string

已處理的網址

 

                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;
}
getUrlManager() protected static method (available since version 2.0.8)

Defined in: yii\helpers\BaseUrl::getUrlManager()

protected static yii\web\UrlManager getUrlManager ( )
return yii\web\UrlManager

用於建立網址的 URL 管理器

 

                protected static function getUrlManager()
{
    return static::$urlManager ?: Yii::$app->getUrlManager();
}
home() public static method

Defined in: yii\helpers\BaseUrl::home()

傳回首頁網址。

public static string home ( $scheme = false )
$scheme boolean|string

用於傳回網址的 URI scheme

  • false (預設)：傳回相對網址。
  • true：傳回絕對基礎網址，其 scheme 與 yii\web\UrlManager::$hostInfo 中的 scheme 相同。
  • string：傳回具有指定 scheme 的絕對網址 (http、https 或空字串，用於協定相對網址)。
return string

首頁網址

 

                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;
}
isRelative() public static method

Defined in: yii\helpers\BaseUrl::isRelative()

傳回一個值，指出網址是否為相對網址。

相對網址沒有主機資訊部分。

public static boolean isRelative ( $url )
$url string

要檢查的網址
return boolean

網址是否為相對網址

 

                public static function isRelative($url)
{
    return preg_match('~^[[:alpha:]][[:alnum:]+-.]*://|^//~', $url) === 0;
}
normalizeRoute() protected static method

Defined in: yii\helpers\BaseUrl::normalizeRoute()

正規化路由並使其適用於 UrlManager。絕對路由保持不變，而相對路由則轉換為絕對路由。

相對路由是沒有前導斜線的路由，例如 "view"、"post/view"。

  • 如果路由是空字串，將使用目前的 route；
  • 如果路由完全不包含斜線，則會將其視為目前控制器的動作 ID，並在其前面加上 yii\web\Controller::$uniqueId；
  • 如果路由沒有前導斜線，則會將其視為相對於目前模組的路由，並在其前面加上模組的 uniqueId。

從 2.0.2 版開始，路由也可以指定為別名。在這種情況下，別名將首先轉換為實際路由，然後再執行上述轉換步驟。

protected static string normalizeRoute ( $route )
$route string

路由。這可以是絕對路由或相對路由。
return string

適用於 UrlManager 的正規化路由
throws yii\base\InvalidArgumentException

當沒有活動控制器時給定相對路由

 

                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, '/');
}
previous() public static method

Defined in: yii\helpers\BaseUrl::previous()

傳回先前 記住 的網址。

See also

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

與先前記住的網址相關聯的名稱。如果未設定，將使用 yii\web\User::getReturnUrl() 取得記住的網址。
return string|null

先前記住的網址。如果沒有使用給定名稱記住網址，且未指定 $name，則傳回 Null。

 

                public static function previous($name = null)
{
    if ($name === null) {
        return Yii::$app->getUser()->getReturnUrl();
    }
    return Yii::$app->getSession()->get($name);
}
remember() public static method

Defined in: yii\helpers\BaseUrl::remember()

記住指定的網址，以便稍後可以透過 previous() 取回。

See also

public static void remember ( $url = '', $name = null )
$url string|array

要記住的網址。請參閱 to() 以取得可接受的格式。如果未指定此參數，將使用目前請求的網址。
$name string|null

與要記住的網址相關聯的名稱。稍後可以由 previous() 使用。如果未設定，將搭配傳遞的網址使用 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);
    }
}
to() public static method

Defined in: yii\helpers\BaseUrl::to()

根據給定的參數建立網址。

此方法與 toRoute() 非常相似。唯一的區別在於此方法僅要求將路由指定為陣列。如果給定字串，則會將其視為網址。特別是，如果 $url 是

  • 陣列：將呼叫 toRoute() 以產生網址。例如：['site/index']、['post/index', 'page' => 2]。請參閱 toRoute() 以取得關於如何指定路由的更多詳細資訊。
  • 帶有前導 @ 的字串：它被視為別名，並將傳回對應的別名字串。
  • 空字串：將傳回目前請求的網址；
  • 一般字串：將按原樣傳回。

當指定 $scheme (字串或 true) 時，將傳回帶有主機資訊 (從 yii\web\UrlManager::$hostInfo 取得) 的絕對網址。如果 $url 已經是絕對網址，其 scheme 將替換為指定的 scheme。

以下是一些使用此方法的範例

// /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', '');
public static string to ( $url = '', $scheme = false )
$url array|string

用於產生有效網址的參數
$scheme boolean|string

要在產生的網址中使用的 URI scheme

  • false (預設)：產生相對網址。
  • true：傳回絕對基礎網址，其 scheme 與 yii\web\UrlManager::$hostInfo 中的 scheme 相同。
  • string：產生具有指定 scheme 的絕對網址 (http、https 或空字串，用於協定相對網址)。
return string

產生的網址
throws yii\base\InvalidArgumentException

當沒有活動控制器時給定相對路由

 

                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);
}
toRoute() public static method

Defined in: yii\helpers\BaseUrl::toRoute()

為給定的路由建立網址。

此方法將使用 yii\web\UrlManager 來建立網址。

您可以將路由指定為字串，例如 site/index。如果您想要為要建立的網址指定其他查詢參數，您也可以使用陣列。陣列格式必須是

// generates: /index.php?r=site/index&param1=value1&param2=value2
['site/index', 'param1' => 'value1', 'param2' => 'value2']

如果您想要建立帶有錨點的網址，您可以使用帶有 # 參數的陣列格式。例如，

// generates: /index.php?r=site/index&param1=value1#name
['site/index', 'param1' => 'value1', '#' => 'name']

路由可以是絕對路由或相對路由。絕對路由具有前導斜線 (例如 /site/index)，而相對路由則沒有 (例如 site/index 或 index)。相對路由將透過以下規則轉換為絕對路由

  • 如果路由是空字串，將使用目前的 route；
  • 如果路由完全不包含斜線 (例如 index)，則會將其視為目前控制器的動作 ID，並在其前面加上 yii\web\Controller::$uniqueId；
  • 如果路由沒有前導斜線 (例如 site/index)，則會將其視為相對於目前模組的路由，並在其前面加上模組的 uniqueId。

從 2.0.2 版開始，路由也可以指定為別名。在這種情況下，別名將首先轉換為實際路由，然後再執行上述轉換步驟。

以下是一些使用此方法的範例

// /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');
public static string toRoute ( $route, $scheme = false )
$route string|array

使用字串來表示路由 (例如 index、site/index)，或使用陣列來表示帶有查詢參數的路由 (例如 ['site/index', 'param1' => 'value1'])。
$scheme boolean|string

要在產生的網址中使用的 URI scheme

  • false (預設)：產生相對網址。
  • true：傳回絕對基礎網址，其 scheme 與 yii\web\UrlManager::$hostInfo 中的 scheme 相同。
  • string：產生具有指定 scheme 的絕對網址 (http、https 或空字串，用於協定相對網址)。
return string

產生的網址
throws yii\base\InvalidArgumentException

當沒有活動控制器時給定相對路由

 

                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);
}