Seo Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require atoolo/seo-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Atoolo\SeoBundle\AtooloSeoBundle::class => ['all' => true],
   ];
   

2. Configuration: Publish the default config:

   php bin/console config:dump-reference AtooloSeoBundle
   

   Or override in config/packages/atoolo_seo.yaml:

   atoolo_seo:
       sitemap:
           enabled: true
           max_urls_per_sitemap: 2000  # Default from 1.1.0
           routes: ['app.homepage', 'app.blog_post']
   

3. First Use Case: Generate a sitemap by visiting /sitemap.xml (route: atoolo_seo.sitemap). The bundle auto-discovers routes based on your routes.yaml or annotations.

Implementation Patterns

Core Workflows

1. Sitemap Generation:

   • Dynamic Routes: Configure routes in atoolo_seo.yaml under sitemap.routes. Supports named routes (Symfony’s app.* syntax).

     sitemap:
         routes:
             - 'app.homepage'
             - { route: 'app.blog_post', priority: 0.8 }
     

   • Custom URL Providers: Extend Atoolo\SeoBundle\Provider\UrlProviderInterface to fetch URLs dynamically (e.g., from a database).

     class CustomUrlProvider implements UrlProviderInterface {
         public function getUrls(): array {
             return [
                 ['url' => '/dynamic-page', 'priority' => 0.9],
             ];
         }
     }
     

     Register as a service:

     services:
         App\Provider\CustomUrlProvider:
             tags: ['atoolo_seo.url_provider']
     

2. URL Rewriting:

   • Leverage the atoolo/rewrite-bundle integration to canonicalize URLs. Configure in atoolo_rewrite.yaml:

     rewrites:
         - { pattern: '/old-url', to: '/new-url' }
     

3. Meta Tags:

   • Use Symfony’s Twig to inject meta tags via the atoolo_seo Twig extension:

     {% seo_meta title: 'Page Title' description: 'Meta description' %}
     

   • For dynamic content, extend the Atoolo\SeoBundle\Twig\SeoExtension or create a custom Twig function.

Integration Tips

• Caching: Enable HTTP caching for sitemaps via Symfony’s HttpCache or VarCache:

  framework:
      http_cache:
          sitemap_cache: true
  

• Validation: Use phpstan (level 9) to catch type-related issues early.
• Testing: Mock the UrlProviderInterface in PHPUnit:

  $this->container->set('atoolo_seo.url_provider.custom', $mockProvider);
  

Gotchas and Tips

Pitfalls

1. Route Discovery:

   • The bundle does not auto-discover all routes by default. Explicitly list routes in atoolo_seo.yaml or implement a custom UrlProvider.
   • Fix: Use php bin/console debug:router to verify route names.

2. XML Limits:

   • Sitemaps are split at max_urls_per_sitemap (default: 2000). Monitor memory usage for large sites.
   • Tip: Set a lower limit (e.g., 1000) if hitting PHP memory limits.

3. Twig Extension:

   • The seo_meta Twig function overwrites existing meta tags. Use sparingly or wrap in conditional blocks:

     {% if not meta_tags_defined %}
         {% seo_meta title: 'Fallback Title' %}
     {% endif %}
     

4. Dependency Conflicts:

   • The bundle requires atoolo/resource-bundle, atoolo/search-bundle, and atoolo/rewrite-bundle. Ensure these are installed and configured.
   • Tip: Run composer why-not atoolo/seo-bundle to debug missing dependencies.

Debugging

• Sitemap Output: Check the generated XML at /sitemap.xml or debug the UrlProvider:

  $provider = $container->get('atoolo_seo.url_provider.main');
  var_dump($provider->getUrls());
  

• Logs: Enable debug mode (APP_DEBUG=true) to log sitemap generation warnings.

Extension Points

1. Custom Sitemap Index: Override the Atoolo\SeoBundle\Controller\SitemapController to modify the sitemap index structure (e.g., add lastmod or changefreq).

2. Event Listeners: Subscribe to atoolo.seo.sitemap.generate to inject URLs dynamically:

   use Symfony\Component\EventDispatcher\GenericEvent;
   
   $dispatcher->addListener('atoolo.seo.sitemap.generate', function (GenericEvent $event) {
       $event->getArgument('urls')->add(['url' => '/dynamic-url']);
   });
   

3. Configuration Overrides: Use environment-specific configs (e.g., config/packages/dev/atoolo_seo.yaml) to toggle features:

   # config/packages/dev/atoolo_seo.yaml
   atoolo_seo:
       sitemap:
           enabled: false  # Disable in dev