URL 助手

URL 助手文件包含用于处理 URL 的函数。

加载此助手

此助手在每个请求时都会被框架自动加载。

可用函数

以下函数可用

site_url([$uri = ''[, $protocol = null[, $altConfig = null]]])
参数:

  • $uri (array|string) – URI 字符串或 URI 段数组

  • $protocol (string) – 协议，例如：‘http’ 或 ‘https’

  • $altConfig (\Config\App) – 要使用的备用配置

返回值:

站点 URL

返回类型:

string

注意

从 v4.3.0 开始，如果您设置了 Config\App::$allowedHostnames，如果当前 URL 匹配，则此函数将返回包含主机名的 URL。

返回您的站点 URL，如您的配置文件中所指定。index.php 文件（或您在配置文件中设置为站点 Config\App::$indexPage 的任何文件）将被添加到 URL 中，您传递给函数的任何 URI 段也将被添加。

建议您在需要生成本地 URL 时使用此函数，以便在您的 URL 发生更改时，您的页面更具可移植性。

可以可选地将段作为字符串或数组传递给函数。以下是一个字符串示例

<?php

echo site_url('news/local/123');

上面的示例将返回类似以下内容：http://example.com/index.php/news/local/123

以下是如何将段作为数组传递的示例

<?php

$segments = ['news', 'local', '123'];
echo site_url($segments);

如果您要为与您的站点不同的站点生成 URL，并且该站点包含不同的配置首选项，您可能会发现备用配置很有用。我们使用它来对框架本身进行单元测试。

base_url([$uri = ''[, $protocol = null]])
参数:

  • $uri (array|string) – URI 字符串或 URI 段数组

  • $protocol (string) – 协议，例如：‘http’ 或 ‘https’

返回值:

基本 URL

返回类型:

string

注意

从 v4.3.0 开始，如果您设置了 Config\App::$allowedHostnames，如果当前 URL 匹配，则此函数将返回包含主机名的 URL。

注意

在以前的版本中，当没有参数调用此函数时，它返回没有尾部斜杠 (/) 的基本 URL。该错误已修复，从 v4.3.2 开始，它返回带有尾部斜杠的基本 URL。

返回您的站点基本 URL，如您的配置文件中所指定。示例

<?php

echo base_url();

此函数返回与 site_url() 相同的内容，只是没有附加 Config\App::$indexPage。

与 site_url() 一样，您可以提供段作为字符串或数组。以下是一个字符串示例

<?php

echo base_url('blog/post/123');

上面的示例将返回类似以下内容：http://example.com/blog/post/123

这很有用，因为与 site_url() 不同，您可以向文件（例如图像或样式表）提供字符串。例如

<?php

echo base_url('images/icons/edit.png');

这将为您提供类似以下内容：http://example.com/images/icons/edit.png

current_url([$returnObject = false[, $request = null]])
参数:

  • $returnObject (boolean) – 如果您希望返回 URI 实例，而不是字符串，则为 True。

  • $request (IncomingRequest|null) – 用于路径检测的备用请求；在测试中很有用。

返回值:

当前 URL

返回类型:

string|\CodeIgniter\HTTP\URI

返回当前正在查看的页面的完整 URL。当返回字符串时，URL 的查询和片段部分将被删除。当返回 URI 时，查询和片段部分将被保留。

但是出于安全原因，它是根据 Config\App 设置创建的，而不是用于匹配浏览器 URL。

从 v4.3.0 开始，如果您设置了 Config\App::$allowedHostnames，如果当前 URL 匹配，则此函数将返回包含主机名的 URL。

注意

调用 current_url() 等同于执行以下操作

site_url(uri_string());

重要

在 v4.1.2 之前，此函数存在一个错误，导致它忽略了 Config\App::$indexPage 上的配置。

previous_url([$returnObject = false])
参数:

  • $returnObject (boolean) – 如果您希望返回 URI 实例而不是字符串，则为 True。

返回值:

用户之前所在的 URL

返回类型:

string|mixed|\CodeIgniter\HTTP\URI

返回用户之前所在的页面的完整 URL（包括段）。

注意

由于盲目信任 HTTP_REFERER 系统变量存在安全问题，CodeIgniter 会在会话可用时将之前访问的页面存储在会话中。这确保我们始终使用已知且可信的来源。如果会话尚未加载或不可用，则将使用 HTTP_REFERER 的经过清理的版本。

uri_string()
返回值:

URI 字符串

返回类型:

string

返回当前 URL 相对于 baseURL 的路径部分。

例如，当您的 baseURL 为 http://some-site.com/ 且当前 URL 为

http://some-site.com/blog/comments/123

该函数将返回

blog/comments/123

当您的 baseURL 为 http://some-site.com/subfolder/ 且当前 URL 为

http://some-site.com/subfolder/blog/comments/123

该函数将返回

blog/comments/123

注意

在以前的版本中，定义了参数 $relative = false。但是，由于一个 bug，此函数始终返回相对于 baseURL 的路径。从 v4.3.2 开始，该参数已被删除。

注意

在以前的版本中，当您导航到 baseURL 时，此函数返回 /。从 v4.3.2 开始，该 bug 已被修复，它返回一个空字符串 ('')。

index_page([$altConfig = null])
参数:

  • $altConfig (\Config\App) – 要使用的备用配置

返回值:

indexPage 值

返回类型:

string

返回您的站点 indexPage，如您的配置文件中所指定。示例

<?php

echo index_page();

与 site_url() 一样，您可以指定备用配置。如果您为与您的站点不同的站点生成 URL，则可能会发现备用配置很有用，该站点包含不同的配置首选项。我们使用它来对框架本身进行单元测试。

anchor([$uri = ''[, $title = ''[, $attributes = ''[, $altConfig = null]]]])
参数:

  • $uri (mixed) – URI 字符串或 URI 段数组

  • $title (string) – 锚点标题

  • $attributes (mixed) – HTML 属性

  • $altConfig (\Config\App) – 要使用的备用配置

返回值:

HTML 超链接（锚点标签）

返回类型:

string

根据您的本地站点 URL 创建标准 HTML 锚点链接。

第一个参数可以包含您希望附加到 URL 的任何段。与上面的 site_url() 函数一样，段可以是字符串或数组。

注意

如果您正在构建应用程序内部的链接，请不要包含基本 URL (http://...)。这将根据您在配置文件中指定的信息自动添加。仅包含您希望附加到 URL 的 URI 段。

第二个段是您希望链接显示的文本。如果您将其留空，将使用 URL。

第三个参数可以包含您希望添加到链接的属性列表。属性可以是简单的字符串或关联数组。

以下是一些示例

<?php

echo anchor('news/local/123', 'My News', 'title="News title"');
// Prints: <a href="http://example.com/index.php/news/local/123" title="News title">My News</a>

echo anchor('news/local/123', 'My News', ['title' => 'The best news!']);
// Prints: <a href="http://example.com/index.php/news/local/123" title="The best news!">My News</a>

echo anchor('', 'Click here');
// Prints: <a href="http://example.com/index.php">Click here</a>

如上所述，您可以指定备用配置。如果您为与您不同的站点生成链接，该站点包含不同的配置首选项，您可能会发现备用配置很有用。我们将其用于框架本身的单元测试。

注意

传递到锚点函数的属性会自动转义以防止 XSS 攻击。

anchor_popup([$uri = ''[, $title = ''[, $attributes = false[, $altConfig = null]]]])
参数:

  • $uri (string) – URI 字符串

  • $title (string) – 锚点标题

  • $attributes (mixed) – HTML 属性

  • $altConfig (\Config\App) – 要使用的备用配置

返回值:

弹出式超链接

返回类型:

string

与 anchor() 函数几乎相同，只是它在新窗口中打开 URL。 您可以在第三个参数中指定 JavaScript 窗口属性来控制窗口的打开方式。 如果未设置第三个参数，它将简单地使用您自己的浏览器设置打开一个新窗口。

以下是一个带有属性的示例

<?php

$atts = [
    'width'       => 800,
    'height'      => 600,
    'scrollbars'  => 'yes',
    'status'      => 'yes',
    'resizable'   => 'yes',
    'screenx'     => 0,
    'screeny'     => 0,
    'window_name' => '_blank',
];

echo anchor_popup('news/local/123', 'Click Me!', $atts);

如上所述，您可以指定备用配置。如果您为与您不同的站点生成链接，该站点包含不同的配置首选项，您可能会发现备用配置很有用。我们将其用于框架本身的单元测试。

注意

上面的属性是函数默认值，因此您只需要设置与所需不同的属性。 如果您希望函数使用所有默认值，只需在第三个参数中传递一个空数组

<?php

echo anchor_popup('news/local/123', 'Click Me!', []);

注意

window_name 并不是真正的属性，而是 JavaScript window.open() 方法的参数，它接受窗口名称或窗口目标。

注意

除上面列出的属性外，任何其他属性都将被解析为锚标签的 HTML 属性。

注意

传递到 anchor_popup 函数的属性会自动转义，以防止 XSS 攻击。

mailto($email[, $title = ''[, $attributes = '']])
参数:

  • $email (string) – 电子邮件地址

  • $title (string) – 锚点标题

  • $attributes (mixed) – HTML 属性

返回值:

一个“邮件到”超链接

返回类型:

string

创建一个标准的 HTML 电子邮件链接。 使用示例

<?php

echo mailto('[email protected]', 'Click Here to Contact Me');

与上面的 anchor() 选项卡类似，您可以使用第三个参数设置属性。

<?php

$attributes = ['title' => 'Mail me'];
echo mailto('[email protected]', 'Contact Me', $attributes);

注意

传递到 mailto 函数的属性会自动转义以防止 XSS 攻击。

safe_mailto($email[, $title = ''[, $attributes = '']])
参数:

  • $email (string) – 电子邮件地址

  • $title (string) – 锚点标题

  • $attributes (mixed) – HTML 属性

返回值:

一个防垃圾邮件的“邮件到”超链接

返回类型:

string

与 mailto() 函数相同，只是它使用 JavaScript 编写的序数来编写mailto标签的混淆版本，以帮助防止垃圾邮件机器人收集电子邮件地址。

参数:

  • $str (string) – 输入字符串

  • $type (string) – 链接类型（‘email’，‘url’ 或 ‘both’）

  • $popup (bool) – 是否创建弹出链接

返回值:

链接化的字符串

返回类型:

string

自动将字符串中包含的 URL 和电子邮件地址转换为链接。示例

<?php

$string = auto_link($string);

第二个参数决定是转换 URL 和电子邮件，还是只转换其中一个。如果未指定参数，则默认行为是两者都转换。电子邮件链接被编码为 safe_mailto()，如上所示。

仅转换 URL

<?php

$string = auto_link($string, 'url');

仅转换电子邮件地址

<?php

$string = auto_link($string, 'email');

第三个参数决定链接是否在新窗口中显示。该值可以是 true 或 false（布尔值）

<?php

$string = auto_link($string, 'both', true);

注意

唯一识别的 URL 是以 www. 或 :// 开头的 URL。

url_title($str[, $separator = '-'[, $lowercase = false]])
参数:

  • $str (string) – 输入字符串

  • $separator (string) – 单词分隔符（通常为 '-' 或 '_'）

  • $lowercase (bool) – 是否将输出字符串转换为小写

返回值:

URL 格式的字符串

返回类型:

string

该函数接收一个字符串作为输入，并创建一个对用户友好的 URL 字符串。例如，如果您有一个博客，希望在 URL 中使用博客文章的标题，这将非常有用。示例

<?php

$title     = "What's wrong with CSS?";
$url_title = url_title($title);
// Produces: Whats-wrong-with-CSS

第二个参数决定单词分隔符。默认情况下使用连字符。首选选项为：-（连字符）或 _（下划线）。

示例

<?php

$title     = "What's wrong with CSS?";
$url_title = url_title($title, '_');
// Produces: Whats_wrong_with_CSS

第三个参数决定是否强制使用小写字符。默认情况下不强制使用。选项为布尔值 true/false。

示例

<?php

$title     = "What's wrong with CSS?";
$url_title = url_title($title, '-', true);
// Produces: whats-wrong-with-css
mb_url_title($str[, $separator = '-'[, $lowercase = false]])
参数:

  • $str (string) – 输入字符串

  • $separator (string) – 单词分隔符（通常为 '-' 或 '_'）

  • $lowercase (bool) – 是否将输出字符串转换为小写

返回值:

URL 格式的字符串

返回类型:

string

此函数与 url_title() 的功能相同，但会自动转换所有带重音符号的字符。

prep_url([$str = ''[, $secure = false]])
参数:

  • $str (string) – URL 字符串

  • $secure (boolean) – https:// 为 true

返回值:

带协议前缀的 URL 字符串

返回类型:

string

如果 URL 缺少协议前缀，此函数将添加 http:// 或 https://。

将 URL 字符串传递给函数，如下所示

<?php

$url = prep_url('example.com');
url_to($controller[, ...$args])
参数:

  • $controller (string) – 路由名称或 Controller::method

  • ...$args (mixed) – 传递给路由的一个或多个参数。最后一个参数允许您设置语言环境。

返回值:

绝对 URL

返回类型:

string

注意

此函数要求控制器/方法在 app/Config/routes.php 中定义路由。

构建指向应用程序中控制器方法的绝对 URL。示例

<?php

// The route is defined as:
$routes->get('/', 'Home::index');

?>

<a href="<?= url_to('Home::index') ?>">Home</a>
<!-- Result: 'http://example.com/' -->

您还可以向路由添加参数。以下是一个示例

<?php

// The route is defined as:
$routes->get('pages/(:segment)', 'Page::index/$1');

?>

<a href="<?= url_to('Page::index', 'home') ?>">Home</a>
<!-- Result: 'http://example.com/pages/home' -->

这很有用，因为您仍然可以在将链接放入视图后更改路由。

从 v4.3.0 开始，当您在路由中使用 {locale} 时，您可以选择将语言环境值作为最后一个参数指定。

<?php

// The route is defined as:
$routes->add(
    '{locale}/users/(:num)/gallery/(:num)',
    'Galleries::showUserGallery/$1/$2',
    ['as' => 'user_gallery']
);

?>

<a href="<?= url_to('user_gallery', 15, 12, 'en') ?>">View Gallery</a>
<!-- Result: 'http://example.com/en/users/15/gallery/12' -->

有关完整详细信息，请参阅 反向路由 和 命名路由。

url_is($path)
参数:

  • $path (string) – 相对于 baseURL 的 URL 路径，用于检查当前 URI 路径。

返回类型:

布尔值

将当前 URL 的路径与给定路径进行比较，以查看它们是否匹配。示例

<?php

if (url_is('admin')) {
    // ...
}

这将匹配 http://example.com/admin。如果您的 baseURL 是 http://example.com/subdir/，它将匹配 http://example.com/subdir/admin。

您可以使用 * 通配符来匹配 URL 中的任何其他适用字符

<?php

if (url_is('admin*')) {
    // ...
}

这将匹配以下任何内容

  • /admin

  • /admin/

  • /admin/users

  • /admin/users/schools/classmates/…