Download the PHP package ecourty/sitemap-bundle without Composer

ecourty/sitemap-bundle

A Symfony bundle for generating XML sitemaps. Supports static routes, dynamic Doctrine entities, and extensive configuration options.

The bundle handles both dynamic generation via controller and static file generation via command.
Memory-efficient streaming prevents issues with large datasets.

Table of Contents

• Requirements
• Installation
• Quick Start
• Configuration
  • Use Cases
  • Full Configuration Example
  • Configuration Reference
• Usage
  • Dynamic Generation (Controller)
  • Static Generation (Command)
  • Generated XML Output
• Advanced Configuration
  • Custom Repository Method
  • Custom Service with FQCN::method
  • DQL Conditions
  • Multiple Route Parameters
  • Sitemap Index Modes
• Extensibility
  • Custom URL Providers
  • Use Cases for Custom Providers
• Architecture
• Performance
• Troubleshooting
• Development
• Contributing
• License

Requirements

• PHP 8.3+
• Symfony 6.4+ / 7.0+ / 8.0+
• Doctrine ORM 3.0+ / 4.0+
• Extension: ext-xmlwriter

Installation

The bundle will be automatically registered in config/bundles.php if using Symfony Flex (otherwise, add it manually):

Quick Start

1. Basic Configuration

Create config/packages/sitemap.yaml:

Example: Static routes only

Example: With dynamic entities

2. Import Routes (Optional)

Only required if you want dynamic generation via /sitemap.xml.

If you only use static generation (sitemap:dump command), you can skip this step.

⚠️ Important: Dynamic generation only works for simple sitemaps (single file). If you're using sitemap indexes (use_index: true or above the configured URLs threshold, default to 50k URLs), you must use static generation.

Add the bundle routes to config/routes.yaml:

3. Access Your Sitemap

Dynamic generation - visit in your browser:

Static generation - generate a file:

That's it! 🎉

Configuration

Use Cases

Case 1: Simple Website (Static Pages Only)

Perfect for marketing sites, landing pages, or small websites with fixed pages:

Case 2: Blog or News Site

Static pages + dynamic articles from database:

Case 3: E-commerce Site

Multiple entity types with different priorities:

Case 4: Filtering with DQL Conditions

When you need simple filtering without creating custom repository methods, use conditions:

Note: Use the alias e in your DQL conditions. You cannot combine conditions with query_builder_method.

Case 5: Large Dataset (Automatic Index)

For sites with 50,000+ URLs, the bundle automatically creates a sitemap index:

Full Configuration Example

Configuration Reference

Valid changefreq values: always, hourly, daily, weekly, monthly, yearly, never

Important:

• Cannot use both query_builder_method and conditions simultaneously.
• query_builder_method can be a repository method name (e.g., 'getSitemapQueryBuilder') or a FQCN::method (e.g., 'App\Service\SitemapService::getArticlesQueryBuilder')

Usage

Dynamic Generation (Controller)

Requires routes import - see step 2 in Quick Start.

Once routes are imported, access the dynamic sitemap at:

The sitemap is generated on-the-fly from your configuration and database.

⚠️ Important limitation: Dynamic generation only works for simple sitemaps (single sitemap.xml file). If your configuration generates a sitemap index with multiple files (due to use_index: true or exceeding the threshold), the controller will only serve the main sitemap.xml index file. The individual sitemap files (sitemap_static.xml, sitemap_entity_*.xml) will not be accessible via controller routes.

Recommended for:

• Small to medium sites (< 50,000 URLs)
• Sites needing always up-to-date data
• Simple sitemap configuration (use_index: false)

For sitemap indexes, use static generation instead (see below).

Static Generation (Command)

No routes import needed - works out of the box after configuration.

Generate a static sitemap file:

Important: The --output option specifies a directory, not a file, because the generator may create multiple files:

• For simple sitemaps: sitemap.xml
• For sitemap indexes: sitemap.xml (index) + sitemap_static.xml, sitemap_entity_product.xml, etc.

✅ Recommended for:

• Large sites with many URLs (> 50,000 URLs)
• Sites with infrequent content updates
• SEO-critical sites (serve static files via web server/CDN)
• Any configuration using sitemap indexes (use_index: true or exceeding threshold)

Required for sitemap indexes: Dynamic generation via controller cannot serve individual sitemap files. Use static generation to write all files to disk.

Tip: Run via cron to regenerate periodically:

Generated XML Output

Simple Sitemap (Mixed Content)

When you have both static routes and dynamic entities with use_index: false:

Sitemap Index (Large Datasets)

When use_index: true or URL count exceeds threshold, the bundle generates an index file referencing separate sitemaps per source.

Benefits:

• ✅ Better organization (one file per entity type)
• ✅ Faster incremental updates (regenerate only changed sources)
• ✅ Respects sitemap.org 50,000 URL limit per file
• ✅ Easier debugging and monitoring

sitemap.xml (index file):

sitemap_static.xml (static routes only):

sitemap_entity_article.xml (articles only):

Note: When a source has more than 50,000 URLs, it's automatically split into numbered files (sitemap_entity_product_1.xml, sitemap_entity_product_2.xml, etc.)

Advanced Configuration

Custom Repository Method

For better performance with filtering and optimization, create a custom repository method that returns a QueryBuilder:

Important: Return a QueryBuilder, not the query result. The bundle will:

• Add COUNT() for efficient counting
• Optimize the SELECT to fetch only needed fields
• Use toIterable() for memory-efficient streaming

Then reference it in config:

Custom Service with FQCN::method

For more flexibility, use any service (not just the entity's repository):

Configuration:

DQL Conditions

Use DQL conditions for simple filtering without custom methods:

Multiple Route Parameters

Map multiple entity properties to route parameters:

Sitemap Index Modes

Control how sitemaps are split:

Example with index:

Extensibility

Custom URL Providers

For complex URL generation needs beyond static routes and Doctrine entities, implement a custom UrlProviderInterface.

This is the most powerful extension point in the bundle, giving you complete control over URL generation.

Use Cases for Custom Providers

• Multi-entity relationships: URLs requiring parameters from different entities (e.g., /category/{slug}/product/{id})
• Dynamic routing: Different routes based on entity type or database fields
• External data sources: Generate URLs from APIs, MongoDB, Redis, etc.
• Complex business logic: Custom filtering, permissions, multi-tenancy
• Legacy systems: Integrate with existing URL structures

Implementation Example: Products with Category Parameters

This example shows how to generate URLs like /category/electronics/product/smartphone-x where both category and product slugs are needed:

Configuration:

That's it! The provider will be automatically discovered and used. No additional configuration needed.

Architecture

Design Patterns

• Registry Pattern: UrlProviderRegistry collects all URL providers via tagged services
• Provider Pattern: Each URL source implements UrlProviderInterface
• Strategy Pattern: Index vs single sitemap decision based on configuration
• DTO Pattern: Immutable readonly configuration objects

Extension Points

The bundle is designed for extensibility:

• Custom URL Providers: Implement UrlProviderInterface for any URL source (see Extensibility section)
• Custom Repository Methods: Fine-tune Doctrine queries for entity routes
• Tagged Services: Automatic discovery via sitemap.url_provider tag
• Configuration DTOs: Type-safe configuration objects

Performance

Memory Optimization

The bundle automatically uses Doctrine's toIterable() to stream entities, preventing memory issues with large datasets.

What the bundle does internally:

Your responsibility: Return a QueryBuilder from repository methods (not query results):

Recommendations

1. Use repository methods - The bundle optimizes the SELECT to fetch only needed fields
2. Add database indexes on columns used in WHERE clauses and route parameters
3. Enable sitemap index for datasets >50k URLs (automatic with use_index: 'auto')
4. ⚠️ Use static generation for sitemap indexes - Dynamic controller cannot serve individual sitemap files
5. Run static generation as a cron job during low-traffic periods
6. Use a CDN to cache sitemap files

Example: Optimized for Large Datasets

Result: Can handle millions of products with minimal memory usage.

Development

Development Workflow

Contributions are welcome! The project follows strict coding standards to maintain high code quality.

Setup:

Development cycle:

Before submitting:

• Ensure composer qa passes without errors
• Add tests for the new feature
• Update documentation as needed

Code Standards

All contributions must follow the project's coding standards:

• PHP 8.3+ with declare(strict_types=1) in all files
• PSR-12 code style (enforced by PHP-CS-Fixer)
• PHPStan Level 9 (strict type safety, no mixed types)
• Full test coverage for new features
• Complete PHPDoc blocks with types

See AGENTS.md for detailed developer and AI agent guide.

License

MIT License - see LICENSE file for details.

Support

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Documentation
• 📧 Email: [email protected]