Bdev Routing Extra Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bdev/bdev-routing-extra-bundle:dev-master
   

   Add the bundle to AppKernel.php:

   new BDev\Bundle\RoutingExtraBundle\BDevRoutingExtraBundle(),
   

2. Configure: Create config/routing.ext.yml (e.g., for route extras) and define it in config.yml:

   bdev_routing_extra:
       resource: "%kernel.root_dir%/config/routing.ext.yml"
       twig: true
       breadcrumb:
           label_attr: [breadcrumb, title]
   

3. First Use Case: Define a route with extras in routing.ext.yml:

   app_homepage:
       path: /
       defaults: { _controller: AppBundle:Page:home }
       bdev_routing_extra:
           title: "Welcome"
           breadcrumb: "Home"
   

   Use in Twig:

   <h1>{{ route_extra('title') }}</h1>
   {{ route_breadcrumb() }}
   

Implementation Patterns

Route Configuration

• Centralized Metadata: Define route-specific metadata (e.g., title, breadcrumb, menu) in routing.ext.yml to avoid hardcoding in templates.

  app_product_show:
      path: /product/{id}
      defaults: { _controller: AppBundle:Product:show }
      bdev_routing_extra:
          title: "Product: {{ product_name }}"
          breadcrumb: "Products > {{ product_name }}"
          menu:
              label: "Products"
              uri: app_product_index
  

• Dynamic Values: Use Twig variables or Symfony’s {{ app.request.attributes.get('product_name') }} for dynamic route extras.

Twig Integration

• Twig Functions:

  • route_extra('key'): Fetch a specific extra (e.g., title, description).
  • route_breadcrumb(): Render breadcrumbs from configured routes.
  • route_menu('menu_name'): Render a KnpMenu menu (if configured).

• Template Inheritance: Extend a base template to include common route extras:

  {% block title %}{{ parent() }} | {{ route_extra('title') }}{% endblock %}
  

KnpMenu Integration

• Menu Configuration: Define menus in config.yml:

  bdev_routing_extra:
      knp_menu:
          menus:
              main:
                  children_attributes:
                      class: "nav-link"
  

  Link routes to menus in routing.ext.yml:

  app_product_index:
      bdev_routing_extra:
          menu:
              main: ~  # Adds to 'main' menu
  

• Dynamic Menus: Use route_menu('main', {'current': app.request.get('_route')}) to highlight active routes.

Workflows

1. Add a New Route:

   • Define extras in routing.ext.yml.
   • Use Twig functions to render them dynamically.

2. Update Breadcrumbs:

   • Modify breadcrumb keys in route configs.
   • Clear cache (php bin/console cache:clear) if Twig extensions are used.

3. Menu Management:

   • Configure menus in config.yml.
   • Attach routes to menus via menu keys in routing.ext.yml.

Gotchas and Tips

Pitfalls

• Twig Extension Disabled: If twig: false in config, Twig functions (route_extra, route_breadcrumb) won’t work. Enable it for template usage.

• Caching Issues: After adding/updating routing.ext.yml, clear the cache:

  php bin/console cache:clear
  

• Route Overrides: Extras defined in routing.ext.yml override defaults in routing.yml. Use merge or append carefully to avoid unintended behavior.

• KnpMenu Dependencies: The bundle assumes KnpMenuBundle is installed for menu features. Install it separately if needed:

  composer require knplabs/knp-menu-bundle
  

Debugging

• Check Route Extras: Dump route extras in a controller to verify configuration:

  $extras = $this->get('router')->getRouteCollection()->get('app_homepage')->getOption('bdev_routing_extra');
  

• Twig Errors: If Twig functions fail, ensure:

  • The bundle is registered in AppKernel.php.
  • twig: true is set in config.yml.
  • The BDevRoutingExtraBundle is loaded after TwigBundle.

Tips

• Reuse Extras: Define common extras (e.g., meta_description) in a base route and extend them:

  _base:
      bdev_routing_extra:
          meta_description: "Default description"
  app_homepage:
      extends: _base
      bdev_routing_extra:
          title: "Homepage"
  

• Localization: Use Twig’s trans filter for translatable extras:

  bdev_routing_extra:
      title: "{{ 'route.title'|trans }}"
  

• Performance: Disable Twig extensions (twig: false) if you only need route extras in controllers (e.g., for APIs).

• Extension Points: Override Twig functions by extending the bundle’s TwigExtension:

  // src/AppBundle/Twig/AppExtension.php
  class AppExtension extends \BDev\Bundle\RoutingExtraBundle\Twig\RoutingExtraExtension
  {
      public function getFunctions()
      {
          return array_merge(parent::getFunctions(), [
              new \Twig_SimpleFunction('custom_route_extra', [$this, 'customRouteExtra']),
          ]);
      }
  }
  

  Register it as a compiler pass or service override.