CI4自定义helper必须是纯函数集合，禁止命名空间和类；正确写法为在app/Helpers/下创建小写下划线命名的PHP文件，直接定义带function_exists检查的全局函数，加载方式为Autoload.php配置$helpers数组或调用helper('name')。
CI4 自定义 helper 必须是纯函数，不能有命名空间或 class
CI4 的 helper 不是类、不是服务、不走 DI 容器，它就是一堆全局函数的集合。一旦你在 app/Helpers/my_helper.php 里写了 namespace App\Helpers; 或 class MyHelper，运行时就会报 Call to undefined function App\Controllers\your_function_name()——注意错误里带 App\Controllers\ 前缀，说明 PHP 正在当前控制器命名空间里找函数，根本没加载成功。
正确写法只有一条：文件开头不加任何 namespace，不写 class，直接定义函数：
if (! function_exists('format_price')) {
function format_price(float $amount): string
{
return '$' . number_format($amount, 2);
}
}
-
if (! function_exists(...))是必须的，防止重复加载导致 “Cannot redeclare” 错误 - 文件名用小写+下划线，比如
price_helper.php，加载时只写'price'（不含.php） - 函数名必须全局唯一，避免和系统 helper（如
url()、form_open()）冲突
怎么加载自定义 helper：三种方式选一个就行
CI4 加载 helper 不依赖自动加载机制，也不走 Composer，靠的是手动注册或配置。别在控制器里写 $this->load->helper() —— CI4 已经没有这个语法了。
- 全局加载（推荐）：在
app/Config/Autoload.php的$psr4下方找到$helpers数组，加上你的 helper 名：$helpers = ['price', 'text']; - 按需加载（控制器内）：用
helper('price');（注意不是$this->load->...） - 按需加载（视图内）：同样用
helper('price');，但建议尽量提前在控制器或 Autoload 中加载，避免视图里逻辑分散
如果加载后仍提示函数未定义，检查是否拼错文件名（price_helper.php ≠ Price_helper.php），或是否漏掉 app/Helpers/ 目录层级。
helper 里不能用 $this，要用 Services::xxx() 获取服务
helper 是无状态函数，没有上下文对象。你不能在 format_price() 里写 $this->request 或 $this->session —— 这会直接 fatal error。
需要访问框架服务时，必须显式调用 Services 类：
if (! function_exists('get_user_name')) {
function get_user_name(?int $id = null): string
{
$userModel = \CodeIgniter\Services::model('UserModel');
$user = $userModel->find($id ?? service('session')->get('user_id'));
return $user ? $user->name : 'Guest';
}
}
- 所有
Services::xxx()调用都得带完整命名空间前缀\CodeIgniter\Services::，否则找不到类 - 不要试图在 helper 里传
$this或控制器实例——这破坏 helper 的无状态设计，也容易引发循环依赖 - 如果逻辑重度依赖服务（比如要查数据库 + 发邮件 + 写日志），那它就不该是 helper，应该抽成
Service类
常见坑：函数名冲突、加载时机、大小写敏感
CI4 对 helper 的加载非常“朴素”，几乎不校验，出错时也不会友好提示，只能靠排查。
- 函数名被覆盖：如果你写了
function url()，会直接覆盖 CI4 自带的url()，且没有任何警告——结果是所有路由生成失效 - 加载顺序问题：多个 helper 里定义同名函数，后加载的会覆盖先加载的；
Autoload.php里的顺序就是加载顺序 - 文件名大小写：Linux 服务器上
Price_helper.php和price_helper.php是两个文件，但 CI4 只认小写文件名，加载'price'时只会找price_helper.php - 忘记加
if (! function_exists())：在 CLI 环境或多次请求中，helper 可能被重复包含，导致致命错误
最隐蔽的问题是：helper 文件里用了 PHP 8+ 特性（如联合类型、属性 promotion），但项目实际运行在 PHP 7.4 上——错误不会指向 helper，而是报 “unexpected token”，得逐行注释排查。
