内置函数

ThinkAdmin 的内置函数主要定义在 think-library/src/common.php，Controller 快捷方法定义在 think-library/src/Controller.php。这些函数可以在控制器、模型、服务、视图模板中直接使用。

本文按当前实现整理签名和行为，示例只展示常用写法。

开发调试

p()

将 var_dump() 输出写入文件，便于调试。

p($data, bool $new = false, ?string $file = null)

参数说明：

  • $data：任意需要输出的数据。
  • $new：是否覆盖写入，false 表示追加。
  • $file：为 null 时写入 runtime/YYYYMMDD.log；只传文件名时写入 runtime/{文件名}.log；传入带目录分隔符的路径时按原路径写入。

示例：

p($data);
p($data, true, 'debug');
p($data, false, syspath('runtime/api.log'));

注意：如果传入 api.log 这类纯文件名，实际文件会是 runtime/api.log.log。需要精确文件名时传入完整路径。

m()

动态创建模型对象。

m(string $name, array $data = [], string $conn = ''): \think\Model

如果 $name 是已存在的完整模型类名，会实例化该模型；否则通过 VirtualModel::mk() 创建动态模型。

$user = m('SystemUser');
$user = m('SystemUser', ['username' => 'admin']);
$user = m('SystemUser', [], 'mysql');

权限与安全

auth()

检查当前用户是否拥有指定节点权限。

auth(?string $node): bool

auth() 会调用 AdminService::check()，支持相对节点补全：

auth('remove');             // 当前控制器 remove 方法
auth('user/remove');        // 当前应用 user/remove
auth('admin/user/remove');  // 完整节点

模板中常用于按钮显隐：

<!--{if auth("remove")}-->
<button data-action="{:url('remove')}" data-value="id#{{d.id}}">删除</button>
<!--{/if}-->

权限细节见 权限管理。

systoken()

生成 CSRF Token 表单参数。

systoken(): string

xss_safe()

过滤文本中的 <script> 块，并把 onxxx= 事件属性中的 on 替换为非 ASCII 相似字符。

xss_safe(string $text): string

该函数只做轻量过滤，不应替代业务侧的白名单校验、富文本净化或输出转义。

URL 生成

sysuri()

生成系统最短可访问 URL。

sysuri(string $url = '', array $vars = [], $suffix = true, $domain = false): string

实现会按当前应用、控制器、方法补全短路径，并尝试省略默认应用、默认控制器、默认方法。

sysuri('admin/user/index');
sysuri('admin/user/edit', ['id' => 1]);
sysuri('admin/user/index', [], true, true);

当前实现中，当 $url 以 http://、https://、@ 或 |/ 开头时，会直接交给 ThinkPHP 路由生成器处理。普通 /admin 或反斜杠开头的字符串仍会进入短路径补全逻辑。

admuri()

生成后台 Hash URL。

admuri(string $url = '', array $vars = [], $suffix = true, $domain = false): string

实际实现等价于：

sysuri('admin/index/index', [], $suffix, $domain) . '#' . url($url, $vars)->build();

示例：

admuri('admin/user/index');
admuri('admin/user/edit', ['id' => 1]);

Helper 全局入口

_vali()

快捷读取输入并按规则验证。

_vali(array $rules, $type = '', ?callable $callable = null): array

$type 为字符串时会调用当前请求对象对应输入方法，空字符串按 param() 读取，也可传入 post、get 等；传入数组时直接作为待验证数据。规则写法与控制器 $this->_vali() 一致。

当前 ValidateHelper::init() 支持三类规则：

  • 数字键字段：'name' 读取同名输入，'username#name' 表示输出字段为 username、输入字段为 name。
  • 固定值规则：'status.value' => 1 直接写入固定值。
  • 默认值规则：'status.default' => 1 在输入缺失时写入默认值。

普通校验规则沿用 ThinkPHP Validate，例如：

$data = _vali([
    'name.require'      => '名称不能为空',
    'phone.mobile'      => '手机号格式错误',
    'status.default'    => 1,
    'source.value'      => 'admin',
    'username#nickname',
], 'post');

验证失败时，如果传入 $callable 会调用它并返回其结果；否则会通过当前控制器 error() 输出 JSON 响应。

_query()

创建查询助手实例。

_query($dbQuery, $input = null): \think\admin\helper\QueryHelper

$dbQuery 可以是模型、查询对象或表/模型名字符串；$input 为 null 时使用请求参数，也可传入数组或指定输入来源。该函数与控制器 $this->_query() 调用同一个 QueryHelper::init() 实现。

数据转换

encode() / decode()

按 ThinkAdmin 自定义规则编码或解码 UTF-8 字符串。

encode(string $content): string
decode(string $content): string

这不是加密算法，只适合做可逆文本编码。

str2arr()

将分隔字符串转换为数组，会自动去除首尾分隔符、空值和空白。

str2arr(string $text, string $separ = ',', ?array $allow = null): array
str2arr(',10001,10002,'); // ['10001', '10002']
str2arr('a|b|c', '|', ['a', 'c']); // ['a', 'c']

arr2str()

将数组转换为首尾都带分隔符的字符串，会过滤空字符串；传入 $allow 时只保留白名单值。

arr2str(array $data, string $separ = ',', ?array $allow = null): string
arr2str(['10001', '10002']); // ,10001,10002,
arr2str(['a', 'b', 'c'], '|', ['a', 'c']); // |a|c|

enbase64url() / debase64url()

URL 安全 Base64 编解码。

enbase64url(string $string): string
debase64url(string $string): string

运行与配置

isDebug() / isOnline()

判断当前运行模式。

isDebug(): bool
isOnline(): bool

当前实现中，RuntimeService::get('mode') !== 'product' 即为调试模式；mode === 'product' 即为生产模式。

sysconf()

读取或写入系统参数，对应 SystemService::get() 与 SystemService::set()。

sysconf(string $name = '', $value = null)

行为说明：

  • sysconf('base.site_name')：读取配置，默认会做 htmlspecialchars()。
  • sysconf('base.site_name|raw')：读取原始配置值。
  • sysconf()：读取全部配置数组。
  • sysconf('base.site_name', 'ThinkAdmin')：写入配置。

注意：第二个参数不是读取默认值。只要传入第二个参数，当前实现就会写入配置。

sysdata()

读取或写入 JSON 数据，对应 system_data 表。

sysdata(string $name, $value = null)

行为说明：

  • 只传 $name 时读取数据，未找到返回 []。
  • 传入 $value 时写入数据，返回保存结果。
  • 写入时当前实现会把值包在数组中 JSON 编码，读取时再取第一个元素。
$profile = sysdata('UserProfile_10000');
sysdata('UserProfile_10000', ['theme' => 'default']);

sysvar()

读写单次请求内存缓存。

sysvar(?string $name = null, $value = null)

行为说明：

  • sysvar()：读取全部内存缓存。
  • sysvar('name')：读取指定值。
  • sysvar('name', $value)：写入指定值。
  • sysvar('', '')：清空全部内存缓存。

syspath()

拼接项目内绝对路径。

syspath(string $name = '', ?string $root = null): string

默认根路径为应用根目录，并会把 /、\ 转成当前系统目录分隔符。

syspath('runtime/cache');
syspath('public/upload/image.png');

日志与任务

sysoplog()

写入系统操作日志。

sysoplog(string $action, string $content): bool

日志会包含当前节点、操作名、内容、IP、用户名和时间。

sysqueue()

注册异步任务并返回任务编号。

sysqueue(string $title, string $command, int $later = 0, array $data = [], int $rscript = 1, int $loops = 0): string

参数说明：

  • $title：任务名称。
  • $command：命令内容，例如 xadmin:queue clean 或业务命令。
  • $later：延迟执行秒数。
  • $data：任务附加数据，写入 system_queue.exec_data。
  • $rscript：是否允许重复脚本，0 表示单例，1 表示允许多例。
  • $loops：循环等待时间，单位秒；0 表示不循环，大于 0 表示按该秒数间隔重新调度。
$code = sysqueue('清理队列', 'xadmin:queue clean', 0, [], 1, 3600);

网络请求与保存

http_get() / http_post()

封装 HttpExtend 的 GET 和 POST 请求。

http_get(string $url, $query = [], array $options = [])
http_post(string $url, $data, array $options = [])

返回值为 bool|string，取决于底层请求结果。

data_save()

调用 SystemService::save() 做新增或更新。

data_save($dbQuery, array $data, string $key = 'id', $where = [])

行为说明：

  • $dbQuery 可以是模型、查询对象或表/模型名字符串。
  • 会按 $key 和 $where 查找已有记录。
  • 保存成功后，$data 会被更新为模型数组。
  • 返回主键值、true 或 false。

文件与格式化

down_file()

下载远程文件到当前存储并返回 URL。

down_file(string $source, bool $force = false, int $expire = 0): string

如果下载失败或存储未返回 URL，会返回原始 $source。

trace_file()

把异常信息写入 runtime/trace。

trace_file(\Throwable $exception): bool

format_bytes()

格式化字节数。

format_bytes($size): string

非数字输入会原样转为字符串返回；数字按 1024 进位换算，当前实现最多换算到 TB。

format_datetime()

格式化时间。

format_datetime($datetime, string $format = 'Y年m月d日 H:i:s'): string

空值返回 -；数字按时间戳处理；字符串会尝试 strtotime()；无法解析则返回原字符串。

Controller 基类方法

Controller 基类提供响应、视图、Helper 和任务快捷方法。以下签名来自 think\admin\Controller。

响应方法

$this->success($info, $data = '{-null-}', $code = 1): void
$this->error($info, $data = '{-null-}', $code = 0): void
$this->redirect(string $url, int $code = 302): void

success() 与 error() 都会抛出 JSON 响应异常，结构为：

{"code": 1, "info": "操作成功", "data": {}}

当 $data 使用默认 '{-null-}' 时会输出空对象。

视图方法

$this->fetch(string $tpl = '', array $vars = [], ?string $node = null): void
$this->assign($name, $value = ''): \think\admin\Controller

fetch() 会把控制器对象属性合并到模板变量；启用 CSRF 时通过 TokenHelper::fetch() 渲染，否则直接返回视图响应。

Helper 快捷方法

$this->_query($dbQuery, $input = null): \think\admin\helper\QueryHelper
$this->_page($dbQuery, $page = true, bool $display = true, $total = false, int $limit = 0, string $template = ''): array
$this->_form($dbQuery, string $template = '', string $field = '', $where = [], array $data = [])
$this->_vali(array $rules, $type = '', ?callable $callable = null): array
$this->_save($dbQuery, array $data = [], string $field = '', $where = []): bool
$this->_delete($dbQuery, string $field = '', $where = []): bool

这些方法只是对应 Helper 的快捷入口。其中 _query() 与 _vali() 同时也有全局函数入口；控制器方法与全局函数调用同一套 Helper 实现。详细用法见：

当前 Helper init() 签名对应关系如下：

QueryHelper::init($dbQuery, $input = null, ?callable $callable = null): QueryHelper
PageHelper::init($dbQuery, $page = true, bool $display = true, $total = false, int $limit = 0, string $template = ''): array
FormHelper::init($dbQuery, string $template = '', string $field = '', $where = [], array $edata = [])
SaveHelper::init($dbQuery, array $edata = [], string $field = '', $where = [])
DeleteHelper::init($dbQuery, string $field = '', $where = [])
ValidateHelper::init(array $rules, $input = '', ?callable $callable = null)
TokenHelper::init(bool $return = false)

$dbQuery 可以是模型类、模型实例、查询对象、表名字符串或子查询字符串。内部统一通过 Helper::buildQuery() 转成 ThinkORM 查询对象，并触发 think_before_event。

模型静态快捷方法

继承 think\admin\Model 的模型通过静态魔术方法接入同一套 Helper：

SystemUser::mQuery($input = null, callable $callable = null): \think\admin\helper\QueryHelper
SystemUser::mForm(string $template = '', string $field = '', $where = [], array $data = [])
SystemUser::mSave(array $data = [], string $field = '', $where = []): bool
SystemUser::mDelete(string $field = '', $where = []): bool
SystemUser::mUpdate(array $data = [], string $field = '', $where = [])
SystemUser::mk($data = [])
SystemUser::mq(array $data = [])

这些静态方法不是在模型中显式声明的方法，而是由 Model::__callStatic() 转发给 QueryHelper::make()。mk() 创建模型实例，mq() 创建查询对象。

表单令牌

$this->_applyFormToken(bool $return = false): bool
systoken(): string

_applyFormToken() 会调用 TokenHelper 检查表单令牌，通常由 Helper 或页面逻辑按需调用。非 POST 请求会开启控制器 csrf_state 并返回 true；POST 请求会优先读取表单 _token_，没有时读取请求头 User-Form-Token。验证失败且 $return=true 时返回 false，否则直接输出错误响应。

systoken() 调用 TokenHelper::token() 生成 _token_；当控制器 csrf_state=true 后，fetch() 会通过 TokenHelper::fetch() 在每个 </form> 前自动注入隐藏字段。

队列任务

$this->_queue(string $title, string $command, int $later = 0, array $data = [], int $rscript = 0, int $loops = 0): void

_queue() 会注册任务并直接返回 JSON 响应：

  • 新建成功时返回 code=1，data 为任务编号。
  • 单例任务已存在时返回 code=1，data 为已存在任务编号。
  • 其他异常返回 code=0。

注意：_queue() 默认 $rscript=0，而全局函数 sysqueue() 默认 $rscript=1。

常用服务

AdminService

当前常用方法：

AdminService::isLogin(): bool
AdminService::isSuper(): bool
AdminService::getSuperName(): string
AdminService::getUserId(): int
AdminService::getUserName(): string
AdminService::getUserData(?string $field = null, $default = null)
AdminService::setUserData(array $data, bool $replace = false): bool
AdminService::check(?string $node = ''): bool
AdminService::apply(bool $force = false): array
AdminService::clear(): bool

当前实现没有 AdminService::getUserInfo()。如需当前登录用户基础信息，可读取 Session 或使用上面的 getUserId()、getUserName()、getUserData()。

ModuleService

ModuleService::getVersion(): string
ModuleService::getRunVar(string $field): string
ModuleService::getPhpExec(): string
ModuleService::getModules(array $data = []): array
ModuleService::getLibrarys(?string $package = null, bool $force = false)

getLibrarys() 读取 vendor/versions.php，传包名时返回该包信息，不传时返回全部包信息。

RuntimeService

RuntimeService::get(?string $name = null, array $default = [])
RuntimeService::set(?string $mode = null, ?array $appmap = [], ?array $domain = []): bool
RuntimeService::clear(bool $force = true): bool
RuntimeService::isDebug(): bool
RuntimeService::isOnline(): bool

RuntimeService::set() 的第二个参数是应用映射 $appmap，第三个参数是域名绑定 $domain，不是后台入口路径配置。

示例：

RuntimeService::set('product');
RuntimeService::set(null, ['admin' => 'admin'], ['admin.example.com' => 'admin']);

SystemService

常用方法：

SystemService::uri(string $path = '', ?string $type = '__ROOT__', $default = '')
SystemService::uris(string $path = ''): array
SystemService::get(string $name = '', string $default = '')
SystemService::set(string $name, $value = '')
SystemService::save($query, array &$data, string $key = 'id', $map = [])
SystemService::update($query, array $data, string $key = 'id', $map = [])
SystemService::setData(string $name, $value): bool
SystemService::getData(string $name, $default = [])
SystemService::setOplog(string $action, string $content): bool
SystemService::putDebug($data, bool $new = false, ?string $file = null)
SystemService::setFavicon(?string $icon = null): bool
最近更新:
Contributors: 邹景立, Anyon