How Multiple Sitemap Files Are Named When Auto-Split Occurs in PHP Sitemap Generator

When the URL count exceeds the maxUrl limit, the generator automatically appends a sequential index and .xml.gz extension to the base filename, producing names like sitemap1.xml.gz, sitemap2.xml.gz, and so on.

The msbatal/php-sitemap-generator library handles large website crawls by automatically partitioning sitemaps when they exceed size limits. Understanding how multiple sitemap files are named when auto-split occurs is essential for managing SEO assets and verifying that search engines can discover every chunk. The naming logic is hardcoded into the SunSitemap::createSitemap() method and follows a predictable, index-based pattern.

The Auto-Split Naming Convention in SunSitemap.php

The automatic splitting triggers inside SunSitemap::createSitemap() whenever the collected URLs exceed the maxUrl threshold defined during instantiation. The generator stores the original target filename in $this->sitemapFile, which defaults to sitemap.xml. When partitioning occurs, the code iterates over the sitemap chunks and renames each by injecting a 1-based index and forcing a .xml.gz extension.

The String Replacement Logic

Inside the splitting loop at lines 177–184 of SunSitemap.php, the library performs a direct string replacement using str_replace():

for ($i = 0; $i < sizeof($this->sitemaps); $i++) {
    $this->sitemaps[$i] = array(
        str_replace('.xml', ($i + 1) . '.xml.gz', $this->sitemapFile),
        $this->sitemaps[$i]
    );
}

This operation replaces the .xml suffix with the chunk number and .xml.gz, ensuring the first file becomes sitemap1.xml.gz, the second sitemap2.xml.gz, and continues sequentially regardless of total volume.

GZIP Compression and the createZip Flag

Every split file receives the .xml.gz suffix because the naming logic always appends it, regardless of the createZip constructor flag. When createZip is true, the library writes GZIP-compressed data to these files. When false, the files are still named with .gz extensions, but the flag only controls whether an additional uncompressed copy (sitemapX.xml) is created alongside the compressed version.

Generating and Identifying Split Sitemap Files

To force a split and observe the naming convention in action, instantiate SunSitemap with a low maxUrl value and add multiple URLs:

<?php
require 'SunSitemap.php';

// Force split by limiting URLs per file to 2
$sm = new SunSitemap('https://example.com', null, 2, false);

$sm->addUrl('page1.html');
$sm->addUrl('page2.html');
$sm->addUrl('page3.html');
$sm->addUrl('page4.html');

// Generates sitemap1.xml.gz and sitemap2.xml.gz
$sm->createSitemap()->updateRobots();
?>

Executing this code produces a directory structure containing:

• sitemap-index.xml — the index file listing both chunks
• sitemap1.xml.gz — first chunk containing URLs 1–2
• sitemap2.xml.gz — second chunk containing URLs 3–4
• robots.txt — updated with a reference to sitemap-index.xml

How the Sitemap Index References Split Files

The generator produces a master index file named sitemap-index.xml (or the configured index name) that aggregates all split chunks. Each <loc> entry inside this index points directly to the corresponding sitemapX.xml.gz file using the same sequential naming convention. This ensures search engine crawlers can discover and fetch every partitioned sitemap without manual path configuration.

Summary

• The SunSitemap::createSitemap() method in SunSitemap.php handles automatic splitting when URL counts exceed maxUrl.
• Split files are named by replacing .xml with a 1-based index and .xml.gz (e.g., sitemap1.xml.gz, sitemap2.xml.gz).
• The .xml.gz extension is applied to all chunks regardless of the createZip flag, which only controls additional uncompressed copies.
• The sitemap-index.xml file references each chunk using the same naming pattern, maintaining crawler discoverability.

Frequently Asked Questions

What is the default naming pattern for split sitemap files?

The library names the first chunk sitemap1.xml.gz, the second sitemap2.xml.gz, and continues sequentially. It derives these names by replacing the .xml extension in the base filename with the chunk number followed by .xml.gz, as implemented in SunSitemap.php.

Does the createZip flag change how split files are named?

No. The .xml.gz suffix is always appended during the split process. The createZip flag only determines whether an additional uncompressed copy (sitemapX.xml) is created alongside the compressed file, but the primary split files always carry the .gz extension.

Where in the source code is the auto-split naming logic located?

The naming logic is implemented inside the createSitemap() method of SunSitemap.php, specifically within the loop at lines 177–184, where str_replace() transforms the base filename for each chunk by inserting a sequential index.

How does the sitemap index file reference the split chunks?

The generated sitemap-index.xml contains <loc> entries that point to each sitemapX.xml.gz file, using the exact same sequential naming convention produced by the auto-split logic in SunSitemap::createSitemap().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}