全局函数和常量

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

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

有关详细信息,请参阅 ConfigurationFactories

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

参数:
  • $name (string) – Cookie 名称

  • $value (string) – Cookie 值

  • $options (array) – Cookie 选项

返回类型:

Cookie

返回:

Cookie 实例

Throws:

CookieException

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

cookies([array $cookies = [][, bool $getGlobal = true]])
参数:
  • $cookies (array) – 如果 getGlobalfalse,则传入 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 是数组,则遍历它,转义每个键/值对的 ‘value’。

有效的 context 值: html, js, css, url, attr, raw

helper($filename)
参数:
  • $filename (string|array) – 要加载的辅助器文件名,或文件名数组

加载辅助器文件。

有关完整详细信息,请参阅 辅助器 页面。

lang($line[, $args[, $locale]])
参数:
  • $line (string) – 要检索的文本行

  • $args (array) – 要替换占位符的数据数组

  • $locale (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

提供了方便访问 session 类和检索存储值的方法。有关更多信息,请参阅 会话 页面。

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 以禁用为 Debug 工具栏 添加调试代码。

$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()
返回:

脚本标签的 CSP 随机数属性

返回类型:

string

返回脚本标签的随机数属性。例如:nonce="Eskdikejidojdk978Ad8jf"。请参阅 內容安全策略

csp_style_nonce()
返回:

样式标签的 CSP 随机数属性

返回类型:

string

返回样式标签的随机数属性。例如: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 严格传输安全(HTST)头,指示现代浏览器将任何 HTTP 请求自动修改为 HTTPS 请求,持续时间为 $duration

备注

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

function_usable($function_name)
参数:
  • $function_name (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 中替换的标签及其值的关联数组

返回:

如果记录成功则为 true,如果记录有问题则为 false

返回类型:

bool

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

级别可以是以下值之一:emergencyalertcriticalerrorwarningnoticeinfodebug

上下文可以用来在消息字符串中替换值。有关完整详细信息,请参阅 日志记录信息 页面。

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()

在 4.3.0 版本加入.

返回:

共享的 Request 对象

返回类型:

IncomingRequest|CLIRequest

此函数是 Services::request() 的包装器。

response()

在 4.3.0 版本加入.

返回:

共享的 Response 对象

返回类型:

Response

此函数是 Services::response() 的包装器。

route_to($method[, ...$params])
参数:
  • $method (string) – 路由名称或 Controller::method

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

返回:

路由路径(基于 baseURL 的 URI 相对路径)

返回类型:

string

备注

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

重要

route_to() 返回一个 路由 路径,而不是站点的完整 URI 路径。如果你的 baseURL 包含子文件夹,返回值与链接的 URI 并不相同。在这种情况下,请改用 url_to()。另请参阅 URL 结构

根据 controller::method 组合为你生成路由。将根据提供的参数生成路由。

<?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。