LimeSurvey 6.5.9插件添加顶部菜单条目失败问题排查

我用PHP 8.1开发LimeSurvey 6.5.9插件，目标是在顶部导航栏的Help与Configuration旁添加菜单条目。插件能正常安装激活，但菜单条目始终不显示，相关代码如下：

Testplugin.php #

<?php

class Testplugin extends PluginBase
{
    protected $storage = 'DbStorage';
    static protected $description = "Test Plugin";
    static protected $name = "Testplugin";

    public function init()
    {
        $this->subscribe('onPluginRegistration');
    }

    public function onPluginRegistration()
    {
        $pluginName = $this->get('pluginName');
        $existingMenu = Surveymenu::model()->findByAttributes(['name' => 'testplugin_menu']);
        if (!$existingMenu) {
            $menuArray = [
                "parent_id" => 1,
                "name" => "testplugin_menu",
                "title" => "Manage Companies",
                "position" => "side",
                "description" => "Manage companies"
            ];
            $newMenuId = Surveymenu::staticAddMenu($menuArray);

            $menuEntryArray = [
                "name" => "manage_companies",
                "title" => "Manage Companies",
                "menu_title" => "Manage Companies",
                "menu_description" => "Manage companies",
                "menu_icon" => "building",
                "menu_icon_type" => "fontawesome",
                "menu_link" => "admin/pluginhelper/sa/index/plugin/Testplugin",
                "addSurveyId" => false,
                "addQuestionGroupId" => false,
                "addQuestionId" => false,
                "linkExternal" => false,
                "hideOnSurveyState" => null,
                "manualParams" => ""
            ];
            SurveymenuEntries::staticAddMenuEntry($newMenuId, $menuEntryArray);
        }
    }
}

config.xml #

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <metadata>
        <name>Testplugin</name>
        <type>plugin</type>
        <creationDate>2024-05-01</creationDate>
        <lastUpdate>2024-05-28</lastUpdate>
        <author>Peter Parker</author>
        <authorUrl>https://www.example.com</authorUrl>
        <version>1.0.0</version>
        <license>Empty</license>
        <description><![CDATA[Testplugin]]></description>
    </metadata>

    <compatibility>
        <version>6.5.9</version>
    </compatibility>

    <settings>
        <setting>
            <name>placeholder</name>
        </setting>
    </settings>
</config>

问题排查与修复方案 #

1. 事件订阅选错了 #

onPluginRegistration只在插件首次注册时触发一次，后续菜单可能被系统缓存或覆盖。应该改用onAdminMenuRender事件，这个事件在后台菜单渲染时实时触发，更适合动态添加顶部菜单。

2. 菜单位置参数错误 #

你设置的position是side，这是侧边栏菜单的标识；而顶部导航栏的位置参数应该是top，这是导致菜单跑到侧边的核心原因。

3. 父菜单ID错误 #

顶部导航栏的父菜单ID不是固定的1，不同环境可能有差异。可以通过查询数据库{{surveymenu}}表，找到position为top的菜单ID，或者用代码动态获取：

$topMenu = Surveymenu::model()->findByAttributes(['position' => 'top']);
$parentId = $topMenu ? $topMenu->id : 0;

4. 缺失权限控制 #

LimeSurvey的菜单需要绑定用户权限才能显示，默认新建菜单没有权限，管理员也看不到。需要给目标角色（比如admin）添加菜单访问权限。

修复后的完整代码 #

<?php

class Testplugin extends PluginBase
{
    protected $storage = 'DbStorage';
    static protected $description = "测试插件";
    static protected $name = "Testplugin";

    public function init()
    {
        $this->subscribe('onAdminMenuRender');
    }

    public function onAdminMenuRender()
    {
        // 动态获取顶部菜单父ID
        $topMenu = Surveymenu::model()->findByAttributes(['position' => 'top']);
        if (!$topMenu) return;
        $parentId = $topMenu->id;

        // 检查菜单是否已存在，避免重复创建
        $existingMenu = Surveymenu::model()->findByAttributes(['name' => 'testplugin_menu', 'parent_id' => $parentId]);
        if (!$existingMenu) {
            $menuArray = [
                "parent_id" => $parentId,
                "name" => "testplugin_menu",
                "title" => "管理公司",
                "position" => "top",
                "description" => "管理公司"
            ];
            $newMenuId = Surveymenu::staticAddMenu($menuArray);

            $menuEntryArray = [
                "name" => "manage_companies",
                "title" => "管理公司",
                "menu_title" => "管理公司",
                "menu_description" => "管理公司",
                "menu_icon" => "building",
                "menu_icon_type" => "fontawesome",
                "menu_link" => "admin/pluginhelper/sa/index/plugin/Testplugin",
                "addSurveyId" => false,
                "addQuestionGroupId" => false,
                "addQuestionId" => false,
                "linkExternal" => false,
                "hideOnSurveyState" => null,
                "manualParams" => ""
            ];
            SurveymenuEntries::staticAddMenuEntry($newMenuId, $menuEntryArray);

            // 给管理员角色添加菜单权限
            $this->assignMenuPermission($newMenuId);
        }
    }

    // 给管理员角色分配菜单权限
    private function assignMenuPermission($menuId)
    {
        $adminRole = Role::model()->findByAttributes(['name' => 'admin']);
        if ($adminRole) {
            Permission::model()->savePermission($adminRole->id, 'menu', $menuId, true);
        }
    }
}

额外注意事项 #

• 卸载插件后，数据库的{{surveymenu}}和{{surveymenu_entries}}表会残留旧数据，重新安装前建议手动删除相关记录；
• 确保menu_link指向的pluginhelper控制器路径正确，测试时可以直接访问该URL验证是否能打开。

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