XML Sitemap: Extending

Extending the XML sitemap for Sylius 2: custom URL providers for CMS pages or brands, decorating services, the admin page Twig hooks and compatibility notes.

Deutsche Version

Back to overview

XML Sitemap: Extending

This documentation always describes the latest published version.

Sylius itself has no CMS pages and no manufacturers, so there are no built-in providers for them. You add your own URLs with a custom provider.

Custom URL provider

Implement Mmd\SyliusSitemapPlugin\Provider\UrlProviderInterface. With autoconfiguration enabled (the Symfony default), the service is tagged automatically with mmd_sylius_sitemap.url_provider:

use Mmd\SyliusSitemapPlugin\Provider\UrlProviderInterface;
use Mmd\SyliusSitemapPlugin\Sitemap\ChannelContext;
use Mmd\SyliusSitemapPlugin\Sitemap\SitemapUrl;

final class BrandUrlProvider implements UrlProviderInterface
{
    public function getSection(): string
    {
        return 'brands'; // the file is called sitemap-brands-1.xml
    }

    public function supports(ChannelContext $context): bool
    {
        return true;
    }

    public function provide(ChannelContext $context): iterable
    {
        yield new SitemapUrl('https://' . $context->hostname . '/brands/acme');
    }
}

Method	Purpose
`getSection()`	Name of the section. It is part of the file name and consists of lowercase letters, digits and underscores
`supports()`	Whether the provider delivers data for this channel
`provide()`	The URLs as `SitemapUrl`, ideally as a generator so nothing grows in memory

The ChannelContext exposes, among others, hostname, defaultLocale, locales, code and the channel's settings in settings.

Keep in mind:

Every provider writes its own files. Providers that return the same section share its numbering, not a file.
An invalid section name is rejected before the first write, even if the provider is active for no channel.
A URL returned by several providers appears only once in the sitemap, in the file of the first provider.
You can attach hreflang alternates and images to the SitemapUrl itself (Alternate and SitemapImage). For localized routes, Mmd\SyliusSitemapPlugin\Url\LocalizedUrlFactory is a good fit.

Replacing existing parts

To change how an existing part works, decorate the matching service:

Service ID	Purpose
`mmd_sylius_sitemap.provider.product`	Product URLs (section `products`)
`mmd_sylius_sitemap.provider.taxon`	Category URLs (section `categories`)
`mmd_sylius_sitemap.provider.static_route`	Static pages (section `pages`)
`mmd_sylius_sitemap.product_reader`	Reads the products (interface `ProductReaderInterface`)
`mmd_sylius_sitemap.taxon_reader`	Reads the categories (interface `TaxonReaderInterface`)
`mmd_sylius_sitemap.writer`	Writes the XML (interface `SitemapWriterInterface`)
`mmd_sylius_sitemap.storage`	File storage (interface `SitemapStorageInterface`)
`mmd_sylius_sitemap.generation_lock`	Per-channel lock (interface `GenerationLockInterface`)
`mmd_sylius_sitemap.url_builder`	Builds absolute URLs through the router (interface `ChannelUrlBuilderInterface`)
`mmd_sylius_sitemap.image_url_resolver`	Builds image URLs (class `ImageUrlResolver`)
`mmd_sylius_sitemap.generator`	Produces the files of a channel (interface `SitemapGeneratorInterface`)
`mmd_sylius_sitemap.refresher`	Validates, locks and starts the generation (interface `SitemapRefresherInterface`)

The order of the files in the index follows the tag priority: products (30), categories (20), static pages (10). Custom providers without a priority come after them.

Extending the admin page

The settings admin page uses two Twig hooks. Attach your own content or buttons to the same hook names:

Hook	Content
`sylius_admin.sitemap_settings.index.content.header.title_block.actions`	Action bar next to "Create", contains the "Generate now" button
`sylius_admin.sitemap_settings.index.content.header.title_block`	Title block, shows the installed plugin version below the title through the Twig function `sitemap_plugin_version()`

sitemap_plugin_version() returns the plugin version installed by Composer, or dev-main@ plus the short commit hash for an install from a path repository.

Compatibility

The project follows Semantic Versioning. ChannelSettingsFormType and AdminMenuListener are marked @internal: their constructors and internals may change in a minor release and are not part of the extension API. Do not decorate them.