[+]: work on phpstan reported issues :)

... before a new release goes live.

Author: voku

.github/workflows/ci.yml

@@ -74,10 +74,9 @@ jobs:
           php vendor/bin/phpunit -c phpunit.xml --coverage-clover=build/logs/clover.xml
 
       - name: Run phpstan
-        continue-on-error: true
         if: ${{ matrix.php == '8.3' }}
         run: |
-          php vendor/bin/phpstan analyse
+          php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
 
       - name: Upload coverage results to Coveralls
         continue-on-error: true

CHANGELOG

@@ -1,19 +1,18 @@
 [PHP Simple HTML Dom - upcoming]
 
-[PHP Simple HTML Dom v5.0.0 - 2026-04-21]
+[PHP Simple HTML Dom v5.0.0 - upcoming]
 1: BREAKING: require PHP >= 7.1.0 and drop PHP 7.0 support
-2: BREAKING / compatibility: nested "find*()" calls now return live, scoped nodes from the original DOM; mutating nested results (e.g. via "delete()" / "remove()") now changes the source document instead of a detached lookup result
-3: supported / tested PHP versions now cover PHP 7.1 - 8.4
-4: update runtime selector support to "symfony/css-selector": ~3.0 || ~4.0 || ~5.0 || ~6.0 || ~7.0 || ~8.0
-5: update dev / CI tooling for newer runtimes, including PHPUnit 8 support, modern phpunit.xml coverage config, and refreshed GitHub Actions / Travis matrices
-6: "SelectorConverter" -> add support for leading combinators (>, +, ~) and compound text / comment selectors, and improve selector cache / validation handling
-7: "HtmlDomParser" / "AbstractDomParser" -> replace invalid helper placeholder element names and fix PHP < 8 node-backed serialization / libxml newline issues, including script placeholder handling
-8: "HtmlDomParser" -> improve plaintext extraction (exclude style-comment content, simplify XPath handling, use array + implode())
-9: add "remove()" + null-returning query helpers ("findOneOrNull()" / "findMultiOrNull()") and fix nested / blank helper behavior
-10: fix nested XPath scoping, nested delete / serialization edge cases, paragraph wrapper handling, and empty SVG data uris inside style tags
-11: add broader regression coverage for Blade directives / conditionals, XML / RSS parsing, selector edge cases, serialization, PHPUnit 8 assertions, and PHP 8.5-safe reflection usage
-12: simplify export usage to "findMulti() + setAttribute()"
-13: fix -> preserve attributes and support nested node renames in "SimpleHtmlDom" / "SimpleXmlDom"
+2: BREAKING / compatibility: nested "find*()" now returns live scoped nodes, so mutating nested results via "delete()" / "remove()" updates the original DOM
+3: add support for "symfony/css-selector": ~8.0
+4: add "findOneOrNull()" + "findMultiOrNull()"
+5: add "remove()" (alias) and update public API docs in "README_API.md"
+6: "SelectorConverter" -> add support for leading combinators (>, +, ~) and text / comment selectors
+7: "HtmlDomParser" -> fix PHP < 8 node serialization, script placeholder handling, plaintext extraction, paragraph wrapper handling, and empty SVG data uris inside style tags
+8: "HtmlDomParser" / "XmlDomParser" -> support "\DOMDocument" input and reject directory paths in "*load*File()"
+9: "SimpleHtmlDom" / "SimpleXmlDom" -> fix "val()" for "<select>", multi-select arrays, and checkbox / radio arrays
+10: "SimpleXmlDom" -> fix "nextNonWhitespaceSibling()" and "parentNode()" edge cases
+11: fix nested XPath scoping, nested delete / serialization, and nested node rename handling
+12: refresh CI / PHPUnit / PHPStan setup and expand regression coverage
 
 [PHP Simple HTML Dom v4.8.10 - 2024-07-03]
 1: fix -> "HtmlDomHelper::mergeHtmlAttributes()" with zero values

README.md

@@ -12,10 +12,11 @@
 A HTML DOM parser written in PHP - let you manipulate HTML in a very easy way!
 This is a fork of [PHP Simple HTML DOM Parser project](http://simplehtmldom.sourceforge.net/) but instead of string manipulation we use DOMDocument and modern php classes like "Symfony CssSelector".
 
-- PHP 7.1+ & 8.x Support
+- PHP 7.1+ runtime support, tested on PHP 7.1 - 8.4
 - PHP-FIG Standard
 - Composer & PSR-4 support
 - PHPUnit testing via GitHub Actions
+- PHPStan-clean source tree on the current release branch
 - PHP-Quality testing via SensioLabsInsight
 - UTF-8 Support (more support via "voku/portable-utf8")
 - Invalid HTML Support (partly ...)
@@ -30,6 +31,12 @@ composer require voku/simple_html_dom
 composer require voku/portable-utf8 # if you need e.g. UTF-8 fixed output
 ```
 
+### Upgrade notes for v5.0.0
+
+- PHP 7.0 is no longer supported; the package now requires PHP 7.1 or newer.
+- Nested `find*()` calls now return live nodes scoped to the original DOM, so mutating nested results updates the source document.
+- See the [CHANGELOG](https://github.com/voku/simple_html_dom/blob/master/CHANGELOG) for the full release notes.
+
 ### Quick Start
 
 ```php

README_API.md

@@ -1,4 +1,4 @@
-[//]: # (AUTO-GENERATED BY "PHP README Helper": base file -> docs/api.md)
+[//]: # (AUTO-GENERATED BY "PHP README Helper": base file -> build/docs/api.md)
 # :scroll: Simple Html Dom Parser for PHP 
 
 ### DomParser API
@@ -31,12 +31,12 @@
 ### SimpleHtmlDomNode (group of dom elements) API
 
 <p id="voku-php-readme-class-methods"></p><table><tr><td><a href="#count-int">count</a>
-</td><td><a href="#findstring-selector-int-idx-simplehtmldomnodesimplehtmldomnodenull">find</a>
+</td><td><a href="#findstring-selector-int-idx-simplehtmldominterfacesimplehtmldomnodeinterfacesimplehtmldominterfacenull">find</a>
 </td><td><a href="#findmultistring-selector-simplehtmldominterfacesimplehtmldomnodeinterfacesimplehtmldominterface">findMulti</a>
 </td><td><a href="#findmultiorfalsestring-selector-falsesimplehtmldominterfacesimplehtmldomnodeinterfacesimplehtmldominterface">findMultiOrFalse</a>
 </td></tr><tr><td><a href="#findmultiornullstring-selector-nullsimplehtmldominterfacesimplehtmldomnodeinterfacesimplehtmldominterface">findMultiOrNull</a>
-</td><td><a href="#findonestring-selector-simplehtmldomnodeinterface">findOne</a>
-</td><td><a href="#findoneorfalsestring-selector-falsesimplehtmldomnodeinterface">findOneOrFalse</a>
+</td><td><a href="#findonestring-selector-simplehtmldominterfacesimplehtmldomnodeinterfacesimplehtmldominterface">findOne</a>
+</td><td><a href="#findoneorfalsestring-selector-falsesimplehtmldominterface">findOneOrFalse</a>
 </td><td><a href="#findoneornullstring-selector-nullsimplehtmldominterface">findOneOrNull</a>
 </td></tr><tr><td><a href="#getiterator">getIterator</a>
 </td><td><a href="#innerhtml-string">innerHtml</a>
@@ -48,7 +48,7 @@
 ### SimpleHtmlDom (single dom element) API
 
 <p id="voku-php-readme-class-methods"></p><table><tr><td><a href="#childnodesint-idx-simplehtmldominterfacesimplehtmldominterfacesimplehtmldomnodeinterfacenull">childNodes</a>
-</td><td><a href="#delete-mixed">delete</a>
+</td><td><a href="#delete-void">delete</a>
 </td><td><a href="#findstring-selector-intnull-idx-simplehtmldominterfacesimplehtmldominterfacesimplehtmldomnodeinterfacesimplehtmldominterface">find</a>
 </td><td><a href="#findmultistring-selector-simplehtmldominterfacesimplehtmldomnodeinterfacesimplehtmldominterface">findMulti</a>
 </td></tr><tr><td><a href="#findmultiorfalsestring-selector-falsesimplehtmldominterfacesimplehtmldomnodeinterfacesimplehtmldominterface">findMultiOrFalse</a>
@@ -79,7 +79,7 @@
 </td><td><a href="#parentnode-simplehtmldominterfacenull">parentNode</a>
 </td><td><a href="#previousnonwhitespacesibling-simplehtmldominterfacenull">previousNonWhitespaceSibling</a>
 </td><td><a href="#previoussibling-simplehtmldominterfacenull">previousSibling</a>
-</td></tr><tr><td><a href="#remove-mixed">remove</a>
+</td></tr><tr><td><a href="#remove-void">remove</a>
 </td><td><a href="#removeattributestring-name-simplehtmldominterface">removeAttribute</a>
 </td><td><a href="#removeattributes-simplehtmldominterface">removeAttributes</a>
 </td><td><a href="#setattributestring-name-stringnull-value-bool-strictemptyvaluecheck-simplehtmldominterface">setAttribute</a>
@@ -390,7 +390,7 @@ __nothing__
 
 --------
 
-## find(string $selector, int $idx): SimpleHtmlDomNode|\SimpleHtmlDomNode[]|null
+## find(string $selector, int $idx): SimpleHtmlDomInterface|\SimpleHtmlDomNodeInterface<\SimpleHtmlDomInterface>|null
 <a href="#voku-php-readme-class-methods">↑</a>
 Find list of nodes with a CSS selector.
 
@@ -399,7 +399,7 @@ Find list of nodes with a CSS selector.
 - `int $idx`
 
 **Return:**
-- `\SimpleHtmlDomNode|\SimpleHtmlDomNode[]|null`
+- `\SimpleHtmlDomInterface|\SimpleHtmlDomNodeInterface<\SimpleHtmlDomInterface>|null`
 
 --------
 
@@ -439,27 +439,27 @@ Find nodes with a CSS selector or null, if no element is found.
 
 --------
 
-## findOne(string $selector): SimpleHtmlDomNodeInterface
+## findOne(string $selector): SimpleHtmlDomInterface|\SimpleHtmlDomNodeInterface<\SimpleHtmlDomInterface>
 <a href="#voku-php-readme-class-methods">↑</a>
 Find one node with a CSS selector.
 
 **Parameters:**
 - `string $selector`
 
 **Return:**
-- `\SimpleHtmlDomNodeInterface`
+- `\SimpleHtmlDomInterface|\SimpleHtmlDomNodeInterface<\SimpleHtmlDomInterface>`
 
 --------
 
-## findOneOrFalse(string $selector): false|\SimpleHtmlDomNodeInterface
+## findOneOrFalse(string $selector): false|\SimpleHtmlDomInterface
 <a href="#voku-php-readme-class-methods">↑</a>
 Find one node with a CSS selector or false, if no element is found.
 
 **Parameters:**
 - `string $selector`
 
 **Return:**
-- `false|\SimpleHtmlDomNodeInterface`
+- `false|\SimpleHtmlDomInterface`
 
 --------
 
@@ -548,15 +548,15 @@ Returns children of node.
 
 --------
 
-## delete(): mixed
+## delete(): void
 <a href="#voku-php-readme-class-methods">↑</a>
-Delete
+Remove this node from the DOM.
 
 **Parameters:**
 __nothing__
 
 **Return:**
-- `mixed`
+- `void`
 
 --------
 
@@ -929,15 +929,15 @@ __nothing__
 
 --------
 
-## remove(): mixed
+## remove(): void
 <a href="#voku-php-readme-class-methods">↑</a>
 Remove this node from the DOM (alias for delete).
 
 **Parameters:**
 __nothing__
 
 **Return:**
-- `mixed`
+- `void`
 
 --------
 

phpstan.neon

@@ -3,29 +3,3 @@ parameters:
     level: 8
     paths:
         - %currentWorkingDirectory%/src/
-    ignoreErrors:
-        ## todo?
-        - '#type specified in iterable type#'
-        - '#Unsafe usage of new static#'
-        - '#extends generic class#'
-        - '#return type with generic#'
-        - '#DOMNode\|null#'
-        - '#function call_user_func_array expects callable#'
-        ## old stuff
-        - '#Method voku\\helper\\HtmlDomParser::findOne\(\) should return#'
-        - '#Method voku\\helper\\HtmlDomParser::findMulti\(\) should return#'
-        - '#Method voku\\helper\\HtmlDomParser::findOneOrFalse\(\) should return#'
-        - '#Method voku\\helper\\HtmlDomParser::findMultiOrFalse\(\) should return#'
-        - '#Method voku\\helper\\SimpleHtmlDomNode::findOne\(\) should return#'
-        - '#Method voku\\helper\\SimpleHtmlDomNode::findMulti\(\) should return#'
-        - '#Method voku\\helper\\SimpleHtmlDomNode::findOneOrFalse\(\) should return#'
-        - '#Method voku\\helper\\SimpleHtmlDomNode::findMultiOrFalse\(\) should return#'
-        - '#Method voku\\helper\\XmlDomParser::findOne\(\) should return#'
-        - '#Method voku\\helper\\XmlDomParser::findMulti\(\) should return#'
-        - '#Method voku\\helper\\XmlDomParser::findOneOrFalse\(\) should return#'
-        - '#Method voku\\helper\\XmlDomParser::findMultiOrFalse\(\) should return#'
-        - '#Method voku\\helper\\SimpleXmlDomNode::findOne\(\) should return#'
-        - '#Method voku\\helper\\SimpleXmlDomNode::findMulti\(\) should return#'
-        - '#Method voku\\helper\\SimpleXmlDomNode::findOneOrFalse\(\) should return#'
-        - '#Method voku\\helper\\SimpleXmlDomNode::findMultiOrFalse\(\) should return#'
-        - '#method voku\\helper\\SimpleHtmlDomNodeBlank::findOne\(\) should be compatible with return type#'

src/voku/helper/AbstractDomParser.php

@@ -24,7 +24,7 @@ abstract class AbstractDomParser implements DomParserInterface
     protected static $domHtmlSpecialScriptHelper = 'simplevokuspecialscript';
 
     /**
-     * @var array
+     * @var array<string, array<int, string>>
      */
     protected static $domBrokenReplaceHelper = [];
 
@@ -59,7 +59,7 @@ abstract class AbstractDomParser implements DomParserInterface
     /**
      * @var callable|null
      *
-     * @phpstan-var null|callable(\voku\helper\XmlDomParser|\voku\helper\HtmlDomParser): void
+     * @phpstan-var null|callable(array{0: \voku\helper\XmlDomParser|\voku\helper\HtmlDomParser}): void
      */
     protected static $callback;
 
@@ -125,8 +125,8 @@ protected function registerDynamicDomBrokenReplaceHelper(string $original, strin
     protected $encoding = 'UTF-8';
 
     /**
-     * @param string $name
-     * @param array  $arguments
+     * @param string       $name
+     * @param array<mixed> $arguments
      *
      * @return bool|mixed
      */
@@ -135,15 +135,17 @@ public function __call($name, $arguments)
         $name = \strtolower($name);
 
         if (isset(self::$functionAliases[$name])) {
-            return \call_user_func_array([$this, self::$functionAliases[$name]], $arguments);
+            $method = self::$functionAliases[$name];
+
+            return $this->{$method}(...$arguments);
         }
 
         throw new \BadMethodCallException('Method does not exist: ' . $name);
     }
 
     /**
-     * @param string $name
-     * @param array  $arguments
+     * @param string       $name
+     * @param array<mixed> $arguments
      *
      * @throws \BadMethodCallException
      * @throws \RuntimeException
@@ -398,7 +400,7 @@ public function save(string $filepath = ''): string
     /**
      * @param callable $functionName
      *
-     * @phpstan-param callable(\voku\helper\XmlDomParser|\voku\helper\HtmlDomParser): void $functionName
+     * @phpstan-param callable(array{0: \voku\helper\XmlDomParser|\voku\helper\HtmlDomParser}): void $functionName
      *
      * @return void
      */

src/voku/helper/AbstractSimpleHtmlDom.php

@@ -7,7 +7,7 @@
 abstract class AbstractSimpleHtmlDom
 {
     /**
-     * @var array
+     * @var array<string, string>
      */
     protected static $functionAliases = [
         'children'     => 'childNodes',
@@ -43,8 +43,8 @@ abstract class AbstractSimpleHtmlDom
     private $classListCache;
 
     /**
-     * @param string $name
-     * @param array  $arguments
+     * @param string       $name
+     * @param array<mixed> $arguments
      *
      * @throws \BadMethodCallException
      *
@@ -55,7 +55,9 @@ public function __call($name, $arguments)
         $name = \strtolower($name);
 
         if (isset(self::$functionAliases[$name])) {
-            return \call_user_func_array([$this, self::$functionAliases[$name]], $arguments);
+            $method = self::$functionAliases[$name];
+
+            return $this->{$method}(...$arguments);
         }
 
         throw new \BadMethodCallException('Method does not exist');
@@ -64,7 +66,7 @@ public function __call($name, $arguments)
     /**
      * @param string $name
      *
-     * @return SimpleHtmlAttributes|string|string[]|null
+     * @return array<int, string>|SimpleHtmlAttributes|string|null
      */
     public function __get($name)
     {
@@ -90,7 +92,10 @@ public function __get($name)
                 return $this->getAllAttributes();
             case 'classlist':
                 if ($this->classListCache === null) {
-                    $this->classListCache = new SimpleHtmlAttributes($this->node ?? null, 'class');
+                    $this->classListCache = new SimpleHtmlAttributes(
+                        $this->node instanceof \DOMElement ? $this->node : null,
+                        'class'
+                    );
                 }
 
                 return $this->classListCache;
@@ -151,24 +156,28 @@ public function __isset($name)
      * @param string $name
      * @param mixed  $value
      *
-     * @return SimpleHtmlDomInterface|null
+     * @return void
      */
-    public function __set($name, $value)
+    public function __set($name, $value): void
     {
         $nameOrig = $name;
         $name = \strtolower($name);
 
         switch ($name) {
             case 'outerhtml':
             case 'outertext':
-                return $this->replaceNodeWithString($value);
+                $this->replaceNodeWithString($value);
+                return;
             case 'innertext':
             case 'innerhtml':
-                return $this->replaceChildWithString($value);
+                $this->replaceChildWithString($value);
+                return;
             case 'innerhtmlkeep':
-                return $this->replaceChildWithString($value, false);
+                $this->replaceChildWithString($value, false);
+                return;
             case 'plaintext':
-                return $this->replaceTextWithString($value);
+                $this->replaceTextWithString($value);
+                return;
             case 'classlist':
                 $name = 'class';
                 $nameOrig = 'class';
@@ -182,12 +191,11 @@ public function __set($name, $value)
 
                     if ($value !== null) {
                         $this->node->{$nameOrig} = $value;
-
-                        return $this->node->{$nameOrig};
+                        return;
                     }
                 }
 
-                return $this->setAttribute($name, $value);
+                $this->setAttribute($name, $value);
         }
     }