OpenCart 4.x.x：通过事件覆盖common/header控制器失败求助

以下是针对问题的具体排查步骤，按优先级逐一验证：

1. 确认路由参数的原始值 #

在header_override方法中先打印原始路由，确认传入的$route是否与预期一致：

public function header_override(string &$route, array &$args): void {
    $this->log->write('header_override() original route: ' . $route);
    $override = ['common/header'];

    if (in_array($route, $override)) {
        $route = 'extension/oc_pif_theme_example/' . $route;
        $this->log->write('header_override() final route: ' . $route);
    }
}

查看系统日志（storage/logs目录下的日志文件），如果原始路由不是common/header，说明事件触发时的路由已经被修改，需要调整匹配规则。

2. 检查自定义控制器的命名空间与类结构 #

OpenCart 4严格遵循PSR-4自动加载规范，自定义控制器必须设置正确的命名空间。你的extension/oc_pif_theme_example/catalog/controller/common/header.php文件内容应符合以下格式：

namespace Extension\OcPifThemeExample\Catalog\Controller\Common;

class Header extends \Catalog\Controller\Common\Header {
    public function index() {
        $this->log->write('Custom header controller executed!');
        // 保留原逻辑或自定义修改
        parent::index();
    }
}

注意：

• 命名空间中的OcPifThemeExample是目录oc_pif_theme_example的驼峰式转换（首字母大写）
• 类名Header对应文件名header.php（规范上保持大小写一致）
• 必须继承原控制器类，确保基础逻辑正常运行

3. 验证事件Action对应的控制器路径 #

事件注册的action为extension/oc_pif_theme_example/startup/theme_example.header_override，对应的控制器文件路径应为：
extension/oc_pif_theme_example/catalog/controller/startup/theme_example.php
文件内的类结构需正确：

namespace Extension\OcPifThemeExample\Catalog\Controller\Startup;

class ThemeExample extends \Catalog\Controller\Startup\Startup {
    public function header_override(string &$route, array &$args): void {
        // 你的路由替换逻辑
    }
}

如果路径或命名空间错误，事件会触发但方法无法执行。

4. 检查事件排序优先级 #

若存在其他扩展注册了相同的catalog/controller/common/header/before事件，且排序值（sort_order）比你的小（优先级更高），可能会覆盖你的路由修改。解决方法：

• 进入后台System > Extensions > Events
• 找到你的事件，将Sort Order设为更小的数值（比如-1），确保它最先执行

5. 清除系统缓存 #

OpenCart 4的缓存会导致代码修改不生效，需执行以下操作：

• 后台进入System > Maintenance > Cache，点击Clear Cache
• 手动删除storage/cache目录下的所有文件
• 清除浏览器缓存后重新测试

内容的提问来源于stack exchange，提问作者Hantu