Seo Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require rami/seo-bundle
   

   Ensure Abdellahramadan\SeoBundle\SeoBundle::class is registered in config/bundles.php.

2. First Use Case: Inject MetaTagsManagerInterface into a controller to set basic SEO metadata:

   use Abdellahramadan\SeoBundle\Metas\MetaTagsManagerInterface;
   
   public function index(MetaTagsManagerInterface $metaTags): Response
   {
       $metaTags->setTitle('Page Title')
           ->setDescription('Page description for search engines');
   
       return $this->render('page.html.twig');
   }
   

3. Where to Look First:

   • Documentation (linked in README).
   • config/packages/abdellahramadan_seo.yaml (default config).
   • src/Controller/ for controller-level SEO logic.

Implementation Patterns

Core Workflows

1. Controller-Level SEO: Use dependency injection to set metadata dynamically:

   public function show(MetaTagsManagerInterface $metaTags, $id)
   {
       $metaTags->setTitle("Product #$id")
           ->setCanonicalUrl($this->generateUrl('product_show', ['id' => $id]));
   }
   

2. Twig Integration: Extend templates with SEO blocks:

   {% block meta_tags %}
       {{ seo.meta_tags() }}
   {% endblock %}
   

3. Structured Data (Schema): Define schema in YAML (e.g., config/packages/abdellahramadan_seo.yaml):

   seo:
       schema:
           '@product': '@App\Dto\ProductSchema'
   

   Implement SchemaInterface in a DTO:

   class ProductSchema implements SchemaInterface
   {
       public function getSchema(array $data): array
       {
           return [
               '@context' => 'https://schema.org',
               '@type' => 'Product',
               'name' => $data['name'],
               // ...
           ];
       }
   }
   

4. Sitemap Generation: Configure routes in config/packages/abdellahramadan_seo.yaml:

   seo:
       sitemap:
           routes:
               - { route: 'homepage' }
               - { route: 'product_list' }
   

   Generate via CLI:

   php bin/console seo:sitemap:generate
   

5. OpenGraph/Twitter Cards: Set dynamic properties in controllers:

   $metaTags->setOpenGraphImage($product->getImageUrl())
       ->setTwitterCard('summary_large_image');
   

Integration Tips

• Event Listeners: Use KernelEvents::VIEW to modify SEO metadata globally:

  public function onKernelView(ViewEvent $event)
  {
      $metaTags = $event->getController()[1]->getMetaTags();
      $metaTags->setKeywords('seo, laravel');
  }
  

• Environment-Specific Config: Override defaults in config/packages/dev/abdellahramadan_seo.yaml for staging/production.
• Caching: Enable seo.cache.enabled in config to cache metadata (reduces DB/controller calls).

Gotchas and Tips

Pitfalls

1. Missing Dependencies:

   • Ensure twig and symfony/twig-bridge are installed (required for Twig integration).
   • For sitemaps, symfony/routing must be configured.

2. Schema Validation:

   • Structured data must adhere to Schema.org standards. Validate output with Google’s Rich Results Test.
   • Example error: Forgetting @context in schema DTOs causes malformed JSON-LD.

3. Sitemap Generation:

   • Routes must be public and cacheable (e.g., avoid GET with side effects).
   • Default sitemap URL is /sitemap.xml. Customize via seo.sitemap.url in config.

4. Profiler Overhead:

   • SEO profiling in dev mode (seo.profiler.enabled) adds latency. Disable in production:

     seo:
         profiler:
             enabled: "%kernel.debug%"
     

5. Twig Template Conflicts:

   • If {{ seo.meta_tags() }} renders nothing, check:
     • The Twig extension is loaded (Abdellahramadan\SeoBundle\Twig\SeoExtension).
     • No other bundles override meta_tags block.

Debugging

• Profiler Tab: Use the Symfony profiler’s "SEO" tab to inspect metadata, OpenGraph tags, and schema.
• Log Metadata: Enable debug logging in config/packages/dev/monolog.yaml:

  handlers:
      seo:
          type: stream
          path: "%kernel.logs_dir%/seo.log"
          level: debug
          channels: ["seo"]
  

• CLI Commands:
  • Validate sitemap: php bin/console seo:sitemap:validate.
  • Clear cache: php bin/console cache:clear.

Extension Points

1. Custom Meta Tags: Extend MetaTagsManager by implementing MetaTagsInterface:

   class CustomMetaTags implements MetaTagsInterface
   {
       public function setCustomTag(string $name, string $content): self
       {
           // ...
       }
   }
   

   Register as a service:

   services:
       App\Service\CustomMetaTags:
           tags: ['seo.meta_tags_manager']
   

2. Dynamic Schema: Use SchemaManagerInterface to fetch schema data from APIs:

   public function getSchema(array $data): array
   {
       $product = $this->productApi->fetch($data['id']);
       return $this->schemaFactory->createProductSchema($product);
   }
   

3. Breadcrumb Customization: Override the default BreadcrumbGenerator:

   services:
       App\Generator\CustomBreadcrumbGenerator:
           decorates: 'abdellahramadan_seo.breadcrumb_generator'
           arguments: ['@abdellahramadan_seo.breadcrumb_generator']
   

4. Google Tag Manager (GTM): Combine with symfony/webpack-encore to inject GTM dynamically:

   {{ seo.google_tag() }}
   {{ encore_entry_script_tags('gtm') }}
   

Configuration Quirks

• Default Values: All options are nullable. Explicitly set null to override defaults:

  seo:
      meta_tags:
          default:
              author: null  # Disables default author
  

• Priority Order: Metadata is merged in this order:

  1. Controller-level overrides.
  2. Route-level annotations (if using seo.route).
  3. Global config defaults.

• Sitemap Frequency: Use seo.sitemap.frequency to set <changefreq> (e.g., daily, weekly). Default is monthly.