Sitemap Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and publish any config with php artisan vendor:publish --tag=<package>-config if the package provides one.
• Check the package README and config file first: the 0.2.0 feature is route-level sitemap metadata, so the important surface area is how routes declare frequency and priority.
• Start with the smallest possible use case: add sitemap metadata to one or two existing routes, generate the sitemap, and inspect the XML output before rolling it out to every route.

Typical first use:

Route::get('/about', AboutController::class)
    ->name('about')
    ->sitemap(frequency: 'monthly', priority: 0.5);

Then generate the sitemap using the package’s artisan command or generator API, for example:

php artisan sitemap:generate

Verify the generated file contains the expected <url>, <changefreq>, and <priority> entries, and that the URLs are absolute rather than relative.

Implementation Patterns

• Opt-in per route: Only attach sitemap metadata to routes that should appear in the sitemap. Keep public, indexable pages explicit rather than trying to infer inclusion from all routes.
• Grouped defaults: If the package supports route groups or defaults, apply sensible defaults for sections such as blog, docs, or marketing pages, then override exceptions per route.
• Dynamic model routes: For resource routes, generate URLs from models and set priority/frequency based on content type. For example, index pages at 1.0, detail pages at 0.8, and archive pages at 0.4.
• Scheduled generation: Generate the sitemap in a scheduled command after content updates or on a nightly cadence, then write it to public/sitemap.xml or object storage.
• Cache-aware generation: If routes are cached in production, confirm the package reads route metadata correctly after php artisan route:cache. Clear and rebuild route caches as part of deployment.
• Multi-sitemap layouts: If the package supports sitemap indexes, split large sites by section (blog, products, docs) and reference them from a sitemap index.
• Robots integration: Point robots.txt at the generated sitemap URL, and ensure the sitemap URL itself is not blocked by middleware or auth.
• Testing: Add a feature test that generates the sitemap and asserts expected URLs, frequencies, and priorities are present.

Example with dynamic priorities:

Route::get('/posts/{post}', [PostController::class, 'show'])
    ->name('posts.show')
    ->sitemap(
        frequency: 'weekly',
        priority: fn ($post) => $post->isFeatured() ? 0.9 : 0.6
    );

Gotchas and Tips

• Route cache quirks: Route-level metadata can be lost or stale after route:cache. Always test sitemap generation against a production-like cached route table.
• Absolute URLs: Sitemap entries must be absolute URLs. Check APP_URL, proxy headers, and trusted proxies so generated links use the correct scheme and host.
• Frequency values: Sitemap changefreq values are constrained (always, hourly, daily, weekly, monthly, yearly, never). Validate or constrain values to avoid invalid XML.
• Priority range: priority should be between 0.0 and 1.0. Avoid treating it as a ranking guarantee; search engines treat it as a hint at best.
• Duplicate routes: Named routes, redirects, and routes with multiple URIs can produce duplicate sitemap entries. Deduplicate where necessary.
• Excluded routes: Do not sitemap authenticated, admin, API, or preview routes. Prefer an explicit allow-list over a broad exclude-list.
• Large sites: Generating thousands of URLs in one process can hit memory limits. Use chunking, sitemap indexes, or queued generation if supported.
• Static files and caching: If writing to public/sitemap.xml, ensure deploy scripts and web servers do not serve a stale file. Regenerate during deployment or via a scheduled job.
• Debugging: Inspect the generated XML directly, then compare it with php artisan route:list to confirm which routes carry sitemap metadata.
• Extension points: Look for custom generators, route macros, or config-driven URL providers if the package supports them. These are preferable to forking when adding non-route URLs such as CMS pages.