Sonata Seo Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   • Clone the repository into your project’s src/Awaresoft directory.
   • Symlink the bundle to your project’s vendor (if not using the utils/prepare_vendors script).
   • Ensure composer.json references the local path (e.g., "awaresoft/sonata-seo-bundle": "dev-main").
   • Run composer update and clear the cache:

     php bin/console cache:clear
     

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       Awaresoft\SonataSeoBundle\SonataSeoBundle::class => ['all' => true],
   ];
   

3. First Use Case:

   • Configure SEO metadata for a route (e.g., app/config/routing.yml):

     sonata_seo:
         resource: "@SonataSeoBundle/Resources/config/routing.yml"
         prefix: /
     

   • Define metadata in a controller or Twig template:

     {% seo_meta title="My Page Title" description="SEO description" %}
     

Implementation Patterns

Core Workflows

1. Dynamic Metadata:

   • Use Twig extensions (sonata_seo_meta) to inject metadata dynamically:

     {% seo_meta title=page.title description=page.meta_description %}
     

   • Override metadata per route via annotations or YAML:

     # app/config/sonata_seo.yml
     sonata_seo:
         routes:
             app_homepage:
                 title: "Home | My Site"
                 description: "Welcome to our site!"
     

2. OpenGraph/Facebook Integration:

   • Extend the bundle’s SonataSeoService to add OpenGraph tags:

     // src/Service/CustomSeoService.php
     public function addOpenGraphTags(array $tags)
     {
         $this->getMetadataBag()->addTags($tags);
     }
     

   • Call in Twig:

     {% seo_meta og:title=page.title og:image=page.imageUrl %}
     

3. Caching Strategies:

   • Cache metadata in a MetadataBag service for performance:

     $metadata = $this->get('sonata.seo.metadata_bag');
     $metadata->set('route_name', ['title' => 'Cached Title']);
     

4. Event-Driven SEO:

   • Listen to sonata.seo.metadata.build events to modify metadata:

     // src/EventListener/SeoListener.php
     public function onBuildMetadata(SeoEvent $event)
     {
         $event->getMetadata()->setTitle('Modified Title');
     }
     

   • Register in services.yml:

     services:
         App\EventListener\SeoListener:
             tags:
                 - { name: kernel.event_listener, event: sonata.seo.metadata.build, method: onBuildMetadata }
     

Gotchas and Tips

Pitfalls

1. Symfony 2.x Dependency:

   • The bundle targets Symfony 2.x (not 3/4/5/6). Ensure compatibility with your project’s version.
   • Workaround: Use a wrapper or fork if upgrading Symfony.

2. Metadata Overrides:

   • Route-based overrides in YAML take precedence over Twig/annotations, but annotations override YAML.
   • Debug with:

     php bin/console debug:container sonata.seo.metadata_bag
     

3. Caching Issues:

   • Clear the cache after modifying metadata configurations:

     php bin/console cache:clear --env=prod
     

   • Use metadata_bag.clear() in a custom command if needed.

4. Twig Extension Conflicts:

   • If sonata_seo_meta fails, check for duplicate Twig extensions. Rename or remove conflicting ones.

Debugging Tips

• Log Metadata: Add a listener to dump metadata:

  public function onBuildMetadata(SeoEvent $event)
  {
      \Log::debug('SEO Metadata:', $event->getMetadata()->all());
  }
  

• Validate Tags: Use browser dev tools to inspect rendered <meta> tags. Missing tags often stem from:
  • Incorrect Twig syntax (e.g., {% seo_meta ... %} vs. {{ seo_meta(...)).
  • Unregistered services (e.g., metadata_bag not autowired).

Extension Points

1. Custom Metadata Providers: Extend SonataSeoBundle\Provider\MetadataProviderInterface to fetch metadata from APIs or databases:

   class ApiMetadataProvider implements MetadataProviderInterface
   {
       public function getMetadata(string $route): array
       {
           return json_decode(file_get_contents("https://api.example.com/seo/$route"), true);
       }
   }
   

   Register in services.yml:

   services:
       App\Provider\ApiMetadataProvider:
           tags:
               - { name: sonata.seo.metadata_provider }
   

2. Modify MetadataBag: Override the default MetadataBag to add custom logic:

   // src/SonataSeo/CustomMetadataBag.php
   class CustomMetadataBag extends MetadataBag
   {
       public function addCustomTag(string $name, string $content)
       {
           $this->tags[$name] = $content;
       }
   }
   

   Bind in services.yml:

   services:
       sonata.seo.metadata_bag:
           class: App\SonataSeo\CustomMetadataBag
           public: true
   

3. Route-Specific Logic: Use the sonata.seo.route_listener event to inject route-specific data:

   public function onRoute(SeoRouteEvent $event)
   {
       $event->setMetadata(['canonical' => route('canonical', ['id' => $event->getRoute()->getDefault('_id')])]);
   }