fix(parser): stop swallowing validation errors

[danielebarbaro]

Four related defects in KmlParser::loadFromString() and KmlValidator, all in the same few lines, so they are fixed together.

1. Validation errors lose their type

loadFromString() wrapped its entire body in catch (\Exception) and rethrew everything through KmlParserException::failedToParse():

try {
    $this->validator->validate($content);
    // ...
} catch (\Exception $e) {
    libxml_clear_errors();
    throw KmlParserException::failedToParse($e->getMessage());
}

A KmlException raised by the validator ("Invalid longitude value: 181", "Missing required element: Document") arrived at the caller as KmlParserException: Failed to parse KML content: .... The original message survived inside the string, but the type did not, so there is no way to distinguish "this file is not XML" from "this file is XML but the coordinates are out of range" other than substring matching on the message.

Validation exceptions now propagate untouched.

2. invalidXml() was unreachable

$errors = libxml_get_errors();
if ($errors) {
    throw KmlParserException::invalidXml($errorMessage);
}

new SimpleXMLElement($content) throws on malformed input, so execution never reached the libxml_get_errors() check. And if it somehow had, the catch (\Exception) two lines below would have caught the invalidXml exception and re-wrapped it as failedToParse. Dead in two independent ways.

invalidXml() is now what malformed XML actually throws, which is what its name always claimed.

3. Everything was parsed twice

KmlValidator::validate() built a SimpleXMLElement, threw it away, and then loadFromString() built a second one from the same string. Double the CPU and double the peak memory on every single load.

KmlValidator gained validateDocument(SimpleXMLElement $xml), which validates an already parsed document. KmlParser parses once and passes the result. validate(string $content) keeps its existing signature and delegates, so direct users of the validator are unaffected.

4. Global libxml state was never restored

Both classes called libxml_use_internal_errors(true) and never put it back. That is process-global: after one KML parse, every other library in the application using libxml (DOM, XMLReader, an XML HTTP client) silently stopped emitting warnings for the rest of the request.

The previous value is now captured and restored in a finally, on the success and the failure path.

Breaking change

Malformed XML previously threw:

KmlParserException: Failed to parse KML content: String could not be parsed as XML

and now throws:

KmlParserException: XML parsing error: String could not be parsed as XML

Still KmlParserException, different message prefix. Anything matching on the old string needs updating. tests/ExceptionsTest.php is updated accordingly.

Validation failures previously threw KmlParserException and now throw the underlying KmlException. Since KmlParserException extends KmlException, any catch (KmlException) keeps working; a catch (KmlParserException) around a validation failure does not. That is the point of the fix, but it belongs in the changelog.

KmlParserException::failedToParse() is no longer thrown by anything. Marked @deprecated rather than deleted, so callers referencing it keep working for one cycle.

Tests

tests/ParsingErrorsTest.php, all five failing on main:

• a validation failure arrives as KmlException, not KmlParserException, with its own unwrapped message
• malformed XML arrives as KmlParserException prefixed XML parsing error:
• the libxml error mode is restored after a successful load
• the libxml error mode is restored after a failed load
• validateDocument() validates a pre-parsed document

Pint and PHPStan clean.