spatie/laravel-sitemap

When upgrading to version 8.0, ensure your environment meets the new requirements and update your implementation of crawler callbacks and configuration files due to breaking changes in the underlying spatie/crawler dependency.

# Upgrade Requirements
- PHP 8.4 or higher
- Laravel 12 or higher

To discover links generated by JavaScript scripts, you must enable execute_javascript in your config/sitemap.php and install the spatie/browsershot package via Composer.

composer require spatie/browsershot

Use SitemapIndex::create() to generate a sitemap index file. You can add sitemaps by passing their URL strings to the add() method, or by passing Spatie\Sitemap\Tags\Sitemap objects to include specific metadata like the last modification date. Finally, use writeToFile() to save the index to a file path.

use Spatie\Sitemap\SitemapIndex;

SitemapIndex::create()
    ->add('/pages_sitemap.xml')
    ->add('/posts_sitemap.xml')
    ->writeToFile($sitemapIndexPath);

To discover links generated by JavaScript, you must enable JavaScript execution.

1. Install spatie/browsershot via composer:

composer require spatie/browsershot

2. Ensure headless Chrome is installed on your system.
3. Set execute_javascript to true in your config/sitemap.php file.

You can also manually set the Chrome path in config/sitemap.php if the package cannot locate it automatically.

To make your sitemaps human-readable in web browsers, you can add an XSL stylesheet processing instruction. Use the setStylesheet() method on either a Sitemap or SitemapIndex instance. Pass the path to your XSL file as a string (e.g., '/sitemap.xsl').

If you use maxTagsPerSitemap on a Sitemap that has a stylesheet set, the stylesheet will automatically be propagated to both the generated sitemap index and all resulting chunk sitemaps.

use Spatie\
Sitemap\Sitemap;
use Spatie\Sitemap\SitemapIndex;

// For a single sitemap
Sitemap::create()
    ->setStylesheet('/sitemap.xsl')
    ->add('/page1')
    ->writeToFile($sitemapPath);

// For a sitemap index
SitemapIndex::create()
    ->setStylesheet('/sitemap-index.xsl')
    ->add('/pages_sitemap.xml')
    ->writeToFile($sitemapIndexPath);

To prevent a link that has already been discovered by the crawler from appearing in your final sitemap, use the hasCrawled method. Pass a callable that receives a Spatie\Sitemap\Tags\Url object. If the callable returns nothing (or null), the URL will be excluded from the sitemap. If it returns the Url object, it will be included.

use Spatie\Sitemap\SitemapGenerator;
use Spatie\Sitemap\Tags\Url;

SitemapGenerator::create('https://example.com')
    ->hasCrawled(function (Url $url) {
        if ($url->segment(1) === 'contact') {
            return;
        }

        return $url;
    })
    ->writeToFile($sitemapPath);

You can also write a SitemapIndex instance to a filesystem disk using the writeToDisk method.

use Spatie\Sitemap\SitemapIndex;

SitemapIndex::create()
    ->add('/pages_sitemap.xml')
    ->add('/posts_sitemap.xml')
    ->writeToDisk('public', 'sitemap.xml');

Use the sort() method to arrange all URLs in your sitemap in alphabetical order. This ensures a consistent order in your sitemap files regardless of the order in which URLs were added.

use Spatie\Sitemap\Sitemap;

$sitemap = Sitemap::create()
    ->add('/zoo')
    ->add('/blog')
    ->add('/about')
    ->add('/contact')
    ->sort();

When using writeToFile to group URLs and maxTagsPerSitemap to limit file size, any group that exceeds the maximum tag limit will be automatically split into numbered files (e.g., sitemap-blog_0.xml, sitemap-blog_1.xml). These split chunks will all be correctly listed in the sitemap index generated by sitemapIndexPath().

SitemapGenerator::create('https://example.com')
    ->maxTagsPerSitemap(20000)
    ->sitemapIndexPath(public_path('sitemap.xml'))
    ->writeToFile(fn (Url $url) => str_starts_with($url->path(), '/blog')
        ? public_path('sitemap-blog.xml')
        : public_path('sitemap-pages.xml'));

If you need to include specific URLs that the crawler might miss, you can access the underlying sitemap instance using getSitemap() after creating the generator. Use the add() method along with Spatie\Sitemap\Tags\Url::create() to append manual links before writing the file to disk.

use Spatie\Sitemap\SitemapGenerator;
use Spatie\Sitemap\Tags\Url;

SitemapGenerator::create('https://example.com')
    ->getSitemap()
    ->add(Url::create('/extra-page'))
    ->add(Url::create('/another-extra-page'))
    ->writeToFile($sitemapPath);