README

介绍

这是对https://github.com/thormeier/breadcrumb-bundle的分支，合并了对 symfony 5.x 的更改和修复。此 Symfony 扩展包通过路由配置和 Twig 模板中的渲染提供面包屑的集成。此扩展包深受已停用的https://github.com/xi-project/xi-bundle-breadcrumbs的启发。

安装/开始使用

步骤 1: Composer require

$ php composer.phar require "szymat/breadcrumb-bundle"

步骤 2: 在内核中启用扩展包

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Thormeier\BreadcrumbBundle\ThormeierBreadcrumbBundle(),
        // ...
    );
}

配置

在您的 config.yml 中启用扩展包

# config.yml
thormeier_breadcrumb: ~

模板默认为基本模板，为每个面包屑提供一个带有 <li> 和 <a> 的 <ul>。

用法

基本

通过路由默认值中的 label 和 parent_route 字段创建面包屑树。基本树示例

# routing.yml

acme_demo_home:
    path: /
    options:
        breadcrumb:
            label: Home

acme_demo_contact:
    path: /contact
    options:
        breadcrumb:
            label: Contact
            parent_route: acme_demo_home

acme_demo_catalogue:
    path: /catalogue
    options:
        breadcrumb:
            label: 'Our Catalogue'
            parent_route: acme_demo_home

acme_demo_catalogue_categories:
    path: /catalogue/categories
    options:
        breadcrumb:
            label: 'All categories'
            parent_route: acme_demo_catalogue

将生成如下的面包屑树

acme_demo_home
    |- acme_demo_contact
    `- acme_demo_catalogue
       `- acme_demo_catalogue_categories

如果当前路由是 acme_demo_catalogue，面包屑将显示如下

Home > Our Catalogue

由于面包屑的配置是在路由配置中进行的，因此通常与路由配置的方式无关。这意味着通过注解等方式配置面包屑是完全可能的。

/**
 * ...
 * @Route(
 *    "/contact",
 *    name="acme_demo_contact",
 *    options={
 *        "breadcrumb" = {
 *            "label" = "Contact",
 *            "parent_route" = "acme_demo_home"
 *        }
 *    })
 * ...
 */

配置也可以通过 XML 和 PHP 进行。

动态路由

如果您有需要包含在面包屑中的动态路由或动态翻译，可以按如下方式定义

# routing.yml

acme_demo_product_detail:
    path: /products/{id}
    options:
        breadcrumb:
            label: 'Produkt: %%name%%'
            parent_route: acme_demo_catalogue

(此示例直接在路由中使用了包含占位符的字符串。您也可以在翻译文件中定义标签文本，只使用翻译键作为标签。模板将处理翻译和替换。)

注意标签中的双 % 用于转义参数。这是因为 routing.yml 被解析为 Symfony 容器时，会识别诸如 %name% 这样的容器参数，并尝试注入这些参数。双-% 转义它，模板处理其余部分。

然后您可以在 Breadcrumb 对象上直接设置参数，例如

<?php
// MyController

// ...

public function productDetailAction()
{
    $product = ...;

    // ...

    $this->get('thormeier_breadcrumb.breadcrumb_provider')
        ->getBreadcrumbByRoute('acme_demo_product_detail')
        ->setRouteParams(array(
            'id' => $product->getId(),
        ))
        ->setLabelParams(array(
            'name' => $product->getName(),
        ));
        
    // ...
}

请注意，必须定义在路由上的面包屑才能设置参数。

动态面包屑

如果您有动态路由树，例如无限深度的类别页面树，您可以在不定义在路由上的情况下动态添加面包屑。例如如下

<?php

use Thormeier\BreadcrumbBundle\Model\Breadcrumb;

// ...

// Route of the product, we want the categories before this
$productCrumb = $breadcrumbProvder->getBreadcrumbByRoute('acme_demo_product_detail');
$collection = $breadcrumbProvider->getBreadcrumbs();

foreach ($product->getCategories() as $category) {
    $newCrumb = new Breadcrumb(
        'Category: %name%',              // Label
        'acme_demo_category',            // Route
        ['id' => $category->getId()],    // Route params
        ['name' => $category->getName()] // Label params
    );
    
    // Adds $newCrumb right in front of $productCrumb
    $collection->addBreadcrumbBeforeCrumb($newCrumb, $productCrumb);
    
    // Or: ->addBreadcrumb(), ->addBreadcrumbAtPosition(), ->addBreadcrumbAfterCrumb(), ->addBreadcrumbToStart()
}

不过，这些面包屑不会存储在缓存中。

在 Twig 中显示

按如下方式调用 twig 扩展

{# someTemplate.html.twig #}
{# ... #}

{{ breadcrumbs() }}

{# ... #}

使用 Bootstrap 模板

此扩展包还提供了对Bootstrap的默认实现。可以如下使用

# config.yml
thormeier_breadcrumb:
    template: @ThormeierBreadcrumb/breadcrumbs_bootstrap.html.twig

替换默认模板

如果您想使用自定义模板，请在您的 config.yml 中添加以下内容

# config.yml
thormeier_breadcrumb:
    template: 'my twig template path'

您的自定义面包屑模板接收一个名为 breadcrumbs 的变量，它是一个表示您的面包屑的集合，按照从树中最顶层到最低层的顺序排列。

单个 breadcrumb 有 route、routeParameters、label 和 labelParameters 字段。使用 route 和 routeParameters 在 twig 中生成路径，例如 path(breadcrumb.route, breadcrumb.routeParameters)，而使用 label 和 labelParameters 生成面包屑文本，例如 {{ (breadcrumb.label)|trans(breadcrumb.labelParameters) }}

您的自定义模板可能看起来像这样

{# myBreadcrumbs.html.twig #}

<div>
    {% for breadcrumb in breadcrumbs %}
        <a href="{{ path(breadcrumb.route, breadcrumb.routeParameters) }}">
            {{ breadcrumb.label|replace({"%%": "%"})|trans(breadcrumb.labelParameters) }}
        </a>
    {% endfor %}
</div>

在模板内部将 %% 替换为单个 %。请参阅 "动态路由" 了解为什么需要这样做。

请查看 Resources/views/breadcrumbs.html.twig 和 Resources/views/breadcrumbs_bootstrap.html.twig 以了解默认实现。

自定义实现

模型类及其集合可以被替换为自己的实现，这些实现需要实现 Thormeier\BreadcrumbBundle\Model\BreadcrumbInterface 和 Thormeier\BreadcrumbBundle\Model\BreadcrumbCollectionInterface 接口。

# config.yml
thormeier_breadcrumb:
    model_class: Acme\Breadcrumbs\Model\MyModel
    collection_class: Acme\Breadcrumbs\Model\MyCollection

可以通过设置参数 provider_service_id 来替换提供者服务 ID。

# config.yml
thormeier_breadcrumb:
    provider_service_id: acme.breadcrumbs.my_provider

缓存

此扩展程序使用路由缓存来在 cache:warmup 上存储每个路由的面包屑列表。它们将在需要时转换为 BreadcrumbCollection。

幻灯片

有关此扩展程序和进一步解释一些概念的幻灯片可在 slideshare 上找到：[http://www.slideshare.net/Thormeier/thormeierbreadcrumbbundle](http://www.slideshare.net/Thormeier/thormeierbreadcrumbbundle)。

开发

要本地执行测试，请执行以下命令

./vendor/bin/phpunit

git 忽略 coverage/ 文件夹，因此可以使用它生成覆盖率报告：phpunit --coverage-html ./coverage/。

如果您想为此项目做出贡献，请随时打开问题报告和/或拉取请求！

szymat / breadcrumb-bundle

维护者

详细信息