# 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。URL 中会包含 index.php 文件（或配置文件中 `Config\App::$indexPage` 设置的内容），以及传递给函数的任何 URI 段。

  建议在生成本地 URL 时始终使用此函数，以便在 URL 发生变化时提高页面的可移植性。

  URI 段可以作为字符串或数组传递给函数。字符串示例如下：

      <?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()` 类似，可以提供字符串或数组形式的 URI 段。字符串示例如下：

      <?php

      // Returns like `http://example.com/blog/post/123`
      echo base_url('blog/post/123');

  以上示例将返回类似： http://example.com/blog/post/123

  若第二个参数传递空字符串 `''`，则返回协议相对链接：

      <?php

      // Returns like `//example.com/blog/post/123`
      echo base_url('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`) -- 若设为 true，则返回 URI 实例而非字符串。

    - $request (`IncomingRequest|null`) -- 用于路径检测的替代请求；常用于测试。

  返回:

    当前 URL

  返回类型:

    `string|\CodeIgniter\HTTP\URI`

  返回当前正在浏览的页面的完整 URL。 返回字符串时，URL 的 query 和 fragment 会被移除。 返回 URI 对象时，query 和 fragment 会被保留。

  出于安全考虑，此 URL 基于 `Config\App` 设置生成，并非旨在与浏览器地址栏完全匹配。

  自 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`) -- 若设为 true，则返回 URI 实例而非字符串。

  返回:

    用户之前访问的 URL

  返回类型:

    `string|\CodeIgniter\HTTP\URI`

  返回用户之前访问页面的完整 URL（包括 URI 段）。

  备注

  由于盲目信任 `HTTP_REFERER` 系统变量存在安全隐患，如果 Session 可用，CodeIgniter 会将之前访问的页面存储在 Session 中。这确保了始终使用已知且可信的来源。若 Session 未加载或不可用，则会使用经过清理的 `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 起该问题已修复，现在返回空字符串（`''`）。

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

    - $altConfig (`\Config\App`) -- 使用的替代配置

  返回:

    `indexPage` 的值

  返回类型:

    `string`

  返回配置文件中指定的站点 indexPage。 示例：

      <?php

      echo index_page();

  与 `site_url()` 相同，可以指定替代配置。如果需要为具有不同配置偏好的其他站点生成 URL，此功能非常有用。框架自身的单元测试就使用了此功能。

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

    - $uri (`array|string`) -- URI 字符串或 URI 段数组

    - $title (`string`) -- 锚点标题

    - $attributes (`array|object|string`) -- HTML 属性

    - $altConfig (`\Config\App|null`) -- 使用的替代配置

  返回:

    HTML 超链接（a 标签）

  返回类型:

    `string`

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

  第一个参数可以包含任何希望追加到 URL 的 URI 段。与上述 `site_url()` 函数类似，URI 段可以是字符串或数组。

  备注

  构建应用程序内部链接时，请勿包含基础 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>

  如上所述，可以指定替代配置。在为具有不同配置偏好的其他站点生成链接时，此功能非常有用。

  备注

  传入 anchor 函数的属性会自动进行转义，以防止 XSS 攻击。

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

    - $uri (`string`) -- URI 字符串

    - $title (`string`) -- 锚点标题

    - $attributes (`array|false|object|string`) -- 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() 方法的参数，该方法接受窗口名称或窗口目标。

  备注

  除上述列出的属性外，任何其他属性都会被解析为 a 标签的 HTML 属性。

  备注

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

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

    - $email (`string`) -- 电子邮件地址

    - $title (`string`) -- 锚点标题

    - $attributes (`array|object|string`) -- HTML 属性

  返回:

    "mail to" 超链接

  返回类型:

    `string`

  创建标准 HTML 电子邮件链接。用法示例：

      <?php

      echo mailto('me@my-site.com', 'Click Here to Contact Me');

  与上述 `anchor()` 标签类似，可以使用第三个参数设置属性：

      <?php

      $attributes = ['title' => 'Mail me'];
      echo mailto('me@my-site.com', 'Contact Me', $attributes);

  备注

  传入 mailto 函数的属性会自动进行转义，以防止 XSS 攻击。

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

    - $email (`string`) -- 电子邮件地址

    - $title (`string`) -- 锚点标题

    - $attributes (`array|object|string`) -- HTML 属性

  返回:

    防垃圾邮件的 "mail to" 超链接

  返回类型:

    `string`

  与 `mailto()` 函数相同，但它会使用 JavaScript 编写混淆版的 mailto 标签，通过序数来防止 Email 地址被垃圾邮件机器人抓取。

auto_link($str[, $type = 'both'[, $popup = false]])
  参数:

    - $str (`string`) -- 输入字符串

    - $type (`string`) -- 链接类型（`'email'`、`'url'` 或 `'both'`）

    - $popup (`bool`) -- 是否创建弹出式链接

  返回:

    链接化处理后的字符串

  返回类型:

    `string`

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

      <?php

      $string = auto_link($string);

  第二个参数决定转换 URL、Email 还是两者都转换。若未指定，默认行为是两者都转换。Email 链接按上述 `safe_mailto()` 方式编码。

  仅转换 URL：

      <?php

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

  仅转换电子邮件地址：

      <?php

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

  第三个参数决定链接是否在新窗口中显示，取值为布尔值 true 或 false：

      <?php

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

  备注

  仅识别以 `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()` 相同，但会自动转换所有重音字符。

parse_subdomain($hostname)
  参数:

    - $hostname (`string|null`) -- 待解析的主机名。若为 null，则使用当前请求的主机。

  返回:

    子域名，若不存在则返回空字符串。

  返回类型:

    `string`

  从给定主机名中解析子域名。

  示例如下：

      <?php

      // Outputs "blog"
      echo parse_subdomain('blog.example.com');

      // Outputs an empty string
      echo parse_subdomain('example.com');
      echo parse_subdomain('example.co.uk');

      // Outputs "shop" - correctly handles two-part TLDs
      echo parse_subdomain('shop.example.co.uk');

      // Outputs "shop.old"
      echo parse_subdomain('shop.old.example.co.uk');

  可以通过将已知的两部分 TLD（顶级域名）添加到 `Config\Hostnames::TWO_PART_TLDS` 数组中来自定义识别列表。

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

    - $str (`string`) -- URL 字符串

    - $secure (`boolean`) -- 设为 true 以使用 `https://`

  返回:

    包含协议前缀的 URL 字符串

  返回类型:

    `string`

  当 URL 缺少协议前缀时，此函数会添加 `http://` 或 `https://`。

  用法如下：

      <?php

      $url = prep_url('example.com');

url_to($controller[, ...$args])
  参数:

    - $controller (`string`) -- 路由名称或 Controller::method

    - ...$args (`int|string`) -- 传递给路由的一个或多个参数。最后一个参数可用于设置语言环境。

  返回:

    绝对 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 路径。

  返回类型:

    `boolean`

  将当前 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/...