Sitemap Bundle Laravel Package

Getting Started

1. Require the package with Composer and publish its config file (php artisan vendor:publish), then open the published config — the dumper setting is the single most important knob in the package and the first thing to look at.
2. Read the two shipped dumper implementations (FileDumper, GzFileDumper) before anything else; they define the on-disk format of the generated index files and therefore everything downstream of them.
3. Check where index files are written (the configured output path) and confirm the directory is writable and git-ignored.
4. First use case: run the index build for the default (or a tiny) dataset, then ls -al the output directory to see exactly what was produced — filenames and extensions matter as much as contents.

Note for v1.0.1: the default dumper is now FileDumper (plain files). Prior to this patch it was GzFileDumper (gzipped), which produced incorrectly named index files. New installs get plain files; the default is scheduled to flip back in the next MAJOR release.

Implementation Patterns

• Pin the dumper explicitly. Don't rely on the package default, because the default is already scheduled to change in the next major. Set the dumper class in the published config (or in a service provider via the package's binding) so behaviour is identical across upgrades.
• Per-environment dumpers. A common split: GzFileDumper in production (smaller artefacts to ship/upload), FileDumper locally (readable, easy to cat/diff when debugging index contents).
• Deploy-time builds. Generate the index in a deploy hook or CI job rather than on a web request; treat the output directory as a build artefact and replace it atomically to avoid serving a half-written index.
• Shared storage. In zero-downtime deploys, make sure each release points at the same storage path (symlinked storage/) or the index rebuilt in release N is invisible to release N-1.
• Custom dumpers. If you need object storage, encryption, or a different compression scheme, implement the package's dumper contract and register your class in the config — this is the intended extension point.
• Tests. Assert on the presence and naming of index files rather than hardcoding .gz; assert the resolved dumper class via config() so an accidental default flip fails the build.

Gotchas and Tips

• v1.0.1 is a behaviour change hiding in a patch release. Anyone relying on the package default silently moves from gzipped to plain index files on composer update. If you were on GzFileDumper and produced misnamed files, delete the index directory and rebuild — stale entries can fail to resolve silently rather than erroring.
• Published config beats the package default. If config/<package>.php explicitly names GzFileDumper::class (which it will if you published it before v1.0.1), you keep the old behaviour and the old filename bug until you change it yourself.
• Clear the config cache (php artisan config:cache) after changing the dumper; otherwise you'll debug a setting that isn't in effect.
• Watch disk usage. Uncompressed index files can be several times larger; check storage quotas and monitoring before rolling this to production.
• Plan for the revert. The default returns to GzFileDumper in the next major. Constrain the requirement to ^1.0 if you want stability, or — better — set the dumper explicitly so the flip is a no-op for you.
• Debugging tip: when output looks wrong, log both the resolved dumper class and a directory listing of the output path; the class tells you the intended format, the listing tells you the actual filename bug is or isn't present.