Ali Sitemap Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require aliarteo/ali-sitemap-bundle
   

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

   return [
       // ...
       Aliarteo\AliSitemapBundle\AliSitemapBundle::class => ['all' => true],
   ];
   

3. Create Configuration Generate config/packages/ali_sitemap.yaml with a basic sitemap:

   ali_sitemap:
       sitemaps:
           - slug: "main"
             nodes:
                 - type: "route"
                   route: "homepage"
                   title: "Homepage"
   

4. Generate Sitemaps Run the command to generate sitemaps:

   php bin/console ali:sitemap:generate
   

   Sitemaps will be generated in public/sitemap/.

First Use Case: Static Pages

Define static routes in ali_sitemap.yaml:

ali_sitemap:
    sitemaps:
        - slug: "pages"
          nodes:
              - type: "route"
                route: "app_about"
                title: "About Us"
                priority: 0.8
              - type: "route"
                route: "app_contact"
                title: "Contact"
                priority: 0.6

Implementation Patterns

Workflow: Dynamic Content Sitemaps

1. Entity-Based Nodes Use type: "routes" to dynamically generate URLs from Doctrine entities:

   - slug: "blog"
     nodes:
         - type: "routes"
           entity: "App\Entity\Post"
           route: "app_post_show"
           route_parameters: { slug: "getSlug" }
           title_method: "getTitle"
           lastmod_method: "getUpdatedAt"
           query: { published: true }
           orderBy: { date: DESC }
   

2. Integration with Controllers Render sitemaps in Twig:

   {{ render(controller('AliarteoAliSitemapBundle:Sitemap:render', {'slug': 'blog'})) }}
   

3. Automate Generation Add a cron job or Symfony command to regenerate sitemaps post-deployment:

   php bin/console ali:sitemap:generate --env=prod
   

Patterns for Large Sites

• Split Sitemaps by Entity Use separate sitemaps for products, categories, and articles to avoid hitting URL limits (50,000 URLs per sitemap).
• Paginate Dynamic Nodes Extend the bundle (see Gotchas) to add pagination to type: "routes" nodes.
• Cache Sitemaps Override the SitemapGenerator service to cache generated XML for performance:

  services:
      App\Service\CachedSitemapGenerator:
          decorates: 'ali_sitemap.sitemap_generator'
          arguments: ['@ali_sitemap.sitemap_generator.decorated', '@cache.app']
  

Twig Integration

• Embed Sitemap Links Use the ali_sitemap Twig function to generate links:

  <a href="{{ ali_sitemap('blog') }}">Blog Sitemap</a>
  

• Dynamic Sitemap Index Render the index dynamically in a controller:

  return $this->render('sitemap/index.html.twig', [
      'sitemaps' => $this->get('ali_sitemap.sitemap_index')->getSitemaps(),
  ]);
  

Gotchas and Tips

Common Pitfalls

1. Route Resolution Failures

   • Issue: Routes like app_home may fail if not defined in config/routes.yaml.
   • Fix: Ensure all referenced routes exist and are properly named.
   • Debug: Use php bin/console debug:router to verify route names.

2. Dynamic Node Queries

   • Issue: repository_method defaults to findBy, but complex queries may fail.
   • Fix: Use query_builder for advanced queries (requires bundle extension):

     - type: "routes"
       entity: "App\Entity\Product"
       route: "app_product_show"
       query_builder: "App\Query\ProductSitemapQueryBuilder"
     

3. URL Generation

   • Issue: Absolute URLs may break in development vs. production.
   • Fix: Use generate_url with absolute paths or configure the base URL in ali_sitemap.yaml:

     ali_sitemap:
         base_url: "%env(APP_URL)%"
     

4. XML Validation Errors

   • Issue: Invalid XML (e.g., missing lastmod or priority) may cause parsing errors.
   • Fix: Validate against the sitemap protocol and ensure all required fields are present.

Debugging Tips

• Log Generation Enable debug mode to log sitemap generation:

  ali_sitemap:
      debug: true
  

  Check var/log/dev.log for errors.

• Dry Run Use the --dry-run flag to preview changes without writing files:

  php bin/console ali:sitemap:generate --dry-run
  

Extension Points

1. Custom Node Types Extend the bundle by adding a new node type (e.g., api for GraphQL endpoints):

   // src/NodeType/ApiNodeType.php
   class ApiNodeType extends AbstractNodeType {
       public function buildUrl(NodeInterface $node, UrlGeneratorInterface $urlGenerator): string {
           return $node->getUrl(); // Custom logic for API endpoints
       }
   }
   

   Register in config/services.yaml:

   services:
       App\NodeType\ApiNodeType:
           tags: ['ali_sitemap.node_type']
   

2. Override Templates Customize the XML output by overriding Twig templates:

   • Copy vendor/aliarteo/ali-sitemap-bundle/Resources/views/Sitemap/sitemap.xml.twig to templates/Sitemap/sitemap.xml.twig.
   • Extend the template to add custom fields (e.g., <image:loc> for image sitemaps).

3. Event Listeners Hook into sitemap generation events (e.g., to modify nodes before XML generation):

   // src/EventListener/SitemapListener.php
   class SitemapListener {
       public function onPreGenerate(NodeCollection $nodes) {
           foreach ($nodes as $node) {
               if ($node instanceof RouteNode) {
                   $node->setPriority(1.0); // Force high priority for routes
               }
           }
       }
   }
   

   Register the listener in config/services.yaml:

   services:
       App\EventListener\SitemapListener:
           tags:
               - { name: kernel.event_listener, event: ali_sitemap.pre_generate, method: onPreGenerate }
   

Configuration Quirks

• Default Values

  • default_priority and default_changefreq apply to all nodes unless overridden.
  • Example: Set default_changefreq: "monthly" to avoid specifying it per node.

• Base URL Handling The bundle auto-detects the base URL from Symfony’s Router. For custom domains, explicitly set:

  ali_sitemap:
      base_url: "https://example.com"
  

• robots.txt Integration The bundle auto-generates robots.txt with sitemap links. To disable:

  ali_sitemap:
      generate_robots_txt: false
  

Performance Optimization

• Disable Index Generation For large sites, disable the index to reduce overhead:

  ali_sitemap:
      generate_index: false
  

• Exclude Nodes Conditionally Use a custom node type to filter nodes dynamically (e.g., exclude draft content):

  - type: "filtered_routes"
    entity: "App\Entity\Article"
    route: "app_article_show"
    filter_callback: "App\Filter\PublishedFilter"