Easy Seo Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require agence-adeliom/easy-seo-bundle
   

   Ensure your composer.json includes the Flex endpoint for seamless integration.

2. Enable the Bundle The bundle auto-registers with Symfony Flex, so no manual AppKernel.php changes are needed.

3. Add SEO to an Entity Extend your entity with the EntitySeoTrait:

   use Adeliom\EasySeoBundle\Traits\EntitySeoTrait;
   
   class Article
   {
       use EntitySeoTrait;
   }
   

4. Configure Basic SEO in EasyAdmin Add the SEOField to your CRUD controller:

   use Adeliom\EasySeoBundle\Field\SEOField;
   
   class ArticleCrudController extends AbstractCrudController
   {
       public function configureFields(string $pageName): iterable
       {
           yield SEOField::new('seo');
       }
   }
   

5. Render SEO in Twig Use the provided Twig functions in your templates:

   {{- seo_title(object.seo) -}}
   {{- seo_metas(object.seo) -}}
   {{- seo_breadcrumb() -}}
   

Implementation Patterns

Workflow: SEO for a New Entity

1. Entity Setup Add EntitySeoTrait to your entity (e.g., Product, BlogPost).

   class BlogPost
   {
       use EntitySeoTrait;
   }
   

2. EasyAdmin Integration Include the SEOField in your CRUD controller’s configureFields() method.

   yield SEOField::new('seo')
       ->setLabel('SEO Settings')
       ->setColumns(3);
   

3. Customize SEO Output Override default behavior via events (e.g., modify titles dynamically):

   $dispatcher->addListener('easyseo.title', function (Event $event) {
       $title = $event->getArgument('title');
       $event->setArgument('title', 'Custom Prefix: ' . $title);
   });
   

4. Twig Integration Embed SEO tags in your base template:

   {% block meta %}
       {{- seo_metas(object.seo) -}}
   {% endblock %}
   

Integration Tips

• Dynamic SEO for Collections Use the easyseo.render_meta event to inject dynamic meta tags (e.g., OpenGraph for lists):

  $dispatcher->addListener('easyseo.render_meta', function (Event $event) {
      $seoData = $event->getArgument('datas');
      $seoData['opengraph']['type'] = 'website';
      $event->setArgument('datas', $seoData);
  });
  

• Breadcrumb Customization Modify breadcrumb structure via the easyseo.breadcrumb event:

  $dispatcher->addListener('easyseo.breadcrumb', function (Event $event) {
      $items = $event->getArgument('items');
      array_unshift($items, ['label' => 'Home', 'url' => path('home')]);
      $event->setArgument('items', $items);
  });
  

• Conditional SEO Disable SEO for specific routes in easy_seo.yaml:

  easy_seo:
      ignore_profiler:
          - '^/admin*'
          - '^/api/*'
  

Gotchas and Tips

Pitfalls

1. Entity Trait Conflicts

   • Issue: EntitySeoTrait may conflict with existing traits (e.g., Timestampable).
   • Fix: Ensure your entity extends SeoInterface explicitly or merge trait methods manually.

2. Caching Headaches

   • Issue: SEO metadata may not update immediately due to Symfony’s HTTP cache.
   • Fix: Clear the cache after updating SEO fields:

     php bin/console cache:clear
     

3. Event Dispatcher Order

   • Issue: Events may override each other unpredictably.
   • Fix: Use priority flags in event listeners:

     $dispatcher->addListener('easyseo.title', [$this, 'modifyTitle'], 100); // Higher priority
     

4. Twig Function Scope

   • Issue: seo_title() or seo_metas() may fail if object.seo is undefined.
   • Fix: Use null checks in Twig:

     {% if object.seo is not null %}
         {{- seo_title(object.seo) -}}
     {% endif %}
     

Debugging Tips

• Profiler Integration Enable the Symfony profiler to inspect SEO data:

  easy_seo:
      enable_profiler: '%kernel.debug%'
  

  Access the EasySeo tab in the profiler for real-time metadata previews.

• Log SEO Events Debug event listeners by logging arguments:

  $dispatcher->addListener('easyseo.title', function (Event $event) {
      \Log::debug('SEO Title Event', ['title' => $event->getArgument('title')]);
  });
  

• Validate SEO Fields Use EasyAdmin’s validation to enforce SEO requirements:

  yield SEOField::new('seo')
      ->setValidationGroups(['Default', 'seo']);
  

Extension Points

1. Custom Meta Tags Extend the SeoInterface to add proprietary meta fields:

   interface SeoInterface extends \Adeliom\EasySeoBundle\Model\SeoInterface
   {
       public function getCustomMeta(): string;
   }
   

2. Sitemap Integration Leverage presta/sitemap-bundle (dependency) to auto-generate sitemaps from SEO entities:

   presta_sitemap:
       sitemaps:
           default:
               routes: ['app_homepage']
               entities: [App\Entity\Article]
   

3. Multi-Language Support Use Symfony’s translation system to localize SEO fields:

   $seo->setTitle($translator->trans('article.title', [], 'seo'));