助手函数

框架在 src/helper.php 中定义了 17 个全局助手函数，随 composer autoload 自动加载，可在项目任意位置直接调用，无需 use 导入。它们是对容器、配置、路径等核心能力的快捷封装，用于减少样板代码。本篇为参考手册，按「路径类 / 容器类 / 配置环境类 / 调试类」四组逐一列出签名与用途。

所有助手函数均以 function_exists 包裹定义，如需覆盖某个函数（如 dump），可在更早加载的自定义文件中定义同名函数。

路径类

路径类函数返回项目各目录的绝对路径，结尾均不带目录分隔符：

函数	签名	说明
`getRootPath`	`getRootPath(): string`	项目根目录
`getVendorPath`	`getVendorPath(): string`	Composer 依赖目录（`{root}/vendor`）
`getConfigPath`	`getConfigPath(): string`	配置目录（`{root}/config`）
`getAppPath`	`getAppPath(): string`	业务代码目录（`{root}/app`）
`getEnvPath`	`getEnvPath(): string`	`.env` 环境变量文件的绝对路径

php

$configFile = getRootPath() . '/config/database.php';
$customEnv  = getEnvPath() . '.testing'; // 基于默认 .env 路径推导

目录结构与各路径的实际含义见项目结构。

容器类

容器类函数是容器（App）实例与解析能力的快捷入口，底层机制见容器。

app()

php

function app(?string $name = null): mixed

参数	类型	默认值	说明
`$name`	string\|null	`null`	服务标识或接口名，`null` 时返回容器实例本身

php

$app = app();                 // 容器实例，可访问 $app->config、$app->log 等魔术属性
$router = app('router');      // 解析容器绑定

服务不存在时抛出 NotFoundException。

make()

php

function make(string $abstract, array $params = []): mixed

参数	类型	默认值	说明
`$abstract`	string	无	类名或容器标识
`$params`	array	`[]`	构造函数参数

创建实例并缓存为单例（协程环境下单例按请求根协程隔离）；类定义 ALLOW_NEW_INSTANCE = true 常量时每次新建：

php

$service = make(UserService::class, ['prefix' => 'vip']);

bind()

php

function bind(string $abstract, object|string $concrete): void

参数	类型	默认值	说明
`$abstract`	string	无	接口名或服务标识
`$concrete`	object\|string	无	实现实例或实现类名

php

bind(PayInterface::class, AliPayService::class); // 接口绑定实现类
$pay = app(PayInterface::class); // 解析时再实例化

模块化的绑定组织方式见服务提供者。

invoke()

php

function invoke(array|callable|string $callable, array $params = []): mixed

参数	类型	默认值	说明
`$callable`	array\|callable\|string	无	函数、方法或 `[类, 方法]` 数组
`$params`	array	`[]`	额外传入的参数

通过容器依赖注入调用函数或方法：未显式传入的参数会按类型自动从容器解析，路由 handler 与事件回调都经由它执行：

php

// 按类型注入 $request、$id
invoke([UserController::class, 'show'], ['id' => 1]);

cache()

php

function cache(?string $key = null, mixed $value = null): mixed

参数	类型	默认值	说明
`$key`	string\|null	`null`	缓存键名，`null` 时返回缓存管理器实例
`$value`	mixed	`null`	键不存在时返回的默认值

php

$value = cache('user:1');           // 读取缓存，未命中返回 null
$cache = cache();                   // CacheManager 实例，可调用 set/delete/tag 等
$cache->set('user:1', $data, 3600); // 写入缓存

缓存读写与标签、锁等完整能力见缓存。

配置环境类

config()

php

function config(?string $name = null, mixed $default = null): mixed

参数	类型	默认值	说明
`$name`	string\|null	`null`	配置键名，支持点号分隔的多级键名
`$default`	mixed	`null`	键不存在时的默认值

php

config('database.default');              // 多级键名
config('server.servers.http.port', 9501); // 带默认值

配置文件组织与运行时修改的注意事项（Config::set() 仅进程内有效）见配置文件。

env()

php

function env(?string $key = null, mixed $default = null): mixed

参数	类型	默认值	说明
`$key`	string\|null	`null`	环境变量名（支持二级点号分割）
`$default`	mixed	`null`	未定义时的默认值

php

$host = env('REDIS_HOST', '127.0.0.1');
$debug = env('app_debug', false); // true/false/on/off 会自动转为布尔值

.env 文件格式与加载规则见环境变量。

getVersion()

php

function getVersion(): string

返回框架当前版本号（语义化版本字符串，如 1.5.4），命令行工具也用它作为应用版本：

php

echo getVersion(); // 1.5.4

调试类

isDebug() 与 app_debug()

php

function isDebug(): bool
function app_debug(): bool

两个函数行为完全等价（app_debug() 为兼容别名），返回当前是否处于调试模式。调试模式由 config/app.php 的 debug 配置（默认取 env('app_debug')）决定，运行时通过 Swoole 共享内存表同步到所有 Worker 进程：

php

if (isDebug()) {
  // 仅调试环境执行：打印详细日志、暴露调试接口等
}

dump()

php

function dump(mixed $data, string $title = 'variable output', string $color = Output::COLORS['GREEN'], int $backtrace = 1): void

参数	类型	默认值	说明
`$data`	mixed	无	要打印的变量内容
`$title`	string	`'variable output'`	输出标题
`$color`	string	`Output::COLORS['GREEN']`（绿色）	输出颜色
`$backtrace`	int	`1`	是否输出调用源：`1` 输出，`0` 不输出

格式化打印变量（支持数组、对象等复杂结构）到控制台，替代裸 var_dump：

php

dump($request->params(), title: '请求参数');

echo_log()

php

function echo_log(string|int $message, string $label = 'SUCCESS', ?string $color = null, int $backtrace = 1): void

参数	类型	默认值	说明
`$message`	string\|int	无	要输出的内容
`$label`	string	`'SUCCESS'`	输出标签（如 `SUCCESS`、`WARNING`、`ERROR`）
`$color`	string\|null	`null`	自定义颜色，`null` 时使用标签映射的默认颜色
`$backtrace`	int	`1`	是否输出调用源：`1` 输出，`0` 不输出

输出一条带标签的控制台日志，框架内部的服务启动、关闭提示即基于它实现：

php

echo_log('定时任务已启动', 'SUCCESS');

dump() 与 echo_log() 直接输出到当前进程的控制台（守护进程模式下写入 OPTION_LOG_FILE 指定的文件），不经过日志系统，没有级别过滤与文件归档。需要持久化、可检索的日志请使用 Log 门面，见日志。

使用注意

常驻内存：助手函数大多是容器与配置的薄封装，本身无状态，但通过它们写入的单例与配置修改受协程与常驻内存规则约束；
性能：config() / env() 每次调用都会查询配置对象，循环体内的高频调用建议先取值到局部变量；
生产环境：dump() 调试输出请勿遗留到生产代码，可通过 isDebug() 包裹或在发布前清理。