SunSitemap Constructor-Level Exception Handling: How the PHP Class Manages Initialization Errors

SunSitemap registers a custom exception handler inside its constructor and throws validation exceptions when initialization parameters are invalid.

The SunSitemap class in the msbatal/php-sitemap-generator repository implements robust error management directly within its constructor. This constructor-level exception handling ensures that invalid directory paths are rejected immediately while providing a consistent formatting mechanism for any uncaught errors during object lifecycle.

How SunSitemap Implements Constructor-Level Exception Handling

The constructor in SunSitemap.php combines proactive validation with a fallback error handler to guarantee that initialization failures are surfaced clearly to the developer.

Exception Handler Registration

Inside the constructor at lines 111-115, the class calls set_exception_handler() with an inline closure. This closure formats any uncaught exception as a bold "SunClass" message, ensuring that exceptions raised during object instantiation—or any subsequent operation—are caught and displayed uniformly regardless of whether they are caught by user code.

Validation Exceptions

The constructor performs strict validation of the $relPath parameter before completing instantiation. If a relative path is supplied but the target directory does not exist, the constructor immediately throws an Exception with the message "Sitemap path … does not valid" (lines 121-125).

The constructor also accepts optional $maxUrl and $createZip parameters. These are applied silently when they match the expected type, with the constructor deferring additional validation logic to other methods within the class.

Practical Examples

These examples demonstrate the constructor-level exception handling patterns available when working with SunSitemap.

Successful Instantiation

When valid parameters are provided, the constructor completes without throwing exceptions:

require 'SunSitemap.php';

$sm = new SunSitemap(
    'https://example.com',   // base URL
    'sitemaps/',             // relative path (must exist)
    30000,                   // max URLs per file
    true                     // create gzipped copy
);

Catching Constructor Exceptions

Wrap instantiation in a try-catch block to handle validation failures programmatically while still allowing the internal handler to format the output:

require 'SunSitemap.php';

try {
    // Provide a non-existent path → constructor throws an Exception
    $sm = new SunSitemap('https://example.com', 'nonexistent/path/');
} catch (Exception $e) {
    // The custom handler also prints a formatted message,
    // but catching here lets you react programmatically.
    echo "Caught during construction: " . $e->getMessage();
}

Using the Internal Exception Handler

If you do not wrap the constructor in try-catch logic, the registered handler displays bold-formatted error text automatically:

require 'SunSitemap.php';

// No try/catch – the internal handler will output a bold message.
$sm = new SunSitemap('https://example.com', 'invalid/../path/');

Source Code Reference

The exception handling logic resides entirely within the core class file:

• SunSitemap.php – Lines 111-115 implement the custom exception handler registration using set_exception_handler(), while lines 121-125 contain the directory existence validation that throws construction-time exceptions.

Additional reference implementations are available in the repository's test suite, where test/SunSitemap.php exercises error paths and test/index.php demonstrates typical initialization flows.

Summary

• Constructor handler registration: The SunSitemap constructor immediately calls set_exception_handler() with a custom closure to ensure consistent error formatting for uncaught exceptions.
• Path validation: Invalid relative paths trigger an Exception with the message "Sitemap path … does not valid" before the object completes instantiation (lines 121-125).
• Dual error management: The class combines proactive throw statements with a fallback handler to cover both programmatically caught and uncaught exception scenarios.
• Optional parameter handling: The $maxUrl and $createZip parameters bypass strict constructor validation, deferring type checking to subsequent method calls.

Frequently Asked Questions

Can I disable the custom exception handler in SunSitemap?

No, the set_exception_handler() call is hardcoded in the constructor at lines 111-115 of SunSitemap.php. To implement alternative error handling, you must either modify the source code or call restore_exception_handler() immediately after instantiation to revert to the previous handler.

What happens if I provide a relative path that doesn't exist?

The constructor throws an Exception with the message "Sitemap path … does not valid" (lines 121-125). You can catch this using a try-catch block around the new SunSitemap() call, or allow the internal handler to format the error as bold text in the output buffer.

Does SunSitemap validate the $maxUrl and $createZip parameters in the constructor?

No, these optional parameters are silently accepted when they match the expected type. The constructor focuses its exception handling on directory path validation, leaving detailed validation of numeric limits and boolean flags to other methods within the class implementation.

Where is the exception handler logic located in the source code?

According to the msbatal/php-sitemap-generator repository, the custom exception handler is registered in SunSitemap.php at lines 111-115, while the validation exception for invalid paths is thrown at lines 121-125.

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