Seo Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require astina/seo-bundle:dev-master
   

   Add the bundle to app/AppKernel.php:

   new Astina\Bundle\SeoBundle\AstinaSeoBundle(),
   

2. Enable Routing (optional for admin UI):

   # app/config/routing.yml
   astina_seo:
       resource: "@AstinaSeoBundle/Resources/config/routing.yml"
   

   Secure the route in app/config/security.yml (e.g., restrict to ROLE_ADMIN).

3. First Use Case: Render meta tags in a Twig template (e.g., base.html.twig):

   {{ seo_meta_tags(app.request) }}
   

   This fetches PageMetaData for the current route and renders <title>, <meta description>, and <meta keywords>.

Implementation Patterns

Core Workflow

1. Define PageMetaData Entities: Create a PageMetaData entity (e.g., via Doctrine) with fields:

   // src/Acme/AppBundle/Entity/PageMetaData.php
   /**
    * @ORM\Entity(repositoryClass="Acme\AppBundle\Repository\PageMetaDataRepository")
    */
   class PageMetaData {
       // @ORM\Id, @ORM\Column, etc.
       private $title;
       private $description;
       private $keywords;
       private $route; // e.g., "homepage", "product_show"
   }
   

2. Configure Global Defaults (optional):

   # app/config.yml
   astina_seo:
       global_defaults:
           title: "My App"
           description: "Default description"
           keywords: "laravel, seo"
   

3. Override Meta Tags per Route:

   • Twig: Pass custom defaults to seo_meta_tags:

     {{ seo_meta_tags(app.request, "Custom Title", {"description": "Custom desc"}) }}
     

   • Controller: Dynamically set metadata via PageMetaData entity (e.g., via a form in an admin panel).

4. Admin Integration:

   • Use the bundled routes (/seo/{route}) to CRUD PageMetaData entries.
   • Extend the admin UI (e.g., with SonataAdmin) for a polished experience.

Advanced Patterns

• Dynamic Title Suffixes: Append suffixes dynamically (e.g., for pagination):

  {{ seo_meta_tags(app.request, null, {}, " - Page " ~ pageNumber) }}
  

• Route-Based Fallbacks: Use Doctrine’s PageMetaDataRepository to fetch metadata by route pattern:

  $metaData = $repo->findOneBy(['route' => $request->get('_route')]);
  

• Event Listeners: Hook into kernel.request to preload metadata for performance:

  // src/Acme/AppBundle/EventListener/SeoListener.php
  public function onKernelRequest(GetResponseEvent $event) {
      $request = $event->getRequest();
      $metaData = $this->get('astina_seo.page_metadata')->findForRequest($request);
      // Cache or preprocess...
  }
  

Gotchas and Tips

Pitfalls

1. Route Mismatches:

   • The bundle matches PageMetaData by exact route name (e.g., homepage). Use wildcards (*) or generic routes (e.g., product_show) sparingly to avoid conflicts.
   • Fix: Normalize route names (e.g., via a listener) or use route parameters (e.g., product_show_{id}).

2. Missing Entities:

   • If no PageMetaData exists for a route, the bundle falls back to global defaults. Test edge cases (e.g., 404 pages) to ensure defaults render correctly.
   • Fix: Add a null check in Twig:

     {% if seo_meta_tags(app.request) is not empty %}
         {{ seo_meta_tags(app.request) }}
     {% endif %}
     

3. Caching Issues:

   • Meta tags may not update immediately if cached (e.g., by Varnish or OPcache). Clear caches after editing PageMetaData.
   • Fix: Use php bin/console cache:clear or implement a cache invalidation event.

4. Twig Template Overrides:

   • The seo_meta_tags function assumes a specific Twig template structure. Overriding it requires extending the bundle’s TwigExtension.
   • Fix: Copy the template from AstinaSeoBundle/Resources/views/PageMetaData/meta_tags.html.twig to your theme.

Debugging Tips

• Log Missing Metadata: Add a debug listener to log unmatched routes:

  public function onKernelRequest(GetResponseEvent $event) {
      $request = $event->getRequest();
      $metaData = $this->get('astina_seo.page_metadata')->findForRequest($request);
      if (!$metaData) {
          $this->logger->debug('No SEO metadata for route: ' . $request->get('_route'));
      }
  }
  

• Check Route Names: Dump the current route name in a template to verify matches:

  {{ dump(app.request.get('_route')) }}
  

Extension Points

1. Custom Metadata Fields: Extend the PageMetaData entity and override the Twig template to include additional tags (e.g., Open Graph):

   <!-- templates/AcmeBundle/PageMetaData/meta_tags.html.twig -->
   {% extends 'AstinaSeoBundle::meta_tags.html.twig' %}
   {% block meta_tags %}
       {{ parent() }}
       <meta property="og:image" content="{{ metaData.ogImage }}" />
   {% endblock %}
   

2. Dynamic Metadata Generation: Use a controller event subscriber to generate metadata on-the-fly (e.g., for product pages):

   public function onKernelController(FilterControllerEvent $event) {
       $metaData = new PageMetaData();
       $metaData->setTitle($product->getName());
       $metaData->setDescription($product->getShortDescription());
       $event->getRequest()->attributes->set('astina_seo.metadata', $metaData);
   }
   

3. Multi-Language Support: Store translations in PageMetaData (e.g., via Gedmo Translatable) and pass the locale to seo_meta_tags:

   {{ seo_meta_tags(app.request, null, {}, null, app.request.locale) }}