# 全局函数和常量

CodeIgniter 提供了一些全局定义的函数和变量，你可以在任何地方使用它们。 这些函数和变量不需要加载任何额外的库或辅助函数。

## 全局函数

### 服务访问器

cache([$key])
  参数:

    - $key (`string`) -- 要从缓存中检索的项目的缓存名称（可选）

  返回:

    缓存对象，或从缓存中检索到的项目

  返回类型:

    `mixed`

  如果没有提供 $key，将返回缓存引擎实例。如果提供了 $key， 将返回当前缓存中存储的 $key 的值，如果未找到值则返回 null。

  示例：

      <?php

      $foo   = cache('foo');
      $cache = cache();

config(string $name[, bool $getShared = true])
  参数:

    - $name (`string`) -- 配置类名。

    - $getShared (`bool`) -- 是否返回共享实例。

  返回:

    配置实例。

  返回类型:

    `object|null`

  从工厂获取配置实例的更简单方式。

  详情请参阅 配置 和 工厂。

  `config()` 内部使用 `Factories::config()`。 有关第一个参数 `$name` 的详细信息，请参阅 加载类。

cookie(string $name[, string $value = ''[, array $options = []]])
  参数:

    - $name (`string`) -- Cookie 名称

    - $value (`string`) -- Cookie 值

    - $options (`array`) -- Cookie 选项

  返回类型:

    `Cookie`

  返回:

    `Cookie` 实例

  Throws:

    `CookieException`

  创建新 Cookie 实例的更简单方式。

cookies([array $cookies = [][, bool $getGlobal = true]])
  参数:

    - $cookies (`array`) -- 如果 `getGlobal` 为 `false`，此参数将传递给 `CookieStore` 的构造函数。

    - $getGlobal (`bool`) -- 如果为 `false`，则创建一个新的 `CookieStore` 实例。

  返回类型:

    `CookieStore`

  返回:

    当前 `Response` 中保存的 `CookieStore` 实例，或一个新的 `CookieStore` 实例。

  获取 `Response` 保存的全局 `CookieStore` 实例。

env($key[, $default = null])
  参数:

    - $key (`string`) -- 要检索的环境变量名称

    - $default (`mixed`) -- 如果未找到值时返回的默认值。

  返回:

    环境变量、默认值或 null。

  返回类型:

    `mixed`

  用于检索先前设置到环境中的值， 或在未找到时返回默认值。会将布尔值格式化为实际的布尔值， 而不是字符串表示形式。

  当与 .env 文件结合使用时特别有用，用于设置 特定于环境本身的值，如数据库 设置、API 密钥等。

esc($data[, $context = 'html'[, $encoding]])
  参数:

    - $data (`string|array`) -- 要转义的信息。

    - $context (`string`) -- 转义上下文。默认为 'html'。

    - $encoding (`string`) -- 字符串的字符编码。

  返回:

    转义后的数据。

  返回类型:

    `mixed`

  转义要包含在网页中的数据，以帮助防止 XSS 攻击。 这使用 Laminas Escaper 库来处理实际的数据过滤。

  如果 $data 是字符串，则简单地转义并返回它。 如果 $data 是数组，则循环遍历它，转义每个键/值对的 '值'。

  有效的上下文值：`html`、`js`、`css`、`url`、`attr`、`raw`

helper($filename)
  参数:

    - $filename (`string|array`) -- 要加载的辅助函数文件名，或名称数组。

  加载辅助函数文件。

  详情请参阅 辅助函数 页面。

lang($line[, $args[, $locale]])
  参数:

    - $line (`string`) -- 语言文件名和要检索的文本键。

    - $args (`array`) -- 用于替换占位符的数据数组。

    - $locale (`string`) -- 指定要使用的不同区域设置，而不是当前区域设置。

  返回:

    语言文件中的文本

  返回类型:

    `list<string>|string`

  从语言文件中检索文本。

  详情请参阅 语言本地化。

model($name[, $getShared = true[, &$conn = null]])
  参数:

    - $name (`string`) -- 模型类名。

    - $getShared (`boolean`) -- 是否返回共享实例。

    - $conn (`ConnectionInterface|null`) -- 数据库连接。

  返回:

    模型实例

  返回类型:

    `object`

  获取模型实例的更简单方式。

  `model()` 内部使用 `Factories::models()`。 有关第一个参数 `$name` 的详细信息，请参阅 加载类。

  另请参阅 使用 CodeIgniter 的模型。

old($key[, $default = null[, $escape = 'html']])
  参数:

    - $key (`string`) -- 要检查的旧表单数据名称。

    - $default (`string|null`) -- 如果 $key 不存在时返回的默认值。

    - $escape (`false|string`) -- 转义 上下文或 false 以禁用它。

  返回:

    定义键的值，或默认值。

  返回类型:

    `array|string|null`

  提供了一种简单的方式来访问提交表单后的“旧输入数据”。

  示例：

      <?php

      // in controller, checking form submittal
      if (! $model->save($user)) {
          // 'withInput()' is what specifies "old data" should be saved.
          return redirect()->back()->withInput();
      }

      ?>

      <!-- In your view file: -->
      <input type="email" name="email" value="<?= old('email') ?>">

      <!-- Or with arrays: -->
      <input type="email" name="user[email]" value="<?= old('user.email') ?>">

备注

如果你正在使用 `set_value()`、`set_select()`、 `set_checkbox()` 和 `set_radio()` 函数（位于 表单辅助函数 中），此功能已内置。只有 在不使用表单辅助函数时才需要使用此函数。

session([$key])
  参数:

    - $key (`string`) -- 要检查的会话项名称。

  返回:

    如果没有提供 $key，则返回 Session 对象实例；如果提供了 $key，则返回会话中 $key 对应的值，或 null。

  返回类型:

    `mixed`

  提供了一种便捷的方式来访问会话类并检索存储的值。详情请参阅 会话 页面。

timer([$name])
  参数:

    - $name (`string`) -- 基准点的名称。

  返回:

    Timer 实例

  返回类型:

    `CodeIgniterDebugTimer`

  一种便捷方法，可快速访问 Timer 类。你可以将基准点的名称作为唯一参数传入。 这将从此点开始计时，或者如果已存在同名计时器则停止计时。

  示例：

      <?php

      // Get an instance
      $timer = timer();

      // Set timer start and stop points
      timer('controller_loading');    // Will start the timer
      // ...
      timer('controller_loading');    // Will stop the running timer

view($name[, $data[, $options]])
  参数:

    - $name (`string`) -- 要加载的文件名

    - $data (`array`) -- 键/值对数组，使其在视图内可用。

    - $options (`array`) -- 将传递给渲染类的选项数组。

  返回:

    视图的输出。

  返回类型:

    `string`

  获取当前与 RendererInterface 兼容的类 （默认为 视图 类） 并告诉它渲染指定的视图。仅提供 一种便捷方法，可在控制器、 库和路由闭包中使用。

  目前，`$options` 数组中可使用以下选项：

  - `saveData` 指定数据将在同一请求内的多次 `view()` 调用间保持。如果你不希望保持，请指定 false。

  - `cache` 指定缓存视图的秒数。详情请参阅 缓存视图。

  - `debug` 可设置为 false 以禁用 调试工具栏 的调试代码添加。

  `$option` 数组主要用于促进与 Twig 等库的第三方集成。

  示例：

      <?php

      $data = ['user' => $user];

      echo view('user_profile', $data);

  详情请参阅 视图 和 视图渲染器 页面。

view_cell($library[, $params = null[, $ttl = 0[, $cacheName = null]]])
  参数:

    - $library (`string`)

    - $params (`null`)

    - $ttl (`integer`)

    - $cacheName (`string|null`)

  返回:

    视图单元用于在视图中插入由其他类管理的 HTML 片段。

  返回类型:

    `string`

  详情请参阅 视图单元 页面。

### 其他函数

app_timezone()
  返回:

    应用程序设置的显示日期的时区。

  返回类型:

    `string`

  返回应用程序设置的显示日期的时区。

csp_script_nonce()
  返回:

    script 标签的 CSP nonce 属性。

  返回类型:

    `string`

  返回 script 标签的 nonce 属性。例如：`nonce="Eskdikejidojdk978Ad8jf"`。 请参阅 内容安全策略。

csp_style_nonce()
  返回:

    style 标签的 CSP nonce 属性。

  返回类型:

    `string`

  返回 style 标签的 nonce 属性。例如：`nonce="Eskdikejidojdk978Ad8jf"`。 请参阅 内容安全策略。

csrf_token()
  返回:

    当前 CSRF 令牌的名称。

  返回类型:

    `string`

  返回当前 CSRF 令牌的名称。

csrf_header()
  返回:

    当前 CSRF 令牌的头部名称。

  返回类型:

    `string`

  当前 CSRF 令牌的头部名称。

csrf_hash()
  返回:

    当前 CSRF 哈希值。

  返回类型:

    `string`

  返回当前 CSRF 哈希值。

csrf_field()
  返回:

    包含所有必需 CSRF 信息的隐藏输入 HTML 字符串。

  返回类型:

    `string`

  返回一个已插入 CSRF 信息的隐藏输入:

      <input type="hidden" name="{csrf_token}" value="{csrf_hash}">

csrf_meta()
  返回:

    包含所有必需 CSRF 信息的 meta 标签 HTML 字符串。

  返回类型:

    `string`

  返回一个已插入 CSRF 信息的 meta 标签:

      <meta name="{csrf_header}" content="{csrf_hash}">

force_https($duration = 31536000[, $request = null[, $response = null]])
  参数:

    - $duration (`int`) -- 浏览器应将此资源的链接转换为 HTTPS 的秒数。

    - $request (`RequestInterface`) -- 当前 Request 对象的实例。

    - $response (`ResponseInterface`) -- 当前 Response 对象的实例。

  检查页面当前是否通过 HTTPS 访问。如果是，则 不会发生任何事情。如果不是，则将用户重定向回当前 URI， 但通过 HTTPS。将设置 HTTP Strict Transport Security (HTST) 头部，指示 现代浏览器在 `$duration` 期间自动将任何 HTTP 请求修改为 HTTPS 请求。

  备注

  此函数也在你将 `Config\App:$forceGlobalSecureRequests` 设置为 true 时使用。

function_usable($functionName)
  参数:

    - $functionName (`string`) -- 要检查的函数

  返回:

    如果函数存在且可以安全调用则返回 true，否则返回 false。

  返回类型:

    `bool`

is_cli()
  返回:

    如果脚本从命令行执行则返回 true，否则返回 false。

  返回类型:

    `bool`

is_really_writable($file)
  参数:

    - $file (`string`) -- 要检查的文件名。

  返回:

    如果可以写入文件则返回 true，否则返回 false。

  返回类型:

    `bool`

is_windows([$mock = null])
  参数:

    - $mock (`bool|null`) -- 如果给定且为布尔值，则将用作返回值。

  返回类型:

    `bool`

  检测平台是否在 Windows 上运行。

  备注

  提供给 $mock 的布尔值将在后续调用中保持。要重置此 模拟值，用户必须在函数调用中显式传递 `null`。这将 刷新函数以使用自动检测。

      <?php

      is_windows(true);

      // some code ...

      if (is_windows()) {
          // do something ..
      }

      is_windows(null); // reset

log_message($level, $message[, $context])
  参数:

    - $level (`string`) -- 严重级别

    - $message (`string`) -- 要记录的消息。

    - $context (`array`) -- 应在 $message 中替换的标签及其值的关联数组

  返回:

    void

  返回类型:

    `bool`

  备注

  从 v4.5.0 开始，返回值已修复为与 PSR Log 兼容。在以前的版本中，如果成功记录则返回 `true`， 如果记录时出现问题则返回 `false`。

  使用 app/Config/Logger.php 中定义的日志处理器记录消息。

  级别可以是以下值之一：`emergency`、`alert`、`critical`、`error`、`warning`、 `notice`、`info` 或 `debug`。

  上下文可用于替换消息字符串中的值。详情请参阅 日志记录信息 页面。

redirect(string $route)
  参数:

    - $route (`string`) -- 要重定向用户的路由名称或 Controller::method。

  返回类型:

    `RedirectResponse`

  返回 RedirectResponse 实例，允许你轻松创建重定向。 详情请参阅 重定向。

remove_invisible_characters($str[, $urlEncoded = true])
  参数:

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

    - $urlEncoded (`bool`) -- 是否同时移除 URL 编码的字符

  返回:

    清理后的字符串

  返回类型:

    `string`

  此函数防止在 ASCII 字符之间插入空字符， 如 Java\0script。

  示例：

      <?php

      remove_invisible_characters('Java\\0script');
      // Returns: 'Javascript'

request()

  Added in version 4.3.0.

  返回:

    共享的 Request 对象。

  返回类型:

    `IncomingRequest|CLIRequest`

  此函数是 `Services::request()` 和 `service('request')` 的包装器。

response()

  Added in version 4.3.0.

  返回:

    共享的 Response 对象。

  返回类型:

    `Response`

  此函数是 `Services::response()` 和 `service('response')` 的包装器。

route_to($method[, ...$params])
  参数:

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

    - ...$params (`int|string`) -- 要传递给路由的一个或多个参数。最后一个参数允许你设置区域设置。

  返回:

    路由路径（相对于 baseURL 的 URI 路径）

  返回类型:

    `string`

  备注

  此函数要求 controller/method 在 app/Config/Routes.php 中定义了路由。

  重要

  `route_to()` 返回的是 路由 路径，而不是你网站的完整 URI 路径。 如果你的 baseURL 包含子目录，则返回值与链接的 URI 不同。 在这种情况下，请改用 `url_to()`。 另请参阅 URL 结构。

  根据控制器::方法组合为你生成路由。如果提供参数，将考虑参数的影响。

      <?php

      // The route is defined as:
      $routes->get('users/(:num)/gallery/(:num)', 'Galleries::showUserGallery/$1/$2');

      ?>

      <?php

      // Generate the route with user ID 15, gallery 12:
      route_to('Galleries::showUserGallery', 15, 12);
      // Result: '/users/15/gallery/12'

  根据路由名称为你生成路由。

      <?php

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

      ?>

      <?php

      // Generate the route with user ID 15, gallery 12:
      route_to('user_gallery', 15, 12);
      // Result: '/users/15/gallery/12'

  从 v4.3.0 开始，当你在路由中使用 `{locale}` 时，可以选择将区域设置值作为最后一个参数指定。

      <?php

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

      ?>

      <?php

      // Generate the route with user ID 15, gallery 12 and locale en:
      route_to('user_gallery', 15, 12, 'en');
      // Result: '/en/users/15/gallery/12'

service($name[, ...$params])
  参数:

    - $name (`string`) -- 要加载的服务名称

    - $params (`mixed`) -- 要传递给服务方法的一个或多个参数。

  返回:

    指定的服务类实例。

  返回类型:

    `mixed`

  提供对系统中定义的任何 服务 的便捷访问。 这将始终返回类的共享实例，因此无论在单个请求期间调用多少次， 都只会创建一个类实例。

  示例：

      <?php

      $logger   = service('logger');
      $renderer = service('renderer', APPPATH . 'views/');

single_service($name[, ...$params])
  参数:

    - $name (`string`) -- 要加载的服务名称

    - $params (`mixed`) -- 要传递给服务方法的一个或多个参数。

  返回:

    指定的服务类实例。

  返回类型:

    `mixed`

  与上面描述的 service() 函数相同，只是对此函数的 所有调用都将返回类的新实例，而 service 每次都返回相同的 实例。

slash_item($item)
  参数:

    - $item (`string`) -- 配置项名称

  返回:

    配置项，如果项不存在则返回 null

  返回类型:

    `string|null`

  获取配置文件项并在末尾添加斜杠（如果不为空）

stringify_attributes($attributes[, $js])
  参数:

    - $attributes (`mixed`) -- 字符串、键值对数组或对象

    - $js (`boolean`) -- 如果值不需要引号（JavaScript 风格）则为 true

  返回:

    包含属性键/值对的字符串，以逗号分隔

  返回类型:

    `string`

  辅助函数，用于将字符串、数组或对象的属性转换为字符串。

## 全局常量

以下常量在应用程序中的任何位置始终可用。

### 核心常量

constant APPPATH

  app 目录的路径。

constant ROOTPATH

  项目根目录的路径。就在 `APPPATH` 上方。

constant SYSTEMPATH

  system 目录的路径。

constant FCPATH

  包含前端控制器的目录路径。

constant WRITEPATH

  writable 目录的路径。

### 时间常量

constant SECOND

  等于 1。

constant MINUTE

  等于 60。

constant HOUR

  等于 3600。

constant DAY

  等于 86400。

constant WEEK

  等于 604800。

constant MONTH

  等于 2592000。

constant YEAR

  等于 31536000。

constant DECADE

  等于 315360000。