From fb1fe70cf855eb53440995a8580c5ef75a514659 Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sun, 15 Nov 2026 15:00:32 +0100 Subject: [PATCH 01/10] Use PHP 8.4+ \Dom classes and functions https://wiki.php.net/rfc/domdocument_html5_parser https://wiki.php.net/rfc/opt_in_dom_spec_compliance --- composer.json | 3 +- src/Locator.php | 46 ++++------ src/Parser.php | 11 +-- src/Sanitize.php | 178 ++++++++++++++++++------------------- src/SimplePie.php | 11 +-- tests/LocatorTest.php | 12 +-- tests/SanitizeTest.php | 2 +- tests/Unit/LocatorTest.php | 14 ++- 8 files changed, 134 insertions(+), 143 deletions(-) diff --git a/composer.json b/composer.json index 2869c4969..c25e8a682 100644 --- a/composer.json +++ b/composer.json @@ -24,7 +24,8 @@ } ], "require": { - "php": ">=7.4.0", + "php": ">=8.4.0", + "ext-dom": "*", "ext-pcre": "*", "ext-xml": "*", "ext-xmlreader": "*" diff --git a/src/Locator.php b/src/Locator.php index 10491db5d..199972108 100644 --- a/src/Locator.php +++ b/src/Locator.php @@ -7,7 +7,6 @@ namespace SimplePie; -use DomDocument; use Psr\Http\Client\ClientInterface; use Psr\Http\Message\RequestFactoryInterface; use Psr\Http\Message\UriFactoryInterface; @@ -51,7 +50,7 @@ class Locator implements RegistryAware public $force_fsockopen; /** @var array */ public $curl_options; - /** @var ?\DomDocument */ + /** @var ?\Dom\HTMLDocument */ public $dom; /** @var ?Registry */ protected $registry; @@ -75,18 +74,13 @@ public function __construct(File $file, int $timeout = 10, ?string $useragent = $body = $this->file->get_body_content(); - if (class_exists('DOMDocument') && $body != '') { - $this->dom = new \DOMDocument(); - - set_error_handler([Misc::class, 'silence_errors']); + if ($body != '') { + // NB: Unlike with the legacy DOM API, parsing never fails, but invalid UTF-8 fails gracefully try { - $this->dom->loadHTML($body); + $this->dom = \Dom\HTMLDocument::createFromString($body, LIBXML_NOERROR | \Dom\HTML_NO_DEFAULT_NS); } catch (\Throwable $ex) { $this->dom = null; } - restore_error_handler(); - } else { - $this->dom = null; } } @@ -200,7 +194,7 @@ public function get_base() $elements = $this->dom->getElementsByTagName('base'); foreach ($elements as $element) { if ($element->hasAttribute('href')) { - $base = $this->registry->call(Misc::class, 'absolutize_url', [trim($element->getAttribute('href')), $this->http_base]); + $base = $this->registry->call(Misc::class, 'absolutize_url', [trim($element->getAttribute('href') ?? ''), $this->http_base]); if ($base === false) { continue; } @@ -248,19 +242,19 @@ protected function search_elements_by_tag(string $name, array &$done, array $fee break; } if ($link->hasAttribute('href') && $link->hasAttribute('rel')) { - $rel = array_unique($this->registry->call(Misc::class, 'space_separated_tokens', [strtolower($link->getAttribute('rel'))])); + $rel = array_unique($this->registry->call(Misc::class, 'space_separated_tokens', [strtolower($link->getAttribute('rel') ?? '')])); $line = $link->getLineNo(); if ($this->base_location < $line) { - $href = $this->registry->call(Misc::class, 'absolutize_url', [trim($link->getAttribute('href')), $this->base]); + $href = $this->registry->call(Misc::class, 'absolutize_url', [trim($link->getAttribute('href') ?? ''), $this->base]); } else { - $href = $this->registry->call(Misc::class, 'absolutize_url', [trim($link->getAttribute('href')), $this->http_base]); + $href = $this->registry->call(Misc::class, 'absolutize_url', [trim($link->getAttribute('href') ?? ''), $this->http_base]); } if ($href === false) { continue; } - if (!in_array($href, $done) && in_array('feed', $rel) || (in_array('alternate', $rel) && !in_array('stylesheet', $rel) && $link->hasAttribute('type') && in_array(strtolower($this->registry->call(Misc::class, 'parse_mime', [$link->getAttribute('type')])), ['text/html', 'application/rss+xml', 'application/atom+xml'])) && !isset($feeds[$href])) { + if (!in_array($href, $done) && in_array('feed', $rel) || (in_array('alternate', $rel) && !in_array('stylesheet', $rel) && $link->hasAttribute('type') && in_array(strtolower($this->registry->call(Misc::class, 'parse_mime', [$link->getAttribute('type') ?? ''])), ['text/html', 'application/rss+xml', 'application/atom+xml'])) && !isset($feeds[$href])) { $this->checked_feeds++; $headers = [ 'Accept' => SimplePie::DEFAULT_HTTP_ACCEPT_HEADER, @@ -297,13 +291,13 @@ public function get_links() $links = $this->dom->getElementsByTagName('a'); foreach ($links as $link) { if ($link->hasAttribute('href')) { - $href = trim($link->getAttribute('href')); + $href = trim($link->getAttribute('href') ?? ''); $parsed = $this->registry->call(Misc::class, 'parse_url', [$href]); if ($parsed['scheme'] === '' || preg_match('/^(https?|feed)?$/i', $parsed['scheme'])) { if ($this->base_location < $link->getLineNo()) { - $href = $this->registry->call(Misc::class, 'absolutize_url', [trim($link->getAttribute('href')), $this->base]); + $href = $this->registry->call(Misc::class, 'absolutize_url', [trim($link->getAttribute('href') ?? ''), $this->base]); } else { - $href = $this->registry->call(Misc::class, 'absolutize_url', [trim($link->getAttribute('href')), $this->http_base]); + $href = $this->registry->call(Misc::class, 'absolutize_url', [trim($link->getAttribute('href') ?? ''), $this->http_base]); } if ($href === false) { continue; @@ -340,17 +334,13 @@ public function get_rel_link(string $rel) throw new \SimplePie\Exception('DOMDocument not found, unable to use '. 'locator'); } - if (!class_exists('DOMXpath')) { - throw new \SimplePie\Exception('DOMXpath not found, unable to use '. - 'get_rel_link'); - } - $xpath = new \DOMXpath($this->dom); + $xpath = new \Dom\XPath($this->dom); $query = '(//head)[1]/link[@rel and @href]'; - /** @var \DOMNodeList<\DOMElement> */ + /** @var \Dom\NodeList<\Dom\Element> */ $queryResult = $xpath->query($query); foreach ($queryResult as $link) { - $href = trim($link->getAttribute('href')); + $href = trim($link->getAttribute('href') ?? ''); $parsed = $this->registry->call(Misc::class, 'parse_url', [$href]); if ($parsed['scheme'] === '' || preg_match('/^https?$/i', $parsed['scheme'])) { @@ -358,19 +348,19 @@ public function get_rel_link(string $rel) $href = $this->registry->call( Misc::class, 'absolutize_url', - [trim($link->getAttribute('href')), $this->base] + [trim($link->getAttribute('href') ?? ''), $this->base] ); } else { $href = $this->registry->call( Misc::class, 'absolutize_url', - [trim($link->getAttribute('href')), $this->http_base] + [trim($link->getAttribute('href') ?? ''), $this->http_base] ); } if ($href === false) { return null; } - $rel_values = explode(' ', strtolower($link->getAttribute('rel'))); + $rel_values = explode(' ', strtolower($link->getAttribute('rel') ?? '')); if (in_array($rel, $rel_values)) { return $href; } diff --git a/src/Parser.php b/src/Parser.php index 103baa453..35ee5500f 100644 --- a/src/Parser.php +++ b/src/Parser.php @@ -69,15 +69,16 @@ public function set_registry(\SimplePie\Registry $registry) */ public function parse(string &$data, string $encoding, string $url = '') { - if (class_exists('DOMXpath') && function_exists('Mf2\parse')) { - $doc = new \DOMDocument(); - @$doc->loadHTML($data); - $xpath = new \DOMXpath($doc); + if (class_exists(\Dom\XPath::class) && function_exists('Mf2\parse')) { + // NB: Unlike with the legacy DOM API, parsing never fails (no recovery needed), + // and errors are swallowed by `LIBXML_NOERROR`. + $doc = \Dom\HTMLDocument::createFromString($data, LIBXML_NOERROR); + $xpath = new \Dom\XPath($doc); // Check for both h-feed and h-entry, as both a feed with no entries // and a list of entries without an h-feed wrapper are both valid. $query = '//*[contains(concat(" ", @class, " "), " h-feed ") or '. 'contains(concat(" ", @class, " "), " h-entry ")]'; - /** @var \DOMNodeList<\DOMElement> $result */ + /** @var \Dom\NodeList<\Dom\Element> $result */ $result = $xpath->query($query); if ($result->length !== 0) { return $this->parse_microformats($data, $url); diff --git a/src/Sanitize.php b/src/Sanitize.php index 9a5aca0cd..9d3a59168 100644 --- a/src/Sanitize.php +++ b/src/Sanitize.php @@ -7,8 +7,6 @@ namespace SimplePie; -use DOMDocument; -use DOMXPath; use InvalidArgumentException; use Psr\Http\Client\ClientInterface; use Psr\Http\Message\RequestFactoryInterface; @@ -485,27 +483,30 @@ public function sanitize(string $data, int $type, string $base = '') } if ($type & (\SimplePie\SimplePie::CONSTRUCT_HTML | \SimplePie\SimplePie::CONSTRUCT_XHTML)) { - if (!class_exists('DOMDocument')) { - throw new \SimplePie\Exception('DOMDocument not found, unable to use sanitizer'); - } - $document = new \DOMDocument(); - $document->encoding = 'UTF-8'; - // PHPStan seems to have trouble resolving int-mask because bitwise // operators are used when operators are used when passing this parameter. // https://github.com/phpstan/phpstan/issues/9384 /** @var int-mask-of $type */ $data = $this->preprocess($data, $type); - set_error_handler([Misc::class, 'silence_errors']); - $document->loadHTML($data); - restore_error_handler(); - - $xpath = new \DOMXPath($document); + // NB: Unlike with the legacy DOM API, parsing never fails (no recovery needed). + // Without HTML_NO_DEFAULT_NS, elements are parsed into their proper + // namespaces (XHTML, SVG, MathML), which makes the HTML5 serialiser + // emit void elements correctly ("", no "" end tag), and + // allows the XPath queries below to use registered prefixes. + $document = \Dom\HTMLDocument::createFromString($data, LIBXML_NOERROR); + + $xpath = new \Dom\XPath($document); + // Register the namespaces used by the HTML parser, for the prefixed + // XPath queries below. Unprefixed name tests would only match + // elements in no namespace, i.e. none. + $xpath->registerNamespace('xh', 'http://www.w3.org/1999/xhtml'); + $xpath->registerNamespace('svg', 'http://www.w3.org/2000/svg'); + $xpath->registerNamespace('mml', 'http://www.w3.org/1998/Math/MathML'); // Strip comments if ($this->strip_comments) { - /** @var \DOMNodeList<\DOMComment> */ + /** @var \Dom\NodeList<\Dom\Comment> */ $comments = $xpath->query('//comment()'); foreach ($comments as $comment) { @@ -566,7 +567,8 @@ public function sanitize(string $data, int $type, string $base = '') foreach ($images as $img) { if ($img->hasAttribute('src')) { - $image_url = $this->cache_namefilter->filter($img->getAttribute('src')); + $src = $img->getAttribute('src') ?? ''; + $image_url = $this->cache_namefilter->filter($src); $cache = $this->get_cache($image_url); if ($cache->get_data($image_url, false)) { @@ -575,7 +577,7 @@ public function sanitize(string $data, int $type, string $base = '') try { $file = $this->get_http_client()->request( Client::METHOD_GET, - $img->getAttribute('src'), + $src, ['X-FORWARDED-FOR' => $_SERVER['REMOTE_ADDR']] ); } catch (ClientException $th) { @@ -600,18 +602,16 @@ public function sanitize(string $data, int $type, string $base = '') $div = $item->firstChild; } // Finally, convert to a HTML string - $data = trim((string) $document->saveHTML($div)); + $data = trim($document->saveHtml($div) ?: ''); if ($this->remove_div) { - $data = preg_replace('/^/', '', $data); - // Cast for PHPStan, it is unable to validate a non-literal regex above. - $data = preg_replace('/<\/div>$/', '', (string) $data); + // Casts for PHPStan, it is unable to validate a non-literal regex above. + $data = (string) preg_replace('/^/', '', $data); + $data = (string) preg_replace('/<\/div>$/', '', $data); } else { - $data = preg_replace('/^/', '
', $data); + // Cast for PHPStan, it is unable to validate a non-literal regex above. + $data = (string) preg_replace('/^/', '
', $data); } - - // Cast for PHPStan, it is unable to validate a non-literal regex above. - $data = str_replace('', '', (string) $data); } if ($type & \SimplePie\SimplePie::CONSTRUCT_IRI) { @@ -663,7 +663,7 @@ protected function preprocess(string $html, int $type) * @param array|string $attributes * @return void */ - public function replace_urls(DOMDocument $document, string $tag, $attributes) + public function replace_urls(\Dom\Document $document, string $tag, $attributes) { if (!is_array($attributes)) { $attributes = [$attributes]; @@ -674,7 +674,7 @@ public function replace_urls(DOMDocument $document, string $tag, $attributes) foreach ($elements as $element) { foreach ($attributes as $attribute) { if ($element->hasAttribute($attribute)) { - $value = $this->registry->call(Misc::class, 'absolutize_url', [$element->getAttribute($attribute), $this->base]); + $value = $this->registry->call(Misc::class, 'absolutize_url', [$element->getAttribute($attribute) ?? '', $this->base]); if ($value !== false) { // Block disallowed URI protocols (e.g. javascript:), otherwise force HTTPS where applicable $value = ($this->disallowed_uri_schemes !== [] && !$this->is_allowed_uri($tag, $attribute, $value)) @@ -712,10 +712,13 @@ public function do_strip_htmltags(array $match) /** * Keep only allowed HTML elements (tags) and their allowed attributes. */ - protected function enforce_allowed_html_nodes(\DOMNode $element, bool $allow_data_attr = true, bool $allow_aria_attr = true): void + protected function enforce_allowed_html_nodes(\Dom\Node $element, bool $allow_data_attr = true, bool $allow_aria_attr = true): void { - if ($element instanceof \DOMElement) { - $tag = $element->tagName; + if ($element instanceof \Dom\Element) { + // NB: `tagName` of namespaced HTML elements is uppercased by libxml. + // Use `localName` instead, which is ASCII-lowercased as per HTML, + // except for case-adjusted SVG/MathML tag names (e.g. `foreignObject`). + $tag = $element->localName; $parent = $element->parentNode; if (!in_array($tag, ['html', 'head', 'body', 'div'], true) && !isset($this->allowed_html_elements_with_attributes[$tag])) { @@ -724,7 +727,7 @@ protected function enforce_allowed_html_nodes(\DOMNode $element, bool $allow_dat $nextSibling = $element->nextSibling; while ($element->firstChild !== null) { $child = $element->firstChild; - if ($child instanceof \DOMText) { + if ($child instanceof \Dom\Text) { $child->nodeValue = htmlspecialchars($child->nodeValue ?? '', ENT_QUOTES, 'UTF-8'); } if ($parent !== null) { @@ -756,7 +759,7 @@ protected function enforce_allowed_html_nodes(\DOMNode $element, bool $allow_dat } } } - if ($element instanceof \DOMElement || $element instanceof \DOMDocument) { + if ($element instanceof \Dom\Element || $element instanceof \Dom\Document) { for ($i = $element->childNodes->length - 1; $i >= 0; $i--) { $child = $element->childNodes->item($i); if ($child !== null) { @@ -815,27 +818,25 @@ public function is_allowed_uri(string $tag, string $attribute, string $uri): boo * This handles MathML and SVG elements which permit href on arbitrary descendant elements * For SVG, also checks xlink:href attribute. */ - private function block_disallowed_schemes_in_descendants(\DOMXPath $xpath): void + private function block_disallowed_schemes_in_descendants(\Dom\XPath $xpath): void { - // Note: content is parsed via loadHTML(), which does not namespace-process attributes - $elements = $xpath->query('.//*[self::math or self::svg]/descendant-or-self::*[@href or @*[name()="xlink:href"]]'); - if ($elements === false) { - return; - } + // NB: SVG and MathML elements are parsed into their own namespaces + // (cf. the `registerNamespace()` calls above). + // Note: content is parsed via the HTML5 parser, which does not namespace-process attributes + $elements = $xpath->query('.//*[self::mml:math or self::svg:svg]/descendant-or-self::*[@href or @*[name()="xlink:href"]]'); foreach ($elements as $element) { - if (!($element instanceof \DOMElement)) { - continue; - } - if ($element->hasAttribute('href')) { - $href = $element->getAttribute('href'); - if (!$this->is_allowed_scheme($href)) { - $element->setAttribute('href', 'unsafe:' . $href); + if ($element instanceof \Dom\Element) { + if ($element->hasAttribute('href')) { + $href = $element->getAttribute('href') ?? ''; + if (!$this->is_allowed_scheme($href)) { + $element->setAttribute('href', 'unsafe:' . $href); + } } - } - if ($element->hasAttribute('xlink:href')) { - $href = $element->getAttribute('xlink:href'); - if (!$this->is_allowed_scheme($href)) { - $element->setAttribute('xlink:href', 'unsafe:' . $href); + if ($element->hasAttribute('xlink:href')) { + $href = $element->getAttribute('xlink:href') ?? ''; + if (!$this->is_allowed_scheme($href)) { + $element->setAttribute('xlink:href', 'unsafe:' . $href); + } } } } @@ -845,11 +846,15 @@ private function block_disallowed_schemes_in_descendants(\DOMXPath $xpath): void * @param int-mask-of $type * @return void */ - protected function strip_tag(string $tag, DOMDocument $document, DOMXPath $xpath, int $type) + protected function strip_tag(string $tag, \Dom\Document $document, \Dom\XPath $xpath, int $type) { - $elements = $xpath->query('body//' . $tag); - - if ($elements === false) { + try { + // Match the requested tag in any of the namespaces the HTML parser + // puts elements in (cf. the three `registerNamespace()` calls above): + // mostly the XHTML namespace, but e.g. `image` exists in both + // XHTML and SVG. + $elements = $xpath->query('xh:body//*[self::xh:' . $tag . ' or self::svg:' . $tag . ' or self::mml:' . $tag . ']'); + } catch (\Throwable $ex) { throw new \SimplePie\Exception(sprintf( '%s(): Possibly malformed expression, check argument #1 ($tag)', __METHOD__ @@ -858,7 +863,7 @@ protected function strip_tag(string $tag, DOMDocument $document, DOMXPath $xpath if ($this->encode_instead_of_strip) { foreach ($elements as $element) { - if (!($element instanceof \DOMNode)) { + if (!$element instanceof \Dom\Element) { continue; } $fragment = $document->createDocumentFragment(); @@ -866,28 +871,26 @@ protected function strip_tag(string $tag, DOMDocument $document, DOMXPath $xpath // For elements which aren't script or style, include the tag itself if (!in_array($tag, ['script', 'style'])) { $text = '<' . $tag; - if ($element->attributes !== null) { - $attrs = []; - foreach ($element->attributes as $name => $attr) { - $value = $attr->value; - - // In XHTML, empty values should never exist, so we repeat the value - if (empty($value) && ($type & \SimplePie\SimplePie::CONSTRUCT_XHTML)) { - $value = $name; - } - // For HTML, empty is fine - elseif (empty($value) && ($type & \SimplePie\SimplePie::CONSTRUCT_HTML)) { - $attrs[] = $name; - continue; - } + $attrs = []; + foreach ($element->attributes as $name => $attr) { + $value = $attr->value; - // Standard attribute text - $attrs[] = $name . '="' . $attr->value . '"'; + // In XHTML, empty values should never exist, so we repeat the value + if (empty($value) && ($type & \SimplePie\SimplePie::CONSTRUCT_XHTML)) { + $value = $name; + } + // For HTML, empty is fine + elseif (empty($value) && ($type & \SimplePie\SimplePie::CONSTRUCT_HTML)) { + $attrs[] = $name; + continue; } - $text .= ' ' . implode(' ', $attrs); + + // Standard attribute text + $attrs[] = $name . '="' . $attr->value . '"'; } + $text .= ' ' . implode(' ', $attrs); $text .= '>'; - $fragment->appendChild(new \DOMText($text)); + $fragment->appendChild($document->createTextNode($text)); } $number = $element->childNodes->length; @@ -898,7 +901,7 @@ protected function strip_tag(string $tag, DOMDocument $document, DOMXPath $xpath } if (!in_array($tag, ['script', 'style'])) { - $fragment->appendChild(new \DOMText('')); + $fragment->appendChild($document->createTextNode('')); } if (($parentNode = $element->parentNode) !== null) { @@ -917,9 +920,6 @@ protected function strip_tag(string $tag, DOMDocument $document, DOMXPath $xpath return; } else { foreach ($elements as $element) { - if (!($element instanceof \DOMNode)) { - continue; - } $fragment = $document->createDocumentFragment(); $number = $element->childNodes->length; for ($i = $number; $i > 0; $i--) { @@ -938,18 +938,18 @@ protected function strip_tag(string $tag, DOMDocument $document, DOMXPath $xpath /** * @return void */ - protected function strip_attr(string $attrib, DOMXPath $xpath) + protected function strip_attr(string $attrib, \Dom\XPath $xpath) { - $elements = $xpath->query('//*[@' . $attrib . ']'); - - if ($elements === false) { + try { + $elements = $xpath->query('//*[@' . $attrib . ']'); + } catch (\Throwable $ex) { throw new \SimplePie\Exception(sprintf( '%s(): Possibly malformed expression, check argument #1 ($attrib)', __METHOD__ ), 1); } - /** @var \DOMElement $element */ + /** @var \Dom\Element $element */ foreach ($elements as $element) { $element->removeAttribute($attrib); } @@ -958,20 +958,20 @@ protected function strip_attr(string $attrib, DOMXPath $xpath) /** * @return void */ - protected function rename_attr(string $attrib, DOMXPath $xpath) + protected function rename_attr(string $attrib, \Dom\XPath $xpath) { - $elements = $xpath->query('//*[@' . $attrib . ']'); - - if ($elements === false) { + try { + $elements = $xpath->query('//*[@' . $attrib . ']'); + } catch (\Throwable $ex) { throw new \SimplePie\Exception(sprintf( '%s(): Possibly malformed expression, check argument #1 ($attrib)', __METHOD__ ), 1); } - /** @var \DOMElement $element */ + /** @var \Dom\Element $element */ foreach ($elements as $element) { - $element->setAttribute('data-sanitized-' . $attrib, $element->getAttribute($attrib)); + $element->setAttribute('data-sanitized-' . $attrib, $element->getAttribute($attrib) ?? ''); $element->removeAttribute($attrib); } } @@ -980,10 +980,10 @@ protected function rename_attr(string $attrib, DOMXPath $xpath) * @param array $valuePairs * @return void */ - protected function add_attr(string $tag, array $valuePairs, DOMDocument $document) + protected function add_attr(string $tag, array $valuePairs, \Dom\Document $document) { $elements = $document->getElementsByTagName($tag); - /** @var \DOMElement $element */ + /** @var \Dom\Element $element */ foreach ($elements as $element) { foreach ($valuePairs as $attrib => $value) { $element->setAttribute($attrib, $value); diff --git a/src/SimplePie.php b/src/SimplePie.php index 2bbe1dbea..9d726caa5 100644 --- a/src/SimplePie.php +++ b/src/SimplePie.php @@ -2227,16 +2227,17 @@ protected function fetch_data(&$cache) $copyContentType = $file->get_header_line('content-type'); try { $microformats = false; - if (class_exists('DOMXpath') && function_exists('Mf2\parse')) { - $doc = new \DOMDocument(); - @$doc->loadHTML($file->get_body_content()); - $xpath = new \DOMXpath($doc); + if (class_exists(\Dom\XPath::class) && function_exists('Mf2\parse')) { + // NB: Unlike with the legacy DOM API, parsing never fails (no recovery needed), + // and errors are swallowed by `LIBXML_NOERROR`. + $doc = \Dom\HTMLDocument::createFromString($file->get_body_content(), LIBXML_NOERROR); + $xpath = new \Dom\XPath($doc); // Check for both h-feed and h-entry, as both a feed with no entries // and a list of entries without an h-feed wrapper are both valid. $query = '//*[contains(concat(" ", @class, " "), " h-feed ") or '. 'contains(concat(" ", @class, " "), " h-entry ")]'; - /** @var \DOMNodeList<\DOMElement> $result */ + /** @var \Dom\NodeList<\Dom\Element> $result */ $result = $xpath->query($query); $microformats = $result->length !== 0; } diff --git a/tests/LocatorTest.php b/tests/LocatorTest.php index 69ee73e47..ad82c4804 100755 --- a/tests/LocatorTest.php +++ b/tests/LocatorTest.php @@ -122,16 +122,16 @@ public function test_from_file(File $data): void $locator->set_registry($registry); $expected = []; - $document = new DOMDocument(); - $document->loadHTML((string) $data->body); - $xpath = new DOMXPath($document); + $document = \Dom\HTMLDocument::createFromString((string) $data->body, LIBXML_NOERROR | \Dom\HTML_NO_DEFAULT_NS); + $xpath = new \Dom\XPath($document); - /** @var \DOMNodeList<\DOMElement> $queryResult */ $queryResult = $xpath->query('//link'); foreach ($queryResult as $element) { - /** @var \DOMElement $element */ - $expected[] = 'http://example.com' . $element->getAttribute('href'); + if (!$element instanceof \Dom\Element) { + continue; + } + $expected[] = 'http://example.com' . ($element->getAttribute('href') ?? ''); } //$expected = SimplePie_Misc::get_element('link', $data->body); diff --git a/tests/SanitizeTest.php b/tests/SanitizeTest.php index 1120cf3eb..55811f6c6 100755 --- a/tests/SanitizeTest.php +++ b/tests/SanitizeTest.php @@ -40,7 +40,7 @@ public function testSanitize(): void ]); self::assertSame( <<Details

...

+
Details

...

HTML , trim(preg_replace('/\R\s+/', '', $sanitize_whitelist->sanitize( diff --git a/tests/Unit/LocatorTest.php b/tests/Unit/LocatorTest.php index aa2b7c4bf..ed0a3127d 100644 --- a/tests/Unit/LocatorTest.php +++ b/tests/Unit/LocatorTest.php @@ -7,8 +7,6 @@ namespace SimplePie\Tests\Unit; -use DOMDocument; -use DOMXPath; use PHPUnit\Framework\TestCase; use SimplePie\File; use SimplePie\HTTP\RawTextResponse; @@ -135,16 +133,16 @@ public function test_from_file(File $data): void $locator->set_registry($registry); $expected = []; - $document = new DOMDocument(); - $document->loadHTML((string) $data->body); - $xpath = new DOMXPath($document); + $document = \Dom\HTMLDocument::createFromString((string) $data->body, LIBXML_NOERROR | \Dom\HTML_NO_DEFAULT_NS); + $xpath = new \Dom\XPath($document); - /** @var \DOMNodeList<\DOMElement> $queryResult */ $queryResult = $xpath->query('//link'); foreach ($queryResult as $element) { - /** @var \DOMElement $element */ - $expected[] = 'http://example.com' . $element->getAttribute('href'); + if (!$element instanceof \Dom\Element) { + continue; + } + $expected[] = 'http://example.com' . ($element->getAttribute('href') ?? ''); } //$expected = SimplePie_Misc::get_element('link', $data->body); From 829e1db09214a105930ab7a06f200523f619af83 Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sun, 15 Nov 2026 16:53:47 +0100 Subject: [PATCH 02/10] Polyfill PHP 8.4+ `Dom\` classes --- autoloader.php | 3 + compat/dom-polyfill.php | 100 ++++++++++++++++++++++++++++ compat/dom.php | 12 ++++ composer.json | 5 +- phpstan.dist.neon | 7 ++ tests/Integration/SimplePieTest.php | 3 +- 6 files changed, 127 insertions(+), 3 deletions(-) create mode 100644 compat/dom-polyfill.php create mode 100644 compat/dom.php diff --git a/autoloader.php b/autoloader.php index 1ae88be64..1b4e63169 100644 --- a/autoloader.php +++ b/autoloader.php @@ -3,6 +3,9 @@ // SPDX-FileCopyrightText: 2004-2023 Ryan Parman, Sam Sneddon, Ryan McCue // SPDX-License-Identifier: BSD-3-Clause +// Polyfill PHP 8.4+ `Dom\` classes +require_once __DIR__ . '/compat/dom.php'; + /** * PSR-4 implementation for SimplePie. * diff --git a/compat/dom-polyfill.php b/compat/dom-polyfill.php new file mode 100644 index 000000000..4f6fb7966 --- /dev/null +++ b/compat/dom-polyfill.php @@ -0,0 +1,100 @@ + */ + private $registeredPrefixes = []; + + /** + * @param string $prefix + * @param string $namespaceURI + */ + public function registerNamespace($prefix, $namespaceURI) + { + $this->registeredPrefixes[$prefix] = true; + return parent::registerNamespace($prefix, $namespaceURI); + } + + private function translate(string $expression): string + { + if ($this->registeredPrefixes === []) { + return $expression; + } + foreach (array_keys($this->registeredPrefixes) as $prefix) { + // NCName-boundary safe: + $translated = preg_replace('/(?translate($expression); + $result = @parent::query($translated, $contextNode, $registerNodeNS); + if ($result === false) { + throw new \Exception('Invalid XPath expression: ' . $translated); + } + return $result; + } +} + +/** + * Maps `\Dom\HTMLDocument::createFromString()` onto `\DOMDocument::loadHTML()`. + */ +final class HTMLDocument extends \DOMDocument +{ + /** + * @return static + */ + public static function createFromString(string $source, ?int $options = null, ?string $overrideEncoding = null) + { + $document = new self(); + $options = ($options ?? 0) | LIBXML_NOERROR | LIBXML_NOWARNING; + + if ($source !== '' && !preg_match('#<(?:meta|\?xml)[^>]*?(?:charset|encoding)\\s*=#i', $source)) { + // If the source itself declares an encoding, let the parser honour it, otherwise UTF-8: + $source = '' . $source; + } + + try { + $document->loadHTML($source, $options); + } catch (\ValueError $e) { + // the native API silently creates an empty document. + } + + return $document; + } +} diff --git a/compat/dom.php b/compat/dom.php new file mode 100644 index 000000000..25da8fc14 --- /dev/null +++ b/compat/dom.php @@ -0,0 +1,12 @@ +=8.4.0", + "php": ">=7.4.0", "ext-dom": "*", "ext-pcre": "*", "ext-xml": "*", @@ -49,6 +49,9 @@ "mf2/mf2": "Microformat module that allows for parsing HTML for microformats" }, "autoload": { + "files": [ + "compat/dom.php" + ], "psr-4": { "SimplePie\\": "src" }, diff --git a/phpstan.dist.neon b/phpstan.dist.neon index d3b949821..c1505c7fb 100644 --- a/phpstan.dist.neon +++ b/phpstan.dist.neon @@ -17,6 +17,13 @@ parameters: - build/*? - vendor/* + # For PHP < 8.4 + ignoreErrors: + - + identifier: class.notFound + messages: + - '#Dom\\\S+#' + treatPhpDocTypesAsCertain: false # TODO: Fix includes: diff --git a/tests/Integration/SimplePieTest.php b/tests/Integration/SimplePieTest.php index 95a5de65c..c15153a46 100644 --- a/tests/Integration/SimplePieTest.php +++ b/tests/Integration/SimplePieTest.php @@ -347,8 +347,7 @@ public function testMicroformatItems(string $path, string $feedTitle, array $tit self::assertSame($feedTitle, $feed->get_title()); $items = $feed->get_items(); - // @phpstan-ignore phpunit.assertCount - self::assertSame(count($titles), count($items), 'Number of items does not match'); + self::assertCount(count($titles), $items, 'Number of items does not match'); foreach (array_map(null, $titles, $items) as $i => [$expectedTitle, $item]) { assert($item !== null); // For PHPStan self::assertSame($expectedTitle, $item->get_title(), "Title of item #$i does not match"); From 18ed48287a1af87a4d6484be8560464142acfb4c Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sun, 15 Nov 2026 17:36:14 +0100 Subject: [PATCH 03/10] Try better compat --- compat/dom-polyfill.php | 44 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/compat/dom-polyfill.php b/compat/dom-polyfill.php index 4f6fb7966..c26cc499e 100644 --- a/compat/dom-polyfill.php +++ b/compat/dom-polyfill.php @@ -11,6 +11,9 @@ const HTML_NO_DEFAULT_NS = 2147483648; +// Hide from PHPStan to avoid divergent signature shapes of the legacy aliases +if (!defined('__PHPSTAN_RUNNING__')): + // The polyfilled node classes class_alias(\DOMNode::class, 'Dom\Node', false); class_alias(\DOMElement::class, 'Dom\Element', false); @@ -32,7 +35,7 @@ final class XPath extends \DOMXPath * @param string $prefix * @param string $namespaceURI */ - public function registerNamespace($prefix, $namespaceURI) + public function registerNamespace($prefix, $namespaceURI): bool { $this->registeredPrefixes[$prefix] = true; return parent::registerNamespace($prefix, $namespaceURI); @@ -58,9 +61,8 @@ private function translate(string $expression): string * * @param string $expression * @param \DOMNode|null $contextNode - * @return \DOMNodeList|false */ - public function query($expression, $contextNode = null, $registerNodeNS = true) + public function query($expression, $contextNode = null, $registerNodeNS = true): \DOMNodeList { $translated = $this->translate($expression); $result = @parent::query($translated, $contextNode, $registerNodeNS); @@ -90,11 +92,45 @@ public static function createFromString(string $source, ?int $options = null, ?s } try { - $document->loadHTML($source, $options); + // `HTML_NO_DEFAULT_NS` is unknown to the legacy `loadHTML()` + $document->loadHTML($source, $options & ~HTML_NO_DEFAULT_NS); } catch (\ValueError $e) { // the native API silently creates an empty document. } return $document; } + + /** + * Normalise to `attr=""` for parity. + * It also emits end tags for void elements (e.g. ``). + */ + public function saveHTML(?\DOMNode $node = null): string|false + { + $html = parent::saveHTML($node); + if ($html === false) { + return false; + } + // Drop void-element end tags emitted for e.g. ``: + $html = (string) preg_replace('#(<(area|base|br|col|embed|hr|img|input|link|meta|param|source|track|wbr)\b[^>]*?>)#i', '$1', $html); + return (string) preg_replace_callback('#<[\w:-]+[^>]*?>#', static function (array $match): string { + $bools = 'allowfullscreen|async|autofocus|autoplay|checked|controls|default|defer|disabled|formnovalidate|hidden|inert|ismap|itemscope|loop|multiple|muted|nomodule|novalidate|open|playsinline|readonly|required|reversed|selected'; + // Only scan outside quoted attribute values, which have no raw `"`: + $parts = preg_split('#(="[^"]*")#', $match[0], -1, PREG_SPLIT_DELIM_CAPTURE); + if ($parts === false) { + return $match[0]; + } + foreach ($parts as $i => $part) { + if ($i % 2 === 0) { + $replaced = preg_replace('#\s(' . $bools . ')(?=[\s/>])#i', ' $1=""', $part); + if ($replaced !== null) { + $parts[$i] = $replaced; + } + } + } + return implode('', $parts); + }, $html) ?: $html; + } } + +endif; From 76c0fd164f3aaacf23f68f1a1fa4072f5d72be90 Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sun, 15 Nov 2026 18:24:16 +0100 Subject: [PATCH 04/10] More compat PHP 7.4 --- compat/dom-polyfill.php | 22 ++++++++++------- src/Sanitize.php | 48 +++++++++++++++++++++++++------------- tests/LocatorTest.php | 2 +- tests/Unit/LocatorTest.php | 2 +- 4 files changed, 48 insertions(+), 26 deletions(-) diff --git a/compat/dom-polyfill.php b/compat/dom-polyfill.php index c26cc499e..69b263c8e 100644 --- a/compat/dom-polyfill.php +++ b/compat/dom-polyfill.php @@ -14,13 +14,16 @@ // Hide from PHPStan to avoid divergent signature shapes of the legacy aliases if (!defined('__PHPSTAN_RUNNING__')): -// The polyfilled node classes -class_alias(\DOMNode::class, 'Dom\Node', false); -class_alias(\DOMElement::class, 'Dom\Element', false); -class_alias(\DOMText::class, 'Dom\Text', false); -class_alias(\DOMComment::class, 'Dom\Comment', false); -class_alias(\DOMNodeList::class, 'Dom\NodeList', false); -class_alias(\DOMDocument::class, 'Dom\Document', false); +// Aliasing internal classes requires PHP 8.3+ +if (\PHP_VERSION_ID >= 80300) { + // The polyfilled node classes + class_alias(\DOMNode::class, 'Dom\Node', false); + class_alias(\DOMElement::class, 'Dom\Element', false); + class_alias(\DOMText::class, 'Dom\Text', false); + class_alias(\DOMComment::class, 'Dom\Comment', false); + class_alias(\DOMNodeList::class, 'Dom\NodeList', false); + class_alias(\DOMDocument::class, 'Dom\Document', false); +} /** * On the legacy path, the parser never puts elements in any namespace, @@ -104,8 +107,11 @@ public static function createFromString(string $source, ?int $options = null, ?s /** * Normalise to `attr=""` for parity. * It also emits end tags for void elements (e.g. ``). + * + * @return string|false */ - public function saveHTML(?\DOMNode $node = null): string|false + #[\ReturnTypeWillChange] + public function saveHTML(?\DOMNode $node = null) { $html = parent::saveHTML($node); if ($html === false) { diff --git a/src/Sanitize.php b/src/Sanitize.php index 9bb094e4a..c97aabd17 100644 --- a/src/Sanitize.php +++ b/src/Sanitize.php @@ -659,10 +659,11 @@ protected function preprocess(string $html, int $type) } /** + * @param \Dom\Document|\DOMDocument $document * @param array|string $attributes * @return void */ - public function replace_urls(\Dom\Document $document, string $tag, $attributes) + public function replace_urls($document, string $tag, $attributes) { if (!is_array($attributes)) { $attributes = [$attributes]; @@ -710,10 +711,12 @@ public function do_strip_htmltags(array $match) /** * Keep only allowed HTML elements (tags) and their allowed attributes. + * + * @param \Dom\Node|\DOMNode|\DOMElement|\Dom\Element $element */ - protected function enforce_allowed_html_nodes(\Dom\Node $element, bool $allow_data_attr = true, bool $allow_aria_attr = true): void + protected function enforce_allowed_html_nodes($element, bool $allow_data_attr = true, bool $allow_aria_attr = true): void { - if ($element instanceof \Dom\Element) { + if ($element instanceof \DOMElement || $element instanceof \Dom\Element) { // NB: `tagName` of namespaced HTML elements is uppercased by libxml. // Use `localName` instead, which is ASCII-lowercased as per HTML, // except for case-adjusted SVG/MathML tag names (e.g. `foreignObject`). @@ -726,7 +729,7 @@ protected function enforce_allowed_html_nodes(\Dom\Node $element, bool $allow_da $nextSibling = $element->nextSibling; while ($element->firstChild !== null) { $child = $element->firstChild; - if ($child instanceof \Dom\Text) { + if ($child instanceof \DOMText || $child instanceof \Dom\Text) { $child->nodeValue = htmlspecialchars($child->nodeValue ?? '', ENT_QUOTES, 'UTF-8'); } if ($parent !== null) { @@ -740,25 +743,31 @@ protected function enforce_allowed_html_nodes(\Dom\Node $element, bool $allow_da } } if ($parent !== null) { - $parent->removeChild($element); + if ($element instanceof \DOMElement) { + $parent->removeChild($element); + } elseif ($parent instanceof \Dom\Element || $parent instanceof \Dom\Document) { + $parent->removeChild($element); + } return; } } $allowed_attrs = array_merge($this->allowed_html_elements_with_attributes[$tag] ?? [], $this->allowed_html_attributes); - for ($i = $element->attributes->length - 1; $i >= 0; $i--) { - $attr = $element->attributes[$i]->nodeName; + $attributes = $element->attributes ?? []; + for ($i = $attributes->length - 1; $i >= 0; $i--) { + $attrNode = $attributes[$i]; + $attr = $attrNode->nodeName; // Skip data-*, aria-* if allowed - if (($allow_data_attr && str_starts_with($attr, 'data-')) - || ($allow_aria_attr && str_starts_with($attr, 'aria-'))) { + if (($allow_data_attr && substr($attr, 0, 5) === 'data-') + || ($allow_aria_attr && substr($attr, 0, 5) === 'aria-')) { continue; } if (!in_array($attr, $allowed_attrs, true)) { - $element->removeAttributeNode($element->attributes[$i]); + $element->removeAttributeNode($attrNode); } } } - if ($element instanceof \Dom\Element || $element instanceof \Dom\Document) { + if ($element instanceof \DOMElement || $element instanceof \Dom\Element || $element instanceof \DOMDocument || $element instanceof \Dom\Document) { for ($i = $element->childNodes->length - 1; $i >= 0; $i--) { $child = $element->childNodes->item($i); if ($child !== null) { @@ -824,7 +833,7 @@ private function block_disallowed_schemes_in_descendants(\Dom\XPath $xpath): voi // Note: content is parsed via the HTML5 parser, which does not namespace-process attributes $elements = $xpath->query('.//*[self::mml:math or self::svg:svg]/descendant-or-self::*[@href or @*[name()="xlink:href"]]'); foreach ($elements as $element) { - if ($element instanceof \Dom\Element) { + if ($element instanceof \DOMElement || $element instanceof \Dom\Element) { if ($element->hasAttribute('href')) { $href = $element->getAttribute('href') ?? ''; if (!$this->is_allowed_scheme($href)) { @@ -842,10 +851,11 @@ private function block_disallowed_schemes_in_descendants(\Dom\XPath $xpath): voi } /** + * @param \Dom\Document|\DOMDocument $document * @param int-mask-of $type * @return void */ - protected function strip_tag(string $tag, \Dom\Document $document, \Dom\XPath $xpath, int $type) + protected function strip_tag(string $tag, $document, \Dom\XPath $xpath, int $type) { try { // Match the requested tag in any of the namespaces the HTML parser @@ -862,7 +872,7 @@ protected function strip_tag(string $tag, \Dom\Document $document, \Dom\XPath $x if ($this->encode_instead_of_strip) { foreach ($elements as $element) { - if (!$element instanceof \Dom\Element) { + if (!$element instanceof \DOMElement && !$element instanceof \Dom\Element) { continue; } $fragment = $document->createDocumentFragment(); @@ -903,7 +913,12 @@ protected function strip_tag(string $tag, \Dom\Document $document, \Dom\XPath $x $fragment->appendChild($document->createTextNode('')); } - if (($parentNode = $element->parentNode) !== null) { + $parentNode = $element->parentNode; + if ($element instanceof \DOMElement) { + if ($parentNode !== null) { + $parentNode->replaceChild($fragment, $element); + } + } elseif ($parentNode instanceof \Dom\Element || $parentNode instanceof \Dom\Document) { $parentNode->replaceChild($fragment, $element); } } @@ -977,9 +992,10 @@ protected function rename_attr(string $attrib, \Dom\XPath $xpath) /** * @param array $valuePairs + * @param \Dom\Document|\DOMDocument $document * @return void */ - protected function add_attr(string $tag, array $valuePairs, \Dom\Document $document) + protected function add_attr(string $tag, array $valuePairs, $document) { $elements = $document->getElementsByTagName($tag); /** @var \Dom\Element $element */ diff --git a/tests/LocatorTest.php b/tests/LocatorTest.php index ad82c4804..247456f33 100755 --- a/tests/LocatorTest.php +++ b/tests/LocatorTest.php @@ -128,7 +128,7 @@ public function test_from_file(File $data): void $queryResult = $xpath->query('//link'); foreach ($queryResult as $element) { - if (!$element instanceof \Dom\Element) { + if (!$element instanceof \DOMElement && !$element instanceof \Dom\Element) { continue; } $expected[] = 'http://example.com' . ($element->getAttribute('href') ?? ''); diff --git a/tests/Unit/LocatorTest.php b/tests/Unit/LocatorTest.php index ed0a3127d..15eb51ba5 100644 --- a/tests/Unit/LocatorTest.php +++ b/tests/Unit/LocatorTest.php @@ -139,7 +139,7 @@ public function test_from_file(File $data): void $queryResult = $xpath->query('//link'); foreach ($queryResult as $element) { - if (!$element instanceof \Dom\Element) { + if (!$element instanceof \DOMElement && !$element instanceof \Dom\Element) { continue; } $expected[] = 'http://example.com' . ($element->getAttribute('href') ?? ''); From 7b4c2b3b824d85b74064d0c7570e1a96e4fbaf25 Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sun, 15 Nov 2026 19:03:58 +0100 Subject: [PATCH 05/10] A round of review --- compat/dom-polyfill.php | 5 +++-- src/Locator.php | 15 ++++++++++----- src/SimplePie.php | 2 +- 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/compat/dom-polyfill.php b/compat/dom-polyfill.php index 69b263c8e..d1db6d1bf 100644 --- a/compat/dom-polyfill.php +++ b/compat/dom-polyfill.php @@ -11,8 +11,9 @@ const HTML_NO_DEFAULT_NS = 2147483648; -// Hide from PHPStan to avoid divergent signature shapes of the legacy aliases -if (!defined('__PHPSTAN_RUNNING__')): +// Hide from PHPStan to avoid divergent signature shapes of the legacy aliases, +// and also skip when legacy `ext-dom` is unavailable +if (!defined('__PHPSTAN_RUNNING__') && class_exists(\DOMDocument::class, false)): // Aliasing internal classes requires PHP 8.3+ if (\PHP_VERSION_ID >= 80300) { diff --git a/src/Locator.php b/src/Locator.php index 199972108..fac80f427 100644 --- a/src/Locator.php +++ b/src/Locator.php @@ -74,7 +74,7 @@ public function __construct(File $file, int $timeout = 10, ?string $useragent = $body = $this->file->get_body_content(); - if ($body != '') { + if (class_exists(\Dom\HTMLDocument::class) && $body != '') { // NB: Unlike with the legacy DOM API, parsing never fails, but invalid UTF-8 fails gracefully try { $this->dom = \Dom\HTMLDocument::createFromString($body, LIBXML_NOERROR | \Dom\HTML_NO_DEFAULT_NS); @@ -187,7 +187,7 @@ public function get_base() assert($this->registry !== null); if ($this->dom === null) { - throw new \SimplePie\Exception('DOMDocument not found, unable to use locator'); + throw new \SimplePie\Exception('\Dom\Document not found, unable to use locator'); } $this->http_base = $this->file->get_final_requested_uri(); $this->base = $this->http_base; @@ -233,7 +233,7 @@ protected function search_elements_by_tag(string $name, array &$done, array $fee assert($this->registry !== null); if ($this->dom === null) { - throw new \SimplePie\Exception('DOMDocument not found, unable to use locator'); + throw new \SimplePie\Exception('\Dom\Document not found, unable to use locator'); } $links = $this->dom->getElementsByTagName($name); @@ -285,7 +285,7 @@ public function get_links() assert($this->registry !== null); if ($this->dom === null) { - throw new \SimplePie\Exception('DOMDocument not found, unable to use locator'); + throw new \SimplePie\Exception('\Dom\Document not found, unable to use locator'); } $links = $this->dom->getElementsByTagName('a'); @@ -331,10 +331,15 @@ public function get_rel_link(string $rel) assert($this->registry !== null); if ($this->dom === null) { - throw new \SimplePie\Exception('DOMDocument not found, unable to use '. + throw new \SimplePie\Exception('\Dom\Document not found, unable to use '. 'locator'); } + if (!class_exists(\Dom\XPath::class)) { + throw new \SimplePie\Exception('\Dom\XPath not found, unable to use '. + 'get_rel_link'); + } + $xpath = new \Dom\XPath($this->dom); $query = '(//head)[1]/link[@rel and @href]'; /** @var \Dom\NodeList<\Dom\Element> */ diff --git a/src/SimplePie.php b/src/SimplePie.php index 203e09d00..850e9841a 100644 --- a/src/SimplePie.php +++ b/src/SimplePie.php @@ -2272,7 +2272,7 @@ protected function fetch_data(&$cache) } catch (SimplePieException $e) { // We need to unset this so that if SimplePie::set_file() has been called that object is untouched unset($file); - // This is usually because DOMDocument doesn't exist + // This is usually because `\Dom\Document` doesn't exist $this->error = $e->getMessage(); $this->registry->call(Misc::class, 'error', [$this->error, E_USER_NOTICE, $e->getFile(), $e->getLine()]); return false; From 3475ef9344d5f0fbf4645d7f78ce3c92d7ca304d Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sun, 15 Nov 2026 23:13:52 +0100 Subject: [PATCH 06/10] CssSelectors --- compat/dom-polyfill.php | 223 ++++++++++++++++++++++++++++++++-------- 1 file changed, 180 insertions(+), 43 deletions(-) diff --git a/compat/dom-polyfill.php b/compat/dom-polyfill.php index d1db6d1bf..c031f3dc8 100644 --- a/compat/dom-polyfill.php +++ b/compat/dom-polyfill.php @@ -3,7 +3,8 @@ // SPDX-FileCopyrightText: 2026 Alexandre Alapetite // SPDX-License-Identifier: BSD-3-Clause -// Polyfill PHP ≥ 8.4 `Dom\` classes approximated using legacy `DOM*` classes. +// Polyfill PHP 8.4+ `Dom\` classes approximated using legacy `DOM*` classes, +// and optional CSS selector API approximated using `GT\CssXPath` library. declare(strict_types=1); @@ -15,65 +16,115 @@ // and also skip when legacy `ext-dom` is unavailable if (!defined('__PHPSTAN_RUNNING__') && class_exists(\DOMDocument::class, false)): -// Aliasing internal classes requires PHP 8.3+ if (\PHP_VERSION_ID >= 80300) { - // The polyfilled node classes - class_alias(\DOMNode::class, 'Dom\Node', false); - class_alias(\DOMElement::class, 'Dom\Element', false); - class_alias(\DOMText::class, 'Dom\Text', false); + // The polyfilled classes that cannot use `registerNodeClass()` + // (aliasing internal classes requires PHP 8.3+): class_alias(\DOMComment::class, 'Dom\Comment', false); - class_alias(\DOMNodeList::class, 'Dom\NodeList', false); class_alias(\DOMDocument::class, 'Dom\Document', false); + class_alias(\DOMNode::class, 'Dom\Node', false); + class_alias(\DOMNodeList::class, 'Dom\NodeList', false); + class_alias(\DOMText::class, 'Dom\Text', false); } /** - * On the legacy path, the parser never puts elements in any namespace, - * so rewrite queries written for the namespaced PHP 8.4 parser (e.g. `xh:body//xh:img`). + * Optional PHP 8.4+ CSS selector API, requiring `GT\CssXPath` library. */ -final class XPath extends \DOMXPath +trait CssSelectors { - /** @var array */ - private $registeredPrefixes = []; + private function cssXPath(): ?XPath { + /** @var \DOMDocument|null $document */ + $document = $this->ownerDocument ?? $this; + return $document instanceof \DOMDocument ? new XPath($document) : null; + } /** - * @param string $prefix - * @param string $namespaceURI + * Translates a CSS selector to an XPath expression. + * + * @param string $selectors CSS selector + * @param string $prefix e.g. `.//` to search descendants of the context node + * @throws \DOMException if the CSS selector cannot be translated */ - public function registerNamespace($prefix, $namespaceURI): bool - { - $this->registeredPrefixes[$prefix] = true; - return parent::registerNamespace($prefix, $namespaceURI); + private function cssToXPath(string $selectors, string $prefix): string { + if (!class_exists(\GT\CssXPath\Translator::class)) { + // https://github.com/PhpGt/CssXPath + throw new \DOMException('CSS selectors are not available: missing the `GT\CssXPath` package'); + } + try { + return (new \GT\CssXPath\Translator($selectors, $prefix))->asXPath(); + } catch (\Throwable $e) { + throw new \DOMException('Invalid CSS selector: ' . $selectors, 0, $e); + } } - private function translate(string $expression): string - { - if ($this->registeredPrefixes === []) { - return $expression; + /** + * Returns the first descendant element matching the CSS selector, or null. + * + * @return \Dom\Element|null + */ + public function querySelector(string $selectors) { + $result = $this->querySelectorAll($selectors); + return $result->length === 0 ? null : $result->item(0); + } + + /** + * Returns the descendant elements matching the CSS selector. + * + * @return \Dom\NodeList<\Dom\Element> + * @throws \DOMException if the CSS selector cannot be translated + */ + public function querySelectorAll(string $selectors) { + $xpath = $this->cssXPath(); + if ($xpath === null) { + // No owner document (e.g. a detached node): empty result + return $this->getElementsByTagName('_'); } - foreach (array_keys($this->registeredPrefixes) as $prefix) { - // NCName-boundary safe: - $translated = preg_replace('/(?query($this->cssToXPath($selectors, './/'), $this); + } catch (\Throwable $e) { + throw $e instanceof \DOMException ? $e : new \DOMException('Invalid CSS selector: ' . $selectors, 0, $e); } - return $expression; } /** - * The native API throws upon an invalid expression, rather than returning `false`. + * Whether this element matches the given CSS selector. * - * @param string $expression - * @param \DOMNode|null $contextNode + * @throws \DOMException if the CSS selector cannot be translated */ - public function query($expression, $contextNode = null, $registerNodeNS = true): \DOMNodeList - { - $translated = $this->translate($expression); - $result = @parent::query($translated, $contextNode, $registerNodeNS); - if ($result === false) { - throw new \Exception('Invalid XPath expression: ' . $translated); + public function matches(string $selectors): bool { + $xpath = $this->cssXPath(); + if ($xpath === null) { + return false; } - return $result; + try { + $result = $xpath->query($this->cssToXPath($selectors, 'descendant-or-self::')); + } catch (\Throwable $e) { + throw $e instanceof \DOMException ? $e : new \DOMException('Invalid CSS selector: ' . $selectors, 0, $e); + } + for ($i = 0; $i < $result->length; $i++) { + $candidate = $result->item($i); + if ($candidate !== null && $candidate->isSameNode($this)) { + return true; + } + } + return false; + } +} + +/** + * Equivalent of native `Dom\Element` (PHP 8.4+), + * registered as the element class of `HTMLDocument` and `XMLDocument` below. + */ +final class Element extends \DOMElement +{ + use CssSelectors; + + /** + * Native `Dom\Element::getAttribute()` return null when the attribute is missing + */ + #[\ReturnTypeWillChange] + public function getAttribute(string $qualifiedName): ?string + { + return $this->hasAttribute($qualifiedName) ? parent::getAttribute($qualifiedName) : null; } } @@ -82,6 +133,14 @@ public function query($expression, $contextNode = null, $registerNodeNS = true): */ final class HTMLDocument extends \DOMDocument { + use CssSelectors; + + public function __construct() + { + parent::__construct(); + $this->registerNodeClass(\DOMElement::class, Element::class); + } + /** * @return static */ @@ -109,14 +168,14 @@ public static function createFromString(string $source, ?int $options = null, ?s * Normalise to `attr=""` for parity. * It also emits end tags for void elements (e.g. ``). * - * @return string|false + * Returns `''` instead of `false` in case of error, for parity with the + * native `Dom\HTMLDocument::saveHTML()`, which always returns a string. */ - #[\ReturnTypeWillChange] - public function saveHTML(?\DOMNode $node = null) + public function saveHTML(?\DOMNode $node = null): string { $html = parent::saveHTML($node); if ($html === false) { - return false; + return ''; } // Drop void-element end tags emitted for e.g. ``: $html = (string) preg_replace('#(<(area|base|br|col|embed|hr|img|input|link|meta|param|source|track|wbr)\b[^>]*?>)#i', '$1', $html); @@ -140,4 +199,82 @@ public function saveHTML(?\DOMNode $node = null) } } +final class XMLDocument extends \DOMDocument +{ + use CssSelectors; + + public function __construct() + { + parent::__construct(); + $this->registerNodeClass(\DOMElement::class, Element::class); + } + + /** + * Maps `\Dom\XMLDocument::createFromString()` onto `\DOMDocument::loadXML()`. + * Like the native implementation, throws upon a malformed XML document. + * + * @return static + */ + public static function createFromString(string $source, ?int $options = null, ?string $overrideEncoding = null) + { + $document = new self(); + if (@$document->loadXML($source, ($options ?? 0) | LIBXML_NOERROR | LIBXML_NOWARNING) !== true + || $document->documentElement === null) { + throw new \ValueError('Argument #1 ($source) must be a valid XML'); + } + return $document; + } +} + +/** + * On the legacy path, the parser never puts elements in any namespace, + * so rewrite queries written for the namespaced PHP 8.4 parser (e.g. `xh:body//xh:img`). + */ +final class XPath extends \DOMXPath +{ + /** @var array */ + private $registeredPrefixes = []; + + /** + * @param string $prefix + * @param string $namespaceURI + */ + public function registerNamespace($prefix, $namespaceURI): bool + { + $this->registeredPrefixes[$prefix] = true; + return parent::registerNamespace($prefix, $namespaceURI); + } + + private function translate(string $expression): string + { + if ($this->registeredPrefixes === []) { + return $expression; + } + foreach (array_keys($this->registeredPrefixes) as $prefix) { + // NCName-boundary safe: + $translated = preg_replace('/(?translate($expression); + $result = @parent::query($translated, $contextNode, $registerNodeNS); + if ($result === false) { + throw new \Exception('Invalid XPath expression: ' . $translated); + } + return $result; + } +} + endif; From 0e41dbbe729cd85c64922a5f0d79372384faabae Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sun, 15 Nov 2026 23:33:16 +0100 Subject: [PATCH 07/10] Fix PHP 7.4 --- compat/dom-polyfill.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/compat/dom-polyfill.php b/compat/dom-polyfill.php index c031f3dc8..74c0006bf 100644 --- a/compat/dom-polyfill.php +++ b/compat/dom-polyfill.php @@ -120,9 +120,10 @@ final class Element extends \DOMElement /** * Native `Dom\Element::getAttribute()` return null when the attribute is missing + * @return string|null */ #[\ReturnTypeWillChange] - public function getAttribute(string $qualifiedName): ?string + public function getAttribute($qualifiedName) { return $this->hasAttribute($qualifiedName) ? parent::getAttribute($qualifiedName) : null; } From 16a79f3e7031d896a18a0b6db61055551a46c62c Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Mon, 16 Nov 2026 00:25:02 +0100 Subject: [PATCH 08/10] Fix some encoding issues --- compat/dom-polyfill.php | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/compat/dom-polyfill.php b/compat/dom-polyfill.php index 74c0006bf..774c207b9 100644 --- a/compat/dom-polyfill.php +++ b/compat/dom-polyfill.php @@ -148,10 +148,12 @@ public function __construct() public static function createFromString(string $source, ?int $options = null, ?string $overrideEncoding = null) { $document = new self(); - $options = ($options ?? 0) | LIBXML_NOERROR | LIBXML_NOWARNING; + $options = ($options ?? 0) | LIBXML_NOERROR | LIBXML_NOWARNING | LIBXML_HTML_NODEFDTD; - if ($source !== '' && !preg_match('#<(?:meta|\?xml)[^>]*?(?:charset|encoding)\\s*=#i', $source)) { - // If the source itself declares an encoding, let the parser honour it, otherwise UTF-8: + // If the source itself declares an encoding, let the parser honour it, otherwise UTF-8. + $injectEncoding = $source !== '' && strncmp($source, "\xEF\xBB\xBF", 3) !== 0 + && !preg_match('#<(?:meta|\?xml)[^>]*?(?:charset|encoding)\\s*=#i', $source); + if ($injectEncoding) { $source = '' . $source; } @@ -162,6 +164,16 @@ public static function createFromString(string $source, ?int $options = null, ?s // the native API silently creates an empty document. } + if ($injectEncoding) { + // Remove the injected declaration, which would otherwise be serialised + foreach ($document->childNodes as $child) { + if ($child instanceof \DOMProcessingInstruction && $child->target === 'xml') { + $document->removeChild($child); + break; + } + } + } + return $document; } @@ -174,7 +186,17 @@ public static function createFromString(string $source, ?int $options = null, ?s */ public function saveHTML(?\DOMNode $node = null): string { - $html = parent::saveHTML($node); + if ($node === null && in_array(strtolower($this->encoding ?? 'utf-8'), ['utf-8', 'utf8'], true)) { + // For a whole document, the legacy serialiser only knows the charset from ``, + // and otherwise writes non-ASCII characters as HTML entities, also inside `