功能概述

StartMVC 内置了一批全局助手函数，用于简化配置读取、输入取值、缓存操作、数据库查询与输出转义等高频操作。它们均定义于 startmvc/function.php，在框架启动时自动加载，无需引入即可直接调用。

一览

env(key, default = null)

读取环境变量，并自动转换常见字面量。环境变量来源于项目根目录的 .env 文件或系统环境变量。

• 参数：$key 变量名，$default 不存在时的默认值
• 转换规则：true / (true) → true；false / (false) → false；null / (null) → null
• 使用：

// .env 中：APP_DEBUG=true
$debug = env('APP_DEBUG'); // true（布尔值，非字符串）
$host = env('DB_HOST', '127.0.0.1'); // 不存在时返回默认值

lang(key, default = '', module = null)

获取语言包中的翻译文本，语言包位于 app/{模块}/language/{语言}.php。

• 参数：$key 语言键名，$default 默认值，$module 指定模块（缺省取当前路由上下文的模块）
• 回退规则：语言包或键不存在时，依次回退「默认值 → 键名本身」，不抛异常
• 使用：

lang('welcome'); // 取当前模块语言包
lang('welcome', '欢迎'); // 未命中时返回默认值
lang('welcome', '欢迎', 'admin'); // 指定 admin 模块的语言包

input(key = null, default = null, type = '', filter = false) 新增

取输入值，合并 GET 与 POST（POST 优先），一步完成「取值 + 类型转换 + 默认兜底」。键名支持点路径读取嵌套数组。

• 参数：
  • $key 键名，支持点路径（如 user.name / list.0.id）；留空返回全部输入
  • $default 取值失败时的默认值
  • $type 类型转换：'' / string / int / float / bool / array
  • $filter 是否 HTML 转义，默认 false
• 使用：

input('id'); // 取 id（字符串）
input('id', 0, 'int'); // 转 int，缺省 0
input('user.name'); // 点路径：$_POST['user']['name']
input('list.0.id', 0, 'int'); // 点路径下钻 + 类型转换
input('agree', false, 'bool'); // 宽松布尔：'false'/'0'/'off' 均判为 false
input('title', '', 'string', true); // 取值并转义
input(); // 返回全部输入（GET + POST 合并）

e(value, doubleEncode = true) 新增

HTML 转义输出助手，用于输出侧防止 XSS。与输入端「不转义」策略配套：输入层保持原始数据，输出到 HTML 时统一在此转义，避免双重转义与数据污染。

• 参数：$value 待转义的值（传入数组将递归转义），$doubleEncode 是否对已是 HTML 实体的内容再次转义，默认 true
• 使用：

// 模板中输出用户输入，防止 XSS
echo e($userInput); // <script> → &lt;script&gt;

// 列表递归转义，便于直接渲染
foreach (e($list) as $item) { ... }

// 值已是 HTML 实体时，避免二次转义
echo e('&amp;', false); // &（而非 &amp;amp;）

// null 返回空字符串，避免输出告警
echo e(null); // ''

dump(var, label = null, echo = true)

格式化输出变量内容，自动适配 CLI 与 Web 环境。

• 参数：$var 要输出的变量，$label 标签，$echo 是否直接输出（为 false 时仅返回字符串）
• 使用：

dump($data, '调试信息');

// 仅返回字符串，不直接输出
$str = dump($data, '调试信息', false);

config(key = null, default = null)

读取或设置配置项。配置项支持以 . 分隔的层级键名。

• 参数：$key 配置键名（传数组则为批量设置），$default 读取时的默认值
• 使用：

config(); // 获取全部配置
config('debug'); // 读取单个配置
config('db.host'); // 读取层级配置
config('db.host', 'localhost'); // 读取，不存在时返回默认值
config(['debug' => true]); // 批量设置配置

// 加载指定配置文件（键名前加 @）
config('@route');

cache(name, value = null, ttl = null, driver = null)

缓存数据的存取与删除。

• 参数：$name 缓存名称，$value 缓存值（null 表示获取、false 表示删除），$ttl 过期秒数（null 时使用驱动配置的默认值），$driver 驱动类型
• 使用：

cache('user_1'); // 获取缓存，未命中返回 null
cache('user_1', $userData); // 写入缓存（使用驱动默认过期时间）
cache('user_1', $userData, 7200); // 写入缓存，2 小时后过期
cache('user_1', false); // 删除缓存
cache('user_1', $userData, 7200, 'redis'); // 指定驱动

url(url)

生成 URL 地址，自动处理 URL 重写与后缀。

• 参数：$url 路径
• 使用：

url('home/index'); // 开启重写：/home/index.html
 // 未开启： /index.php/home/index.html

db(table = '', config = [])

数据库操作助手，支持链式调用与自定义配置。

• 参数：$table 表名，$config 数据库配置（可选）
• 使用：

// 使用默认配置
db('user')->where('id', 1)->get();

// 链式指定表名
db()->table('user')->where('status', 1)->select('id,name')->get();

// 使用自定义配置
db('user', $config)->where('uid', 1)->get();

// 写入与更新
db('user')->insert(['name' => 'test', 'email' => 'test@example.com']);
db('user')->where('id', 1)->update(['name' => 'updated']);
db('user')->where('id', 1)->delete();

get_ip()

获取客户端真实 IP 地址，支持代理环境。

• 参数：无
• 使用：

$ip = get_ip();