Sitemap Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require berriart/sitemap-bundle
   

   Add to config/bundles.php:

   Berriart\SitemapBundle\BerriartSitemapBundle::class => ['all' => true],
   

2. Configuration Add to config/packages/berriart_sitemap.yaml:

   berriart_sitemap:
       default_locale: en
       base_url: 'https://example.com'
       sitemap:
           filename: 'sitemap.xml'
           path: '/'
   

3. First Use Case Generate a basic sitemap via CLI:

   php bin/console berriart:sitemap:generate
   

   Outputs to web/sitemap.xml (or configured path).

Implementation Patterns

Core Workflows

1. Dynamic URL Registration Use the SitemapUrl entity to define URLs programmatically:

   use Berriart\SitemapBundle\Entity\SitemapUrl;
   
   $url = new SitemapUrl();
   $url->setUrl('/products/123')
       ->setChangeFrequency(SitemapUrl::CHANGE_FREQUENCY_DAILY)
       ->setPriority(0.8);
   $em->persist($url);
   

2. Doctrine Integration Fetch URLs from a repository and map them to SitemapUrl:

   $urls = $productRepository->findAll();
   foreach ($urls as $product) {
       $url = new SitemapUrl();
       $url->setUrl($product->getSlug())
           ->setLastChange($product->getUpdatedAt());
       $em->persist($url);
   }
   

3. Multidomain Support Configure multiple sitemaps in config/packages/berriart_sitemap.yaml:

   berriart_sitemap:
       sitemaps:
           main:
               base_url: 'https://example.com'
               filename: 'sitemap.xml'
           blog:
               base_url: 'https://blog.example.com'
               filename: 'blog-sitemap.xml'
   

4. Image Sitemaps Extend SitemapUrl to include images:

   $url->addImage(
       'https://example.com/image.jpg',
       '1000',
       '800',
       'image/jpeg',
       'https://example.com/page'
   );
   

5. Scheduled Generation Use Symfony’s scheduler (or cron) to auto-generate sitemaps:

   0 3 * * * php bin/console berriart:sitemap:generate --env=prod
   

Gotchas and Tips

Pitfalls

1. Unmaintained Status

   • No active maintenance; fork or patch locally if issues arise.
   • Test thoroughly in staging before production.

2. Doctrine Dependency

   • Requires Doctrine ORM (not ODM). Avoid if using MongoDB.
   • Ensure SitemapUrl entity is properly mapped in your App\Entity\SitemapUrl.

3. XML Output Quirks

   • Sitemap URLs must be absolute (e.g., https://example.com/page). Relative paths break validation.
   • Validate output with Google’s Sitemap Tester.

4. Caching Headaches

   • Generated sitemaps aren’t cached by default. Implement a cache layer (e.g., Symfony’s HttpCache) if regeneration is slow:

     # config/packages/framework.yaml
     framework:
         http_cache:
             sitemap:
                 max_age: 3600
                 shared_max_age: 86400
     

Debugging Tips

1. Check Entity Persistence Verify SitemapUrl entities are saved:

   php bin/console doctrine:query:sql "SELECT * FROM sitemap_url"
   

2. Validate XML Use xmllint to debug malformed XML:

   xmllint --noout --valid web/sitemap.xml
   

3. Log Generation Enable debug mode to trace generation:

   php bin/console berriart:sitemap:generate --env=dev -v
   

Extension Points

1. Custom URL Providers Create a service to dynamically fetch URLs (e.g., from an API):

   // src/Service/CustomSitemapProvider.php
   class CustomSitemapProvider implements SitemapUrlProviderInterface
   {
       public function getUrls(): array
       {
           return [
               new SitemapUrl('/dynamic-page', 'https://example.com'),
           ];
       }
   }
   

   Register as a tag:

   services:
       App\Service\CustomSitemapProvider:
           tags: [berriart_sitemap.url_provider]
   

2. Override Templates Customize the XML template by extending the bundle’s SitemapGenerator:

   // src/Sitemap/CustomSitemapGenerator.php
   class CustomSitemapGenerator extends \Berriart\SitemapBundle\Sitemap\SitemapGenerator
   {
       protected function getUrlTemplate(): string
       {
           return '<url><loc>%s</loc><lastmod>%s</lastmod><changefreq>%s</changefreq><priority>%f</priority></url>';
       }
   }
   

   Bind it in services.yaml:

   services:
       Berriart\SitemapBundle\Sitemap\SitemapGenerator:
           class: App\Sitemap\CustomSitemapGenerator
   

3. Add Custom Fields Extend SitemapUrl to include additional fields (e.g., video tags):

   // src/Entity/ExtendedSitemapUrl.php
   class ExtendedSitemapUrl extends SitemapUrl
   {
       private $videoUrl;
       private $videoDuration;
   
       // Getters/setters...
   }
   

   Update the generator to handle new fields.