Mity Docs Mity Docs for Mity Digital
Sitemapamic Documentation

Cache

Building a sitemap means reading every entry and term on your site, so Sitemapamic caches the result. The cache option in config/sitemapamic.php controls how.

1'cache' => [
2 'enabled' => env('SITEMAPAMIC_CACHE_ENABLED', true),
3 
4 'key' => 'sitemapamic',
5 
6 'ttl' => env('SITEMAPAMIC_CACHE_TTL'),
7 
8 'disk' => env('SITEMAPAMIC_CACHE_DISK', 'local'),
9],

Option

Default

Description

enabled

true

Whether to cache the sitemap.

key

sitemapamic

The prefix for Sitemapamic's cache keys, and the folder its files are stored in on the disk.

ttl

null

How long a built sitemap lasts, in seconds. null keeps it until your content changes.

disk

local

The filesystem disk the sitemap files are stored on.

How caching works

The sitemap is built the first time it is requested, not when content is saved.

  • The XML files are written to the disk, under {key}/{site}/.

  • A small manifest of those files is kept in your app's default cache store.

  • Later requests stream the files straight from the disk, so even very large sitemaps use little memory.

Each site has its own cache, so saving content on one site only rebuilds the sitemaps that need it.

Automatic invalidation

Sitemapamic listens for Statamic events and marks the sitemap stale when your content changes. That includes saving or deleting:

  • entries, or an entry's scheduled date being reached

  • Collections and their trees (structure)

  • Taxonomies and terms

  • sites

An entry only marks its own Collection's sites stale. Everything else marks every site stale.

Changing config/sitemapamic.php rebuilds the sitemap on the next request too, so you don't need to clear the cache after changing your configuration.

Stale sitemaps keep being served

A stale sitemap is not deleted. The next request rebuilds it, and any requests that arrive during the rebuild are served the previous version. The new version replaces it only once it is complete.

If content changes while the sitemap is being built, the build runs again so the new content isn't missed.

When there is no previous version yet, such as the very first request, a request waits up to 10 seconds for a build already in progress. If it is still building, Sitemapamic responds with a 503 and a Retry-After header, which search engines will retry.

Cache lifetime

ttl sets how long a built sitemap lasts, in seconds. After that, it is treated as stale and rebuilt on the next request, in the same way as a content change.

1SITEMAPAMIC_CACHE_TTL=86400

You don't need a ttl for Statamic content, because content changes are tracked automatically. It is useful when your sitemap includes Dynamic Routes built from data Statamic doesn't know about.

Choosing a disk

The default local disk suits a site on a single server.

If your site runs on more than one server, or on a platform with an ephemeral filesystem, use a disk every server can read, such as S3. Your app's default cache store must be shared between servers too, such as Redis or a database.

1SITEMAPAMIC_CACHE_DISK=s3

Builds use your cache store's atomic locks so only one request builds a site's sitemap at a time. Every cache driver that ships with Laravel supports them.

The cache key

Change key if more than one app shares the same cache store or disk, so their sitemaps don't overwrite each other:

1'key' => 'sitemapamic-marketing',

Clearing the cache

You rarely need to clear the cache yourself. When you do, use the command:

1php please sitemapamic:clear
2php please sitemapamic:clear --site=default

Or the facade:

1use MityDigital\Sitemapamic\Facades\Sitemapamic;
2 
3Sitemapamic::clearCache(); // every site
4Sitemapamic::clearCache('default'); // one site

Clearing deletes the cached files immediately, so the next request has to wait for a fresh build. To rebuild without that wait, mark the sitemap stale instead. The previous version keeps being served until the new one is ready:

1Sitemapamic::markStale(); // every site
2Sitemapamic::markStale('default'); // one site

Scheduled entries

Statamic fires an event when a scheduled entry's date is reached, and Sitemapamic marks that entry's sites stale.

If you also use our Scheduled Cache Invalidator addon, Sitemapamic listens for its event too, and marks the sites of the Collections it names stale. No configuration is needed: install the addon and it just works.

A full list of events is available in Clearing the Sitemap.

Disabling the cache

Set SITEMAPAMIC_CACHE_ENABLED=false to build the sitemap on every request. Nothing is written to the cache store or disk.

1SITEMAPAMIC_CACHE_ENABLED=false

This can help while developing, but isn't recommended in production: every request reads all of your content.

When the cache fails

If the cache store or disk can't be read or written, Sitemapamic reports the exception and builds that response without the cache, so your sitemap is still served.