README

Laravel Sitemap Generator

A Laravel package for generating and managing XML sitemaps with caching and cooldown periods. This package provides an easy way to generate and maintain sitemaps for your Laravel applications while preventing excessive generation requests.

Requirements

• PHP 8.4+
• Laravel 13+

Features

• Automatic sitemap generation with configurable cooldown periods
• Sitemap Index Support - Split large sitemaps into multiple files (50,000 URLs per file)
• Model-Based Generation - Generate sitemaps from Eloquent models (faster, includes authenticated content)
• Hybrid Mode - Combine crawled URLs with model-based URLs
• Caching of sitemap content for improved performance
• Environment-aware generation (skips generation in local environment)
• Force regeneration capability when needed
• Built on top of the popular spatie/laravel-sitemap package
• Automatic scheduling of sitemap generation
• Storage-based sitemap management for better control

Installation

You can install the package via composer:

composer require daikazu/sitemap

You can publish the config file with:

php artisan vendor:publish --tag="sitemap-config"

This is a summary of the published config file (see the full file for all options and documentation):

return [
    'cooldown_hours' => env('SITEMAP_COOLDOWN_HOURS', 24),

    'storage' => [
        'disk' => env('SITEMAP_STORAGE_DISK', 'public'),
        'path' => env('SITEMAP_STORAGE_PATH', 'sitemaps'),
        'filename' => env('SITEMAP_FILENAME', 'sitemap.xml'),
    ],

    'schedule' => [
        'enabled' => env('SITEMAP_SCHEDULE_ENABLED', true),
        'daily_time' => env('SITEMAP_DAILY_TIME', '00:00'),
    ],

    'skip_patterns' => [
        '/login', '/logout', '/register', '/admin', '/cart', '/checkout',
        // ... see config file for full list
    ],

    'index' => [
        'enabled' => env('SITEMAP_INDEX_ENABLED', false),
        'max_urls_per_sitemap' => env('SITEMAP_MAX_URLS', 50000),
        'filename_pattern' => env('SITEMAP_FILENAME_PATTERN', 'sitemap-%d.xml'),
        'index_filename' => env('SITEMAP_INDEX_FILENAME', 'sitemap.xml'),
    ],

    'models' => [
        // See "Model-Based Sitemap Generation" section below
    ],

    'generate_mode' => env('SITEMAP_GENERATE_MODE', 'crawl'), // 'crawl', 'models', or 'hybrid'

    'max_pagination_depth' => env('SITEMAP_MAX_PAGINATION_DEPTH', 100),
];

Usage

The package provides a SitemapService that handles sitemap generation and caching:

use Daikazu\Sitemap\Services\SitemapService;

$sitemapService = app(SitemapService::class);

// Generate sitemap if due (respects cooldown period)
$sitemapService->generateIfDue();

// Force regenerate sitemap regardless of cooldown
$sitemapService->forceRegenerate();

// Get the sitemap content (returns null if generation fails)
$sitemapContent = $sitemapService->getSitemapContent();

The package automatically handles scheduling of sitemap generation based on your configuration settings. You can customize the scheduling behavior through the config file.

Artisan Commands

# Generate sitemap with configured mode (crawl/models/hybrid)
php artisan app:generate-sitemap

# Generate sitemap from models only (ignores generate_mode)
php artisan app:generate-model-sitemap

# Force regenerate the sitemap (bypasses cooldown)
php artisan app:regenerate-sitemap

# Clear all generated sitemaps and reset cache
php artisan app:clear-sitemap

Sitemap Index (Multi-Sitemap) Support

For large sites with more than 50,000 URLs, enable sitemap index support:

// In config/sitemap.php
'index' => [
    'enabled' => true,
    'max_urls_per_sitemap' => 50000,
    'filename_pattern' => 'sitemap-%d.xml',
    'index_filename' => 'sitemap.xml',
],

When enabled, the package will:

• Split your sitemap into multiple files (sitemap-1.xml, sitemap-2.xml, etc.)
• Generate a sitemap index (sitemap.xml) that references all individual sitemaps
• Automatically serve the correct sitemap based on the requested URL

The main sitemap index will be available at /sitemap.xml, and individual sitemaps at /sitemaps/sitemap-1.xml, /sitemaps/sitemap-2.xml, etc.

Model-Based Sitemap Generation

Generate sitemaps directly from your Eloquent models - much faster than crawling and includes dynamic/authenticated content:

// In config/sitemap.php
'models' => [
    \App\Models\Post::class => [
        'enabled' => true,
        'url' => fn($post) => route('posts.show', $post->slug),
        'lastmod' => 'updated_at', // column name or closure
        'changefreq' => 'weekly',
        'priority' => 0.8, // or use closure: fn($post) => $post->is_featured ? 0.9 : 0.7
        'query' => fn($query) => $query->where('published', true),
    ],
    \App\Models\Product::class => [
        'enabled' => true,
        'url' => fn($product) => route('products.show', $product),
        'lastmod' => fn($product) => $product->updated_at,
        'priority' => fn($product) => $product->in_stock ? 0.8 : 0.5,
    ],
],

// Set generation mode
'generate_mode' => 'hybrid', // Options: 'crawl', 'models', or 'hybrid'

Generation Modes:

• crawl - Traditional website crawling (default)
• models - Only generate from configured models
• hybrid - Combine both crawled pages and model-based URLs (with automatic deduplication)

Hybrid Mode Deduplication: When using hybrid mode, the package intelligently prevents duplicate URLs by:

• Tracking all model-generated URLs
• Normalizing URLs (removes trailing slashes, tracking parameters, case differences)
• Skipping crawled URLs that were already added from models
• Result: Clean sitemap with no duplicates, combining the best of both approaches!

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mike Wall
• All Contributors

License

The MIT License (MIT). Please see License File for more information.