How SunSitemap Splits Large Sitemaps When maxUrl Is Exceeded

SunSitemap automatically chunks URL collections exceeding the maxUrl limit into separate XML files using array_chunk() and generates a <sitemapindex> file to reference each chunk when multiple parts are required.

The msbatal/php-sitemap-generator library provides the SunSitemap class for PHP applications needing standards-compliant XML sitemap generation. When managing large websites that surpass the 50,000 URL per-file limit defined by the sitemap protocol, SunSitemap implements an internal splitting mechanism that distributes URLs across multiple files and creates a master index without manual intervention.

Validating the 50,000 URL Hard Limit

Before processing begins, SunSitemap enforces the XML sitemap specification’s upper boundary. In SunSitemap.php, the constructor validates that the user-defined $maxUrl property does not exceed 50,000:

if ($this->maxUrl > 50000) {
    throw new Exception('Each sitemap file can contain a maximum of 50,000 URLs.');
}

(source → SunSitemap.php L190-L192)

If you attempt to initialize the class with a maxUrl value greater than 50,000, it throws an exception immediately. The default value is set to 50,000, ensuring compliance with search engine standards unless explicitly lowered.

Chunking URLs with array_chunk() in createSitemap()

When createSitemap() is invoked, SunSitemap checks the total number of URLs stored in the private $urls array (populated via addUrl() calls). If the count exceeds $this->maxUrl, the library splits the array into manageable pieces:

foreach (array_chunk($this->urls, $this->maxUrl) as $sitemap) {
    // build one XML file for each $sitemap chunk
}

(source → SunSitemap.php L193-L196)

The array_chunk() function divides $this->urls into sub-arrays, each containing at most $this->maxUrl entries. The method then iterates over these chunks, creating a distinct SimpleXMLElement for each segment.

Generating Separate XML Files and the Sitemap Index

Inside the chunking loop, SunSitemap constructs individual XML documents for each sub-array and stores the resulting strings in $this->sitemaps. Once all chunks are processed, the library determines whether an index file is necessary:

if (sizeof($this->sitemaps) > 1) { /* build index */ }

(source → SunSitemap.php L216-L229)

If multiple sitemap files were generated, SunSitemap automatically constructs a sitemap-index.xml file containing a <sitemapindex> root element. Each chunk receives a sequential filename (e.g., sitemap1.xml.gz, sitemap2.xml.gz, etc.), and the index references these locations using <loc> tags. This ensures search engines can discover and crawl every segment of a large URL collection.

Configuring the Split Behavior

You control the splitting threshold via the maxUrl constructor parameter. The following example initializes SunSitemap with a 20,000 URL limit, adds 75,000 URLs, and triggers automatic file generation:

<?php
require 'SunSitemap.php';

// Initialise with a custom max‑URL limit (e.g., 20 000 per file)
$sitemap = new SunSitemap(
    baseUrl: 'https://example.com',   // optional, defaults to current host
    relPath: 'sitemaps/',             // directory where files will be saved
    maxUrl: 20000,                    // split after 20 000 URLs
    createZip: true                   // also write .gz versions
);

// Add many URLs (could be thousands)
for ($i = 1; $i <= 75000; $i++) {
    $sitemap->addUrl("page{$i}.html");
}

// Build the sitemap files and index automatically
$sitemap->createSitemap()
        ->updateRobots();   // optional: creates /sitemaps/robots.txt

echo "Done. Generated " . count($sitemap->sitemaps) . " sitemap files.\n";
?>

What happens internally

• The addUrl() calls fill $sitemap->urls with 75,000 entries.
• createSitemap() detects maxUrl = 20000 and uses array_chunk() to create four chunks (20,000, 20,000, 20,000, and 15,000 URLs).
• Four XML files are written to disk (optionally gzipped), and because sizeof($this->sitemaps) > 1, a sitemap-index.xml is created referencing each chunk.

Summary

• SunSitemap enforces a hard limit of 50,000 URLs per file, throwing an exception if maxUrl exceeds this value in SunSitemap.php (lines 190-192).
• The createSitemap() method uses PHP’s array_chunk() to divide the internal $urls array into segments sized according to the maxUrl property.
• Each chunk generates a separate XML file stored in $this->sitemaps, with sequential naming like sitemap1.xml.gz for secondary files.
• When multiple chunks exist, SunSitemap automatically produces a sitemap-index.xml file containing <sitemapindex> entries pointing to each chunk.
• The library supports Gzip compression and custom base URLs, handling both file generation and optional robots.txt updates via method chaining.

Frequently Asked Questions

What is the maximum number of URLs SunSitemap allows per file?

SunSitemap enforces a hard limit of 50,000 URLs per sitemap file, matching the XML sitemap protocol specification. If you attempt to set maxUrl higher than 50,000 in the constructor, the library throws an exception immediately (source: SunSitemap.php, lines 190-192).

How does SunSitemap determine when to create a sitemap index?

SunSitemap checks the size of the $sitemaps array after processing all chunks. If sizeof($this->sitemaps) > 1, indicating multiple files were generated, it automatically builds a sitemap-index.xml file that references each individual sitemap chunk using <sitemapindex> and <loc> elements (source: SunSitemap.php, lines 216-229).

Can I customize the number of URLs per sitemap file?

Yes, you can specify a custom maxUrl value via the constructor (default is 50,000). For example, setting maxUrl: 20000 splits a 75,000 URL collection into four separate files (20,000 + 20,000 + 20,000 + 15,000 URLs respectively), with each file receiving its own XML document.

What file naming convention does SunSitemap use for split sitemaps?

SunSitemap generates sequential filenames for additional chunks, such as sitemap1.xml.gz, sitemap2.xml.gz, etc., while the first chunk typically uses sitemap.xml.gz (or .xml if compression is disabled). The index file references these relative paths based on the configured relPath directory.

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