README

为Symfony应用程序提供简单的面包屑导航。

要求

至少需要PHP 5.5。

此包需要Symfony HTTPKernel组件，并可以在任何使用Symfony的依赖注入组件的Symfony应用程序中使用（包括完整的Symfony框架）。

这意味着您可以在不要求使用Symfony FrameworkBundle的情况下使用它。

安装

要安装此包，将 rollerworks/breadcrumbs-bundle 添加到您的 composer.json 中

$ php composer.phar require rollerworks/breadcrumbs-bundle

现在，Composer 将自动下载所有必需的文件，并为您安装它们。

启用Bundle

注意

此包是为使用Symfony的应用程序设计的，但不要求使用Symfony FrameworkBundle。预计您对Symfony有足够的了解，可以以某种方式在您的应用程序中启用此Bundle。您应该至少注册了 request_stack 和 service_container 服务，并设置了自动加载。

此处显示的安装说明仅限于与Symfony-standard发行版一起使用。

运行Composer后，在您的内核中启用 RollerworksBreadcrumbsBundle

<?php

// in AppKernel::registerBundles()
$bundles = [
    // ...
    new Rollerworks\Bundle\BreadcrumbsBundle\RollerworksBreadcrumbsBundle(),
    // ...
];

基本用法

RollerworksBreadcrumbsBundle从提供者类加载面包屑，每个提供者类可以通过带有注释的方法提供一个或多个面包屑。

假设您的应用程序中有一个客户部分，以下是一个BreadcrumbsProvider类

namespace Acme\Customer;

use Rollerworks\Bundle\BreadcrumbsBundle\Annotation\Breadcrumb;
use Symfony\Component\HttpFoundation\Request;

class CustomerBreadcrumbsProvider
{
    /**
     * @Breadcrumb(name="acme_customer_home", route="acme_customer_home")
     */
    public function home(Request $request, array $breadcrumb)
    {
        return [
            'label' => 'Account',
            'route' => $breadcrumb['route'],
        ];
    }
}

现在您需要将提供者注册到服务容器中，这样BreadcrumbsLoader就可以找到它们

<?xml version="1.0" ?>

<container xmlns="https://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://symfony.ac.cn/schema/dic/services https://symfony.ac.cn/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="acme.breadcrumbs.customer" class="Acme\Customer\CustomerBreadcrumbsProvider">
            <tag name="rollerworks_breadcrumb.provider" />
        </service>
    </services>
</container>

或者如果您更喜欢YAML

services:
    acme.breadcrumbs.customer:
        class: "Acme\Customer\CustomerBreadcrumbsProvider"
        tags: [ { name: rollerworks_breadcrumb.provider } ]

就是这样，acme_customer_home 面包屑现在可用于加载。

提示：您也可以通过路由加载面包屑，这样您就不必为每个模板配置面包屑。简单地通过请求信息获取当前路由名称。

面包屑方法必须返回一个数组，但您可以决定使用哪些键和值。

按照惯例，建议至少返回一个标签和路由。当 route 键不存在时，它将自动设置为注解的 route 值。

额外参数

可以使用注解传递额外的属性

@Breadcrumb(name="acme_customer_home", route="acme_customer_home", route_parameters={"foo"="bar"})

可以使用 $breadcrumb['extra']['route_parameters'] 使用 route_parameters 属性。

您可以使用任何值或类型。

注意：当将extra属性传递给注解时，它必须是一个数组！并且它将覆盖所有其他额外参数。

面包屑父级路径

面包屑不仅仅只有一个，它们形成了一条通往起源的路径。幸运的是，RollerworksBreadcrumbsBundle提供了一种非常强大且易于创建面包屑路径的方法。

您只需要将parent属性添加到注解中。

@Breadcrumb(name="acme_customer_home", route="acme_customer_home", parent="acme_homepage")

parent的值必须指向另一个您希望用作父级的面包屑。在这个例子中，您会得到类似主页 > 账户的东西。

但是，当acme_homepage也有父级时，您的路径可能看起来像这样：Acme > 主页 > 账户。

注意：父级是在当前面包屑之后注册的，这无关紧要，所有面包屑都在容器编译过程中收集，然后计算它们的路径。

父级的数量没有限制，但父级不能引用已经在路径中的面包屑，因此这不会工作：Acme > 主页 > 账户 > Acme，因为它会导致无限循环。

基本配置

当在提供者中定义面包屑时，它们很可能共享一个共同或基本配置。例如，所有或大多数都以相同的名称/路由前缀开始，或者有相同的父级。

无需手动复制或重新输入这些内容，有一个更简单的解决方案。

namespace Acme\Customer;

use Rollerworks\Bundle\BreadcrumbsBundle\Annotation\BreadcrumbProvider;
use Rollerworks\Bundle\BreadcrumbsBundle\Annotation\Breadcrumb;
use Symfony\Component\HttpFoundation\Request;

/**
 * @BreadcrumbProvider(namePrefix="acme_customer.", routePrefix="acme_customer_", parent="app_homepage")
 */
class CustomerBreadcrumbsProvider
{
    /**
     * @Breadcrumb(name="home", route="home")
     */
    public function home(Request $request, array $breadcrumb)
    {
        return [
            'label' => 'Account',
            'route' => $breadcrumb['route'],
        ];
    }

    /**
     * @Breadcrumb(name="edit", route="edit")
     */
    public function edit(Request $request, array $breadcrumb)
    {
        return [
            'label' => 'Account',
            'route' => $breadcrumb['route'],
        ];
    }
}

@BreadcrumbProvider注解将为类中的所有面包屑设置基本配置。因此，home方法中的面包屑将变为@Breadcrumb(name="acme_customer.home", route="acme_customer_home", parent="app_homepage")。

同样适用于edit方法。

但如果您不需要为所有方法（或不是所有属性）都这样做，您仍然可以按面包屑覆盖配置。

namespace Acme\Customer;

use Rollerworks\Bundle\BreadcrumbsBundle\Annotation\BreadcrumbProvider;
use Rollerworks\Bundle\BreadcrumbsBundle\Annotation\Breadcrumb;
use Symfony\Component\HttpFoundation\Request;

/**
 * @BreadcrumbProvider(namePrefix="acme_customer.", routePrefix="acme_customer_", parent="app_homepage")
 */
class CustomerBreadcrumbsProvider
{
    /**
     * @Breadcrumb(name="home", route="home")
     */
    public function home(Request $request, array $breadcrumb)
    {
        return [
            'label' => 'Account',
            'route' => $breadcrumb['route'],
        ];
    }

    /**
     * @Breadcrumb(name="edit", route="edit")
     */
    public function edit(Request $request, array $breadcrumb)
    {
        return [
            'label' => 'Account',
            'route' => $breadcrumb['route'],
        ];
    }

    /**
     * @Breadcrumb(fullName="acme_customer.group_list", fullRoute="acme_group_list", parent="")
     */
    public function listGroups(Request $request, array $breadcrumb)
    {
        return [
            'label' => 'Account',
            'route' => $breadcrumb['route'],
        ];
    }
}

现在，listGroups方法将忽略基本配置，仅使用它自己的配置。

注意：extra属性将覆盖继承的额外信息。

多个@Breadcrumb注解

如果您的面包屑非常静态，例如只有一个路由、标签和一些额外信息，您也可以使用单个方法为多个面包屑提供服务。

namespace Acme\Customer;

use Rollerworks\Bundle\BreadcrumbsBundle\Annotation\BreadcrumbProvider;
use Rollerworks\Bundle\BreadcrumbsBundle\Annotation\Breadcrumb;
use Symfony\Component\HttpFoundation\Request;

/**
 * @BreadcrumbProvider(namePrefix="acme_customer.", routePrefix="acme_customer_", parent="app_homepage")
 */
class CustomerBreadcrumbsProvider
{
    /**
     * @Breadcrumb(name="acme_customer.home", route="home", label="Account")
     * @Breadcrumb(name="acme_customer.edit", route="edit", label="Edit", parent="acme_customer.home")
     */
    public function action(Request $request, array $breadcrumb)
    {
        return [
            'label' => $breadcrumb['extra']['label'],
            'route' => $breadcrumb['route'],
        ];
    }
}

action方法将针对每个面包屑调用，但具有不同的数据。

特别说明

类和方法名称不重要，您可以使用任何您喜欢的东西。但方法必须声明为public。参数不是必需的。

$request提供了有关当前请求的信息。

$breadcrumb参数提供了面包屑的规范化信息

• name: 面包屑的名称。
• parent: 面包屑的父级（为空时为null）。
• class: 面包屑提供者的完整限定类名。
• service: 面包屑提供者的服务-id。
• method: 提供者的方法名称（基本上是当前方法）。
• extra: 作为数组提供的所有额外属性。
• trail: 从根到当前面包屑的面包屑路径，所有值都是面包屑名称。

包含容器参数的参数

所有参数值（包括额外参数）都通过ServiceContainer的参数包解析。值%somevar%将被替换为容器参数值%somevar%。

非额外参数只接受字符串值。

注意：数组值是递归解析的，这意味着所有更深层级也将被解析。

要在参数或属性中直接使用百分号，必须使用另一个百分号进行转义：foo%%somevar%%bar。

另请参阅

https://symfony.ac.cn/doc/current/components/dependency_injection/parameters.html https://symfony.ac.cn/doc/current/book/service_container.html#service-parameters

版本控制

为了提高透明度和对发布周期的洞察力，以及努力保持向后兼容性，尽可能在本包中遵循语义版本控制指南。

版本号将采用以下格式

<主版本>.<次版本>.<修订版本>

并遵循以下指南

• 破坏向后兼容性会增加主版本（并重置次版本和修订版本）
• 没有破坏向后兼容性的新功能会增加次版本（并重置修订版本）
• 错误修复和其他更改会增加修订版本

有关SemVer的更多信息，请访问http://semver.org/。

许可

本包在MIT许可下提供。