TP5项目应自封装Utils工具类而非依赖单字母函数：按Str/Arr/Date/File等职责拆分，使用static方法+PSR-4自动加载，严格处理类型校验、UTF-8编码、引用拷贝三坑。
TP5 本身不强制提供“工具函数库”，但项目中高频需要字符串处理、数组转换、时间格式化等操作，直接写原生 PHP 函数容易散落、难复用、缺校验。最稳妥的做法是：自己封装一个 Utils 类（或多个小类），放在 app/common/utils/ 下，配合 PSR-4 自动加载，按需调用。
为什么不用单字母函数或助手函数替代？
TP5 的 input()、dump()、url() 等是框架级响应/输入/路由辅助函数，不解决通用数据加工问题。比如你没法用 input() 把二维数组按某个字段去重，也不能靠 url() 生成带签名的下载链接。它们职责不同，不能混用。
常见误判是把 Arr::only() 当万能数组工具——它只做键筛选，不处理值映射、递归扁平、条件分组等真实业务场景。
如何组织 Utils 类结构（推荐分拆）
别堆一个大而全的 Utils.php。按能力边界拆成独立类，利于测试和按需加载：
-
Str.php：处理大小写、截取、模糊匹配、UUID、随机字符串、正则提取等 -
Arr.php：基于 PHP 原生函数封装，如array_column()+array_unique()组合去重、array_filter()带默认值兜底、二维数组按字段排序（usort()封装） -
Date.php：时间戳转相对时间（“2小时前”）、格式化为 ISO8601、计算两个日期差天数、生成本周起止时间等 -
File.php：安全拼接路径（realpath()+basename()防遍历）、检查文件 MIME 类型（非仅后缀）、生成唯一上传文件名
每个类用 static 方法，不依赖实例状态，调用干净：Str::snake('UserLogin')、Arr::groupBy($list, 'status')。
封装时必须处理的三个坑
很多自封工具函数上线后出问题，根源就在这三处没兜住：
-
类型校验缺失：比如
Arr::first()传了null或字符串，不提前is_array()判空就直接reset()，PHP 会报 Warning；应在入口加if (!is_array($arr) || empty($arr)) { return $default; } -
编码不统一：中文字符串用
substr()截取会乱码，必须用mb_substr()并显式传'UTF-8'；所有涉及字符串长度、位置的操作都要走mb_*系列 -
引用与拷贝混淆：对传入数组做
array_walk_recursive()修改值时，若未用&$item引用，原数组不会变；但若函数内部unset($arr[0])又返回$arr，外部变量其实已受影响——这种副作用要文档写清，或统一返回新数组避免歧义
如何接入 Composer 自动加载
在 composer.json 的 autoload 段加上：
"autoload": {
"psr-4": {
"app\common\utils\": "app/common/utils/"
}
}
然后运行 composer dump-autoload。之后就能直接 use appcommonutilsStr; 或 use appcommonutilsArr;。
注意路径斜杠方向：Windows 下写 appcommonutils（反斜杠），Linux/macOS 也兼容；别写成 app/common/utils/（正斜杠），PSR-4 规范要求命名空间分隔符是反斜杠。
复杂点在于跨项目复用——如果多个 TP5 项目都要用同一套工具，就得抽成独立 Composer 包（如 easy-utils），用 composer require your-vendor/easy-utils 安装。这时候类路径、版本约束、测试覆盖就都得跟上，不是加个文件夹那么简单。
