KnpMenuBundle 技术文档

1. 安装指南

1.1 使用 Composer 安装

要安装 KnpMenuBundle，首先需要确保你已经安装了 Composer。然后在你的项目目录中执行以下命令：

composer require knplabs/knp-menu-bundle

1.2 启用 Bundle

安装完成后，你需要在你的 Symfony 项目中启用 KnpMenuBundle。如果你使用的是 Symfony Flex，Bundle 会自动启用和配置。如果你没有使用 Flex，可以在你的项目 Kernel 中手动启用它：

// 例如在 app/AppKernel.php 中
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // 其他 bundles
            new Knp\Bundle\MenuBundle\KnpMenuBundle(),
        ];

        return $bundles;
    }
}

1.3 配置 Bundle

Bundle 自带了合理的默认配置，但你可以根据需要进行自定义配置。配置文件通常位于 config/packages/knp_menu.yaml 中：

knp_menu:
    # 自定义配置选项

2. 项目的使用说明

2.1 创建你的第一个菜单

KnpMenuBundle 提供了多种方式来创建菜单。以下是三种常见的方法：

方法 a) 简单方式

使用 Symfony 的依赖注入容器来创建菜单：

use Knp\Menu\MenuItem;

$menu = $this->container->get('knp_menu.menu_factory')->createItem('My Menu');
$menu->addChild('Home', ['uri' => '/']);
$menu->addChild('About', ['uri' => '/about']);

方法 b) 使用菜单构建器作为服务

创建一个菜单构建器服务：

namespace App\Menu;

use Knp\Menu\FactoryInterface;
use Symfony\Component\DependencyInjection\ContainerAwareInterface;
use Symfony\Component\DependencyInjection\ContainerAwareTrait;

class Builder implements ContainerAwareInterface
{
    use ContainerAwareTrait;

    public function mainMenu(FactoryInterface $factory, array $options)
    {
        $menu = $factory->createItem('My Menu');
        $menu->addChild('Home', ['uri' => '/']);
        $menu->addChild('About', ['uri' => '/about']);

        return $menu;
    }
}

然后在你的服务配置中注册这个构建器：

services:
    App\Menu\Builder:
        tags:
            - { name: knp_menu.menu_builder, method: mainMenu, alias: main }

方法 c) 使用菜单作为服务

你也可以直接将菜单定义为服务：

services:
    app.menu.main:
        class: Knp\Menu\MenuItem
        factory: ['@knp_menu.menu_factory', 'createItem']
        arguments: ['My Menu']
        calls:
            - [addChild, ['Home', ['uri' => '/']]]
            - [addChild, ['About', ['uri' => '/about']]]

2.2 渲染菜单

在 Twig 模板中渲染菜单：

{{ knp_menu_render('main') }}

3. 项目 API 使用文档

3.1 菜单工厂 (MenuFactory)

MenuFactory 是创建菜单项的核心类。你可以使用它来创建菜单项并添加子项。

use Knp\Menu\FactoryInterface;

class MyMenuBuilder
{
    private $factory;

    public function __construct(FactoryInterface $factory)
    {
        $this->factory = $factory;
    }

    public function createMenu()
    {
        $menu = $this->factory->createItem('My Menu');
        $menu->addChild('Home', ['uri' => '/']);
        $menu->addChild('About', ['uri' => '/about']);

        return $menu;
    }
}

3.2 菜单项 (MenuItem)

MenuItem 代表菜单中的一个项。你可以通过 addChild 方法添加子项，并通过 setUri 方法设置链接。

$menu = $factory->createItem('My Menu');
$menu->addChild('Home', ['uri' => '/']);
$menu->addChild('About', ['uri' => '/about']);

3.3 菜单渲染器 (MenuRenderer)

MenuRenderer 用于将菜单渲染为 HTML。你可以使用 knp_menu_render 函数在 Twig 模板中渲染菜单。

{{ knp_menu_render('main') }}

4. 项目安装方式

4.1 通过 Composer 安装

composer require knplabs/knp-menu-bundle

4.2 手动启用 Bundle

如果你没有使用 Symfony Flex，可以在你的项目 Kernel 中手动启用 KnpMenuBundle：

// 例如在 app/AppKernel.php 中
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // 其他 bundles
            new Knp\Bundle\MenuBundle\KnpMenuBundle(),
        ];

        return $bundles;
    }
}

4.3 配置 Bundle

根据需要自定义配置文件：

knp_menu:
    # 自定义配置选项

通过以上步骤，你可以成功安装并使用 KnpMenuBundle 来创建和管理 Symfony 应用程序中的菜单。