From fae4e788450a0d6ff9ef619d67b2b77f8c5d1bd2 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 16 Mar 2024 17:57:49 +0100
Subject: [PATCH 01/17] Fix missing return value in grabArticle

Not sure if this is expected but at least it works the same as before.
---
 src/Readability.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Readability.php b/src/Readability.php
index 290cc28..b8c8898 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -1044,7 +1044,7 @@ protected function grabArticle(?\DOMElement $page = null)
 
             foreach ($ancestors as $level => $ancestor) {
                 if (!$ancestor->nodeName || !$ancestor->parentNode) {
-                    return;
+                    return false;
                 }
 
                 if (!$ancestor->hasAttribute('readability')) {

From 4f5360df90b7c3def1309af453ed379366e04422 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 16 Mar 2024 18:33:56 +0100
Subject: [PATCH 02/17] Use helpers for content score manipulation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`DOMAttr::$value` must be a `string`.

Let’s add helpers for manipulating the `readability` attribute
so that we do not have to keep casting it from and to `string`
in order to appease `strict_types`.
---
 src/Readability.php | 59 ++++++++++++++++++++++++++++++---------------
 1 file changed, 40 insertions(+), 19 deletions(-)

diff --git a/src/Readability.php b/src/Readability.php
index b8c8898..9c909cb 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -618,7 +618,7 @@ public function cleanConditionally(\DOMElement $e, string $tag): void
         for ($i = $curTagsLength - 1; $i >= 0; --$i) {
             $node = $tagsList->item($i);
             $weight = $this->getWeight($node);
-            $contentScore = ($node->hasAttribute('readability')) ? (int) $node->getAttribute('readability') : 0;
+            $contentScore = self::getContentScore($node);
             $this->logger->debug('Start conditional cleaning of ' . $node->getNodePath() . ' (class=' . $node->getAttribute('class') . '; id=' . $node->getAttribute('id') . ')' . (($node->hasAttribute('readability')) ? (' with score ' . $node->getAttribute('readability')) : ''));
 
             // XXX Incomplete implementation
@@ -834,29 +834,26 @@ protected function initializeNode(\DOMElement $node): void
             return;
         }
 
-        $readability = $this->dom->createAttribute('readability');
-        // this is our contentScore
-        $readability->value = 0;
-        $node->setAttributeNode($readability);
+        $contentScore = 0;
 
         // using strtoupper just in case
         switch (strtoupper($node->tagName)) {
             case 'ARTICLE':
-                $readability->value += 15;
+                $contentScore += 15;
                 // no break
             case 'DIV':
-                $readability->value += 5;
+                $contentScore += 5;
                 break;
             case 'PRE':
             case 'CODE':
             case 'TD':
             case 'BLOCKQUOTE':
             case 'FIGURE':
-                $readability->value += 3;
+                $contentScore += 3;
                 break;
             case 'SECTION':
                 // often misused
-                // $readability->value += 2;
+                // $contentScore += 2;
                 break;
             case 'OL':
             case 'UL':
@@ -864,7 +861,7 @@ protected function initializeNode(\DOMElement $node): void
             case 'DD':
             case 'DT':
             case 'LI':
-                $readability->value -= 3;
+                $contentScore -= 3;
                 break;
             case 'ASIDE':
             case 'FOOTER':
@@ -875,7 +872,7 @@ protected function initializeNode(\DOMElement $node): void
             case 'TEXTAREA':
             case 'INPUT':
             case 'NAV':
-                $readability->value -= 3;
+                $contentScore -= 3;
                 break;
             case 'H1':
             case 'H2':
@@ -885,11 +882,15 @@ protected function initializeNode(\DOMElement $node): void
             case 'H6':
             case 'TH':
             case 'HGROUP':
-                $readability->value -= 5;
+                $contentScore -= 5;
                 break;
         }
 
-        $readability->value += $this->getWeight($node);
+        $contentScore += $this->getWeight($node);
+
+        $readability = $this->dom->createAttribute('readability');
+        $readability->value = (string) $contentScore;
+        $node->setAttributeNode($readability);
     }
 
     /**
@@ -1059,7 +1060,8 @@ protected function grabArticle(?\DOMElement $page = null)
                 } else {
                     $scoreDivider = $level * 3;
                 }
-                $ancestor->getAttributeNode('readability')->value += $contentScore / $scoreDivider;
+
+                self::updateContentScore($ancestor, fn ($prevScore) => $prevScore + $contentScore / $scoreDivider);
             }
         }
 
@@ -1074,7 +1076,7 @@ protected function grabArticle(?\DOMElement $page = null)
                 $node = $candidates->item($c);
                 // node should be readable but not inside of an article otherwise it's probably non-readable block
                 if ($node->hasAttribute('readability') && (int) $node->getAttributeNode('readability')->value < 40 && ($node->parentNode ? 0 !== strcasecmp($node->parentNode->tagName, 'article') : true)) {
-                    $this->logger->debug('Removing unlikely candidate (using note) ' . $node->getNodePath() . ' by "' . $node->tagName . '" with readability ' . ($node->hasAttribute('readability') ? (int) $node->getAttributeNode('readability')->value : 0));
+                    $this->logger->debug('Removing unlikely candidate (using note) ' . $node->getNodePath() . ' by "' . $node->tagName . '" with readability ' . self::getContentScore($node));
                     $node->parentNode->removeChild($node);
                 }
             }
@@ -1098,14 +1100,13 @@ protected function grabArticle(?\DOMElement $page = null)
                 // Scale the final candidates score based on link density. Good content should have a
                 // relatively small link density (5% or less) and be mostly unaffected by this operation.
                 // If not for this we would have used XPath to find maximum @readability.
-                $readability = $item->getAttributeNode('readability');
-                $readability->value = round($readability->value * (1 - $this->getLinkDensity($item)), 0, \PHP_ROUND_HALF_UP);
+                self::updateContentScore($item, fn ($prevScore) => round($prevScore * (1 - $this->getLinkDensity($item)), 0, \PHP_ROUND_HALF_UP));
 
                 for ($t = 0; $t < 5; ++$t) {
                     $aTopCandidate = $topCandidates[$t];
 
-                    if (!$aTopCandidate || $readability->value > (int) $aTopCandidate->getAttribute('readability')) {
-                        $this->logger->debug('Candidate: ' . $item->getNodePath() . ' (' . $item->getAttribute('class') . ':' . $item->getAttribute('id') . ') with score ' . $readability->value);
+                    if (!$aTopCandidate || self::getContentScore($item) > self::getContentScore($aTopCandidate)) {
+                        $this->logger->debug('Candidate: ' . $item->getNodePath() . ' (' . $item->getAttribute('class') . ':' . $item->getAttribute('id') . ') with score ' . self::getContentScore($item));
                         array_splice($topCandidates, $t, 0, [$item]);
                         if (\count($topCandidates) > 5) {
                             array_pop($topCandidates);
@@ -1371,6 +1372,26 @@ protected function reinitBody(): void
         }
     }
 
+    /**
+     * Updates the content score for the given element using the provided function.
+     *
+     * @param callable(float): float $f
+     */
+    private static function updateContentScore(\DOMElement $element, callable $f): void
+    {
+        $readabilityAttr = $element->getAttributeNode('readability');
+        $prevScore = (float) $readabilityAttr->value;
+        $readabilityAttr->value = (string) $f($prevScore);
+    }
+
+    /**
+     * Gets the content score for given element.
+     */
+    private static function getContentScore(\DOMElement $element): float
+    {
+        return $element->hasAttribute('readability') ? (float) $element->getAttribute('readability') : 0;
+    }
+
     /**
      * Load HTML in a DOMDocument.
      * Apply Pre filters

From 32267cb7b45ab79c0d4cff48610f21c8e255b0df Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Wed, 9 Oct 2024 08:51:02 +0200
Subject: [PATCH 03/17] Add type annotations to properties

To preserve BC, we are not using type hints for now.
---
 src/Readability.php       | 113 +++++++++++++++++++++++++++++++++-----
 tests/ReadabilityTest.php |   2 +-
 2 files changed, 100 insertions(+), 15 deletions(-)

diff --git a/src/Readability.php b/src/Readability.php
index 9c909cb..a0bb649 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -24,25 +24,60 @@ class Readability implements LoggerAwareInterface
     public const MIN_ARTICLE_LENGTH = 200;
     public const MIN_NODE_LENGTH = 80;
     public const MAX_LINK_DENSITY = 0.25;
+
+    /**
+     * @var bool
+     */
     public $convertLinksToFootnotes = false;
+
+    /**
+     * @var bool
+     */
     public $revertForcedParagraphElements = false;
+
+    /**
+     * @var ?\DOMElement
+     */
     public $articleTitle;
+
+    /**
+     * @var ?\DOMElement
+     */
     public $articleContent;
+
+    /**
+     * @var ?string
+     */
     public $original_html;
+
     /**
-     * @var \DOMDocument
+     * @var ?\DOMDocument
      */
     public $dom;
-    // optional - URL where HTML was retrieved
+
+    /**
+     * @var ?string URL where HTML was retrieved
+     */
     public $url = null;
-    // preserves more content (experimental)
+
+    /**
+     * @var bool preserves more content (experimental)
+     */
     public $lightClean = true;
-    // no more used, keept to avoid BC
+
+    /**
+     * @var bool no more used, keept to avoid BC
+     */
     public $debug = false;
+
+    /**
+     * @var bool
+     */
     public $tidied = false;
 
     /**
-     * All of the regular expressions in use within readability.
+     * @var array<string, string> All of the regular expressions in use within readability.
+     *
      * Defined up here so we don't instantiate them repeatedly in loops.
      */
     public $regexps = [
@@ -57,10 +92,18 @@ class Readability implements LoggerAwareInterface
         'hasContent' => '/\S$/',
         'isNotVisible' => '/display\s*:\s*none/',
     ];
+
+    /**
+     * @var array<string>
+     */
     public $defaultTagsToScore = ['section', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'td', 'pre'];
-    // The commented out elements qualify as phrasing content but tend to be
-    // removed by readability when put into paragraphs, so we ignore them here.
+
+    /**
+     * @var array<string>
+     */
     public $phrasingElements = [
+        // The commented out elements qualify as phrasing content but tend to be
+        // removed by readability when put into paragraphs, so we ignore them here.
         // "CANVAS", "IFRAME", "SVG", "VIDEO",
         'ABBR', 'AUDIO', 'B', 'BDO', 'BR', 'BUTTON', 'CITE', 'CODE', 'DATA',
         'DATALIST', 'DFN', 'EM', 'EMBED', 'I', 'IMG', 'INPUT', 'KBD', 'LABEL',
@@ -68,6 +111,10 @@ class Readability implements LoggerAwareInterface
         'RUBY', 'SAMP', 'SCRIPT', 'SELECT', 'SMALL', 'SPAN', 'STRONG', 'SUB',
         'SUP', 'TEXTAREA', 'TIME', 'VAR', 'WBR',
     ];
+
+    /**
+     * @var array<string, bool|string>
+     */
     public $tidy_config = [
         'tidy-mark' => false,
         'vertical-space' => false,
@@ -92,20 +139,55 @@ class Readability implements LoggerAwareInterface
         'output-encoding' => 'utf8',
         'hide-comments' => true,
     ];
-    // article domain regexp for calibration
+
+    /**
+     * @var ?string article domain regexp for calibration
+     */
     protected $domainRegExp = null;
+
+    /**
+     * @var ?\DOMElement
+     */
     protected $body = null;
-    // Cache the body HTML in case we need to re-use it later
+
+    /**
+     * @var ?string Cache the body HTML in case we need to re-use it later
+     */
     protected $bodyCache = null;
-    // 1 | 2 | 4;   // Start with all processing flags set.
-    protected $flags = 7;
-    // indicates whether we were able to extract or not
+
+    /**
+     * @var int-mask-of<self::FLAG_*> start with all processing flags set
+     */
+    protected $flags = self::FLAG_STRIP_UNLIKELYS | self::FLAG_WEIGHT_ATTRIBUTES | self::FLAG_CLEAN_CONDITIONALLY;
+
+    /**
+     * @var bool indicates whether we were able to extract or not
+     */
     protected $success = false;
+
+    /**
+     * @var LoggerInterface
+     */
     protected $logger;
+
+    /**
+     * @var string
+     */
     protected $parser;
+
+    /**
+     * @var string
+     */
     protected $html;
+
+    /**
+     * @var bool
+     */
     protected $useTidy;
-    // raw HTML filters
+
+    /**
+     * @var array<string, string> raw HTML filters
+     */
     protected $pre_filters = [
         // remove spans as we redefine styles and they're probably special-styled
         '!</?span[^>]*>!is' => '',
@@ -118,7 +200,10 @@ class Readability implements LoggerAwareInterface
         // replace fonts to spans
         '!<(/?)font[^>]*>!is' => '<\\1span>',
     ];
-    // output HTML filters
+
+    /**
+     * @var array<string, string> output HTML filters
+     */
     protected $post_filters = [
         // replace excessive br's
         '/<br\s*\/?>\s*<p/i' => '<p',
diff --git a/tests/ReadabilityTest.php b/tests/ReadabilityTest.php
index 8a29629..b09a97a 100644
--- a/tests/ReadabilityTest.php
+++ b/tests/ReadabilityTest.php
@@ -338,7 +338,7 @@ public function testAutoClosingIframeNotThrowingException(): void
         $oldErrorReporting = error_reporting(\E_ALL);
         $oldDisplayErrors = ini_set('display_errors', '1');
         // dummy function to be used to the next test
-        set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline) {
+        set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline): bool {
             throw new \Exception($errstr, $errno);
         });
 

From 9a0a088bc6bded8a5b6206c18aee760cb786a9e3 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Fri, 11 Oct 2024 09:47:35 +0200
Subject: [PATCH 04/17] Throw a BadMethodCallException calling
 get{Title,Content} uninitialized

This is bad state so it should not be a breaking change.
---
 src/Readability.php | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/Readability.php b/src/Readability.php
index a0bb649..9c1b983 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -249,6 +249,10 @@ public function setLogger(LoggerInterface $logger): void
      */
     public function getTitle()
     {
+        if (null === $this->articleTitle) {
+            throw new \BadMethodCallException('You need to successfully run Readability::init() before you can get title');
+        }
+
         return $this->articleTitle;
     }
 
@@ -259,6 +263,10 @@ public function getTitle()
      */
     public function getContent()
     {
+        if (null === $this->articleContent) {
+            throw new \BadMethodCallException('You need to successfully run Readability::init() before you can get content');
+        }
+
         return $this->articleContent;
     }
 

From 5040fc1587cde6c8d5ba9a9ee0e2ee13a3ea1cd3 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Fri, 11 Oct 2024 09:57:15 +0200
Subject: [PATCH 05/17] Use method param type hints instead of PHPDoc

Since we require PHP 7.4, contravariance in param types is supported,
so we do not need to worry about subclasses that widen the param type.
It will be only breaking in the unlikely case a subclass uses a type that
contradicts the PHPDoc type annotation and does not not extend `DOMNode`.

Also fix the type annotation since some invocations pass it a `DOMText`,
an arbitrary sibling/child `DOMNode` or even `null`.
---
 .php-cs-fixer.php   | 1 +
 src/Readability.php | 6 +-----
 2 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/.php-cs-fixer.php b/.php-cs-fixer.php
index 5f09a0c..b8b7aac 100644
--- a/.php-cs-fixer.php
+++ b/.php-cs-fixer.php
@@ -22,6 +22,7 @@
         'ordered_imports' => true,
         'php_unit_strict' => false,
         'phpdoc_order' => true,
+        'phpdoc_to_param_type' => true,
         // 'psr4' => true,
         'strict_comparison' => true,
         'strict_param' => true,
diff --git a/src/Readability.php b/src/Readability.php
index 9c1b983..0bc2ec8 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -546,12 +546,8 @@ public function prepArticle(\DOMNode $articleContent): void
     /**
      * Get the inner text of a node.
      * This also strips out any excess whitespace to be found.
-     *
-     * @param \DOMElement $e
-     * @param bool        $normalizeSpaces (default: true)
-     * @param bool        $flattenLines    (default: false)
      */
-    public function getInnerText($e, bool $normalizeSpaces = true, bool $flattenLines = false): string
+    public function getInnerText(?\DOMNode $e, bool $normalizeSpaces = true, bool $flattenLines = false): string
     {
         if (null === $e || !isset($e->textContent) || '' === $e->textContent) {
             return '';

From f610333040aaf2ef3ddac2d67f886b52ecb26679 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Fri, 11 Oct 2024 23:00:43 +0200
Subject: [PATCH 06/17] Add @var casts for XPath queries

Because PHPStan does not currently analyze XPath expressions, we need to use a @var cast:
https://phpstan.org/writing-php-code/phpdocs-basics#inline-%40var

These are list of elements since asterisk wildcard only selects elements:
https://www.w3.org/TR/1999/REC-xpath-19991116/#path-abbrev
---
 src/Readability.php | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/Readability.php b/src/Readability.php
index 0bc2ec8..9bf62c0 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -474,6 +474,7 @@ public function prepArticle(\DOMNode $articleContent): void
         }
 
         // Remove service data-candidate attribute.
+        /** @var \DOMNodeList<\DOMElement> */
         $elems = $xpath->query('.//*[@data-candidate]', $articleContent);
         foreach ($elems as $elem) {
             $elem->removeAttribute('data-candidate');
@@ -1159,6 +1160,7 @@ protected function grabArticle(?\DOMElement $page = null)
          * This is faster to do before scoring but safer after.
          */
         if ($this->flagIsActive(self::FLAG_STRIP_UNLIKELYS) && $xpath) {
+            /** @var \DOMNodeList<\DOMElement> */
             $candidates = $xpath->query('.//*[(self::footer and count(//footer)<2) or (self::aside and count(//aside)<2)]', $page->documentElement);
 
             for ($c = $candidates->length - 1; $c >= 0; --$c) {
@@ -1180,6 +1182,7 @@ protected function grabArticle(?\DOMElement $page = null)
         $topCandidates = array_fill(0, 5, null);
         if ($xpath) {
             // Using array of DOMElements after deletion is a path to DOOMElement.
+            /** @var \DOMNodeList<\DOMElement> */
             $candidates = $xpath->query('.//*[@data-candidate]', $page->documentElement);
             $this->logger->debug('Candidates: ' . $candidates->length);
 

From 1226daa8f8584dd6623f936b413599faaf1ae750 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 16 Mar 2024 21:51:43 +0100
Subject: [PATCH 07/17] Use JSLikeHTMLElement in type hints

We use `DOMDocument::registerNodeClass()` to make DOM methods return
`JSLikeHTMLElement` instead of `DOMElement`. Unfortunately, it is not
possible for PHPStan to detect that so we need to cast it ourselves:
https://github.com/phpstan/phpstan/discussions/10748
We may want to deprecate it in the future just to get rid of this mess.

Also add PHPStan stubs for DOM classes so that we do not need to cast everything.
It is fine to do that globally as we only ever use DOM with `JSLikeHTMLElement` registered.

This patch also allows us to get rid of the assertions in tests.
---
 phpstan.dist.neon         |  3 +++
 src/Readability.php       | 18 ++++++++---------
 stubs/dom.stub            | 36 ++++++++++++++++++++++++++++++++++
 tests/ReadabilityTest.php | 41 ---------------------------------------
 4 files changed, 48 insertions(+), 50 deletions(-)
 create mode 100644 stubs/dom.stub

diff --git a/phpstan.dist.neon b/phpstan.dist.neon
index 7e5d5d8..95b916d 100644
--- a/phpstan.dist.neon
+++ b/phpstan.dist.neon
@@ -8,6 +8,9 @@ parameters:
     bootstrapFiles:
         - vendor/bin/.phpunit/phpunit/vendor/autoload.php
 
+    stubFiles:
+        - stubs/dom.stub
+
 includes:
     - vendor/phpstan/phpstan-phpunit/extension.neon
     - vendor/phpstan/phpstan-phpunit/rules.neon
diff --git a/src/Readability.php b/src/Readability.php
index 9bf62c0..9f6f87f 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -36,12 +36,12 @@ class Readability implements LoggerAwareInterface
     public $revertForcedParagraphElements = false;
 
     /**
-     * @var ?\DOMElement
+     * @var ?JSLikeHTMLElement
      */
     public $articleTitle;
 
     /**
-     * @var ?\DOMElement
+     * @var ?JSLikeHTMLElement
      */
     public $articleContent;
 
@@ -245,7 +245,7 @@ public function setLogger(LoggerInterface $logger): void
     /**
      * Get article title element.
      *
-     * @return \DOMElement
+     * @return JSLikeHTMLElement
      */
     public function getTitle()
     {
@@ -259,7 +259,7 @@ public function getTitle()
     /**
      * Get article content element.
      *
-     * @return \DOMElement
+     * @return JSLikeHTMLElement
      */
     public function getContent()
     {
@@ -447,7 +447,7 @@ public function addFootnotes(\DOMElement $articleContent): void
      */
     public function prepArticle(\DOMNode $articleContent): void
     {
-        if (!$articleContent instanceof \DOMElement) {
+        if (!$articleContent instanceof JSLikeHTMLElement) {
             return;
         }
 
@@ -474,7 +474,7 @@ public function prepArticle(\DOMNode $articleContent): void
         }
 
         // Remove service data-candidate attribute.
-        /** @var \DOMNodeList<\DOMElement> */
+        /** @var \DOMNodeList<JSLikeHTMLElement> */
         $elems = $xpath->query('.//*[@data-candidate]', $articleContent);
         foreach ($elems as $elem) {
             $elem->removeAttribute('data-candidate');
@@ -645,7 +645,7 @@ public function getWeight(\DOMElement $e): int
     /**
      * Remove extraneous break tags from a node.
      */
-    public function killBreaks(\DOMElement $node): void
+    public function killBreaks(JSLikeHTMLElement $node): void
     {
         $html = $node->getInnerHTML();
         $html = preg_replace($this->regexps['killBreaks'], '<br />', $html);
@@ -1160,7 +1160,7 @@ protected function grabArticle(?\DOMElement $page = null)
          * This is faster to do before scoring but safer after.
          */
         if ($this->flagIsActive(self::FLAG_STRIP_UNLIKELYS) && $xpath) {
-            /** @var \DOMNodeList<\DOMElement> */
+            /** @var \DOMNodeList<JSLikeHTMLElement> */
             $candidates = $xpath->query('.//*[(self::footer and count(//footer)<2) or (self::aside and count(//aside)<2)]', $page->documentElement);
 
             for ($c = $candidates->length - 1; $c >= 0; --$c) {
@@ -1182,7 +1182,7 @@ protected function grabArticle(?\DOMElement $page = null)
         $topCandidates = array_fill(0, 5, null);
         if ($xpath) {
             // Using array of DOMElements after deletion is a path to DOOMElement.
-            /** @var \DOMNodeList<\DOMElement> */
+            /** @var \DOMNodeList<JSLikeHTMLElement> */
             $candidates = $xpath->query('.//*[@data-candidate]', $page->documentElement);
             $this->logger->debug('Candidates: ' . $candidates->length);
 
diff --git a/stubs/dom.stub b/stubs/dom.stub
new file mode 100644
index 0000000..ac85e9d
--- /dev/null
+++ b/stubs/dom.stub
@@ -0,0 +1,36 @@
+<?php
+
+// SPDX-FileCopyrightText: 2022 Ondřej Mirtes
+// SPDX-License-Identifier: MIT
+// Based on https://github.com/phpstan/phpstan-src/blob/b2a9ba4b82d19b01f37eb983746f1840f1213851/stubs/dom.stub
+
+use Readability\JSLikeHTMLElement;
+
+class DOMDocument
+{
+    /** @var JSLikeHTMLElement|null */
+    public $documentElement;
+
+    /** @var null */
+    public $ownerDocument;
+
+    /**
+     * @param string $name
+     * @return DOMNodeList<JSLikeHTMLElement>
+     */
+    public function getElementsByTagName($name) {}
+}
+
+class DOMNode
+{
+
+}
+
+class DOMElement extends DOMNode
+{
+    /**
+     * @param string $name
+     * @return DOMNodeList<JSLikeHTMLElement>
+     */
+    public function getElementsByTagName($name) {}
+}
diff --git a/tests/ReadabilityTest.php b/tests/ReadabilityTest.php
index b09a97a..74b4d31 100644
--- a/tests/ReadabilityTest.php
+++ b/tests/ReadabilityTest.php
@@ -5,7 +5,6 @@
 use Monolog\Handler\TestHandler;
 use Monolog\Logger;
 use Psr\Log\LoggerInterface;
-use Readability\JSLikeHTMLElement;
 use Readability\Readability;
 
 class ReadabilityTest extends \PHPUnit\Framework\TestCase
@@ -80,8 +79,6 @@ public function testInitNoContent(): void
         $res = $readability->init();
 
         $this->assertFalse($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('Sorry, Readability was unable to parse this page for content.', $readability->getContent()->getInnerHtml());
     }
@@ -92,8 +89,6 @@ public function testInitP(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertStringContainsString('<div readability=', $readability->getContent()->getInnerHtml());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is the awesome content :)', $readability->getContent()->getInnerHtml());
@@ -105,8 +100,6 @@ public function testInitDivP(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertStringContainsString('<div readability=', $readability->getContent()->getInnerHtml());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is the awesome content :)', $readability->getContent()->getInnerHtml());
@@ -119,8 +112,6 @@ public function testInitDiv(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertStringContainsString('<div readability=', $readability->getContent()->getInnerHtml());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is the awesome content :)', $readability->getContent()->getInnerHtml());
@@ -134,8 +125,6 @@ public function testWithFootnotes(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertStringContainsString('<div readability=', $readability->getContent()->getInnerHtml());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
@@ -151,8 +140,6 @@ public function testStandardClean(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertStringContainsString('<div readability=', $readability->getContent()->getInnerHtml());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
@@ -167,8 +154,6 @@ public function testWithIframe(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertStringContainsString('<div readability=', $readability->getContent()->getInnerHtml());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
@@ -182,8 +167,6 @@ public function testWithArticle(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertStringContainsString('alt="article"', $readability->getContent()->getInnerHtml());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
@@ -197,8 +180,6 @@ public function testWithAside(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
         $this->assertStringNotContainsString('<aside>', $readability->getContent()->getInnerHtml());
@@ -212,8 +193,6 @@ public function testWithClasses(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertStringContainsString('alt="article"', $readability->getContent()->getInnerHtml());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
@@ -228,8 +207,6 @@ public function testWithClassesWithoutLightClean(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertStringContainsString('alt="article"', $readability->getContent()->getInnerHtml());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
@@ -243,8 +220,6 @@ public function testWithTd(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
     }
@@ -256,8 +231,6 @@ public function testWithSameClasses(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
         $this->assertStringContainsString('This text is also an awesome text and you should know that', $readability->getContent()->getInnerHtml());
@@ -270,8 +243,6 @@ public function testWithScript(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertEmpty($readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
         $this->assertStringNotContainsString('This text is also an awesome text and you should know that', $readability->getContent()->getInnerHtml());
@@ -284,8 +255,6 @@ public function testTitle(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertSame('this is my title', $readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
         $this->assertStringNotContainsString('This text is also an awesome text and you should know that', $readability->getContent()->getInnerHtml());
@@ -298,8 +267,6 @@ public function testTitleWithDash(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertSame('title2 - title3', $readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
         $this->assertStringNotContainsString('This text is also an awesome text and you should know that', $readability->getContent()->getInnerHtml());
@@ -312,8 +279,6 @@ public function testTitleWithDoubleDot(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertSame('title2 : title3', $readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
         $this->assertStringNotContainsString('This text is also an awesome text and you should know that', $readability->getContent()->getInnerHtml());
@@ -326,8 +291,6 @@ public function testTitleTooShortUseH1(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
         $this->assertSame('this is my h1 title !', $readability->getTitle()->getInnerHtml());
         $this->assertStringContainsString('This is an awesome text with some links, here there are', $readability->getContent()->getInnerHtml());
         $this->assertStringNotContainsString('This text is also an awesome text and you should know that', $readability->getContent()->getInnerHtml());
@@ -374,8 +337,6 @@ public function testAutoClosingIframeNotThrowingException(): void
             $res = $readability->init();
 
             $this->assertTrue($res);
-            $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-            $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
             $this->assertStringContainsString('<iframe src="https://www.youtube.com/embed/PUep6xNeKjA" width="560" height="315" frameborder="0" allowfullscreen="allowfullscreen"> </iframe>', $readability->getContent()->getInnerHtml());
             $this->assertStringContainsString('3D Touch', $readability->getTitle()->getInnerHtml());
         } finally {
@@ -442,8 +403,6 @@ public function testAppendIdAlreadyHere(): void
         $res = $readability->init();
 
         $this->assertTrue($res);
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getContent());
-        $this->assertInstanceOf(JSLikeHTMLElement::class, $readability->getTitle());
     }
 
     public function testPostFilters(): void

From e36f2ed70f38d41f8d9e7c66c8342ffac17e356f Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 16 Mar 2024 20:24:17 +0100
Subject: [PATCH 08/17] Raise PHPStan to level 4

Nothing affecting correctness, just stuff making it easier for PHPStan to reason about the code.
---
 phpstan.dist.neon   |  2 +-
 src/Readability.php | 11 ++++++-----
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/phpstan.dist.neon b/phpstan.dist.neon
index 95b916d..4e2f08f 100644
--- a/phpstan.dist.neon
+++ b/phpstan.dist.neon
@@ -1,5 +1,5 @@
 parameters:
-    level: 1
+    level: 4
     paths:
         - src
         - tests
diff --git a/src/Readability.php b/src/Readability.php
index 9f6f87f..97d53f0 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -1166,7 +1166,7 @@ protected function grabArticle(?\DOMElement $page = null)
             for ($c = $candidates->length - 1; $c >= 0; --$c) {
                 $node = $candidates->item($c);
                 // node should be readable but not inside of an article otherwise it's probably non-readable block
-                if ($node->hasAttribute('readability') && (int) $node->getAttributeNode('readability')->value < 40 && ($node->parentNode ? 0 !== strcasecmp($node->parentNode->tagName, 'article') : true)) {
+                if ($node->hasAttribute('readability') && (int) $node->getAttributeNode('readability')->value < 40 && ($node->parentNode instanceof \DOMElement ? 0 !== strcasecmp($node->parentNode->tagName, 'article') : true)) {
                     $this->logger->debug('Removing unlikely candidate (using note) ' . $node->getNodePath() . ' by "' . $node->tagName . '" with readability ' . self::getContentScore($node));
                     $node->parentNode->removeChild($node);
                 }
@@ -1209,6 +1209,7 @@ protected function grabArticle(?\DOMElement $page = null)
             }
         }
 
+        /** @var \DOMNodeList<\DOMElement> */
         $topCandidates = array_filter(
             $topCandidates,
             fn ($v, $idx) => 0 === $idx || null !== $v,
@@ -1326,7 +1327,7 @@ protected function grabArticle(?\DOMElement $page = null)
             $siblingNode = $siblingNodes->item($s);
             $siblingNodeName = $siblingNode->nodeName;
             $append = false;
-            $this->logger->debug('Looking at sibling node: ' . $siblingNode->getNodePath() . ((\XML_ELEMENT_NODE === $siblingNode->nodeType && $siblingNode->hasAttribute('readability')) ? (' with score ' . $siblingNode->getAttribute('readability')) : ''));
+            $this->logger->debug('Looking at sibling node: ' . $siblingNode->getNodePath() . (($siblingNode instanceof \DOMElement && $siblingNode->hasAttribute('readability')) ? (' with score ' . $siblingNode->getAttribute('readability')) : ''));
 
             if ($siblingNode->isSameNode($topCandidate)) {
                 $append = true;
@@ -1334,11 +1335,11 @@ protected function grabArticle(?\DOMElement $page = null)
                 $contentBonus = 0;
 
                 // Give a bonus if sibling nodes and top candidates have the same classname.
-                if (\XML_ELEMENT_NODE === $siblingNode->nodeType && $siblingNode->getAttribute('class') === $topCandidate->getAttribute('class') && '' !== $topCandidate->getAttribute('class')) {
+                if ($siblingNode instanceof \DOMElement && $siblingNode->getAttribute('class') === $topCandidate->getAttribute('class') && '' !== $topCandidate->getAttribute('class')) {
                     $contentBonus += ((int) $topCandidate->getAttribute('readability')) * 0.2;
                 }
 
-                if (\XML_ELEMENT_NODE === $siblingNode->nodeType && $siblingNode->hasAttribute('readability') && (((int) $siblingNode->getAttribute('readability')) + $contentBonus) >= $siblingScoreThreshold) {
+                if ($siblingNode instanceof \DOMElement && $siblingNode->hasAttribute('readability') && (((int) $siblingNode->getAttribute('readability')) + $contentBonus) >= $siblingScoreThreshold) {
                     $append = true;
                 } elseif (0 === strcasecmp($siblingNodeName, 'p')) {
                     $linkDensity = (int) $this->getLinkDensity($siblingNode);
@@ -1568,7 +1569,7 @@ private function getAncestors(\DOMElement $node, int $maxDepth = 0): array
 
     private function isPhrasingContent($node): bool
     {
-        return \XML_TEXT_NODE === $node->nodeType
+        return $node instanceof \DOMText
             || \in_array(strtoupper($node->nodeName), $this->phrasingElements, true)
             || (
                 \in_array(strtoupper($node->nodeName), ['A', 'DEL', 'INS'], true)

From abf670d02e2aea904d73cc2788e993f2f30693a3 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 12 Oct 2024 02:04:14 +0200
Subject: [PATCH 09/17] fixup! Use JSLikeHTMLElement in type hints

---
 src/Readability.php |  4 ++--
 stubs/dom.stub      | 10 +++++++---
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/src/Readability.php b/src/Readability.php
index 97d53f0..5c36b71 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -146,7 +146,7 @@ class Readability implements LoggerAwareInterface
     protected $domainRegExp = null;
 
     /**
-     * @var ?\DOMElement
+     * @var ?\JSLikeHTMLElement
      */
     protected $body = null;
 
@@ -603,7 +603,7 @@ public function getWordCount(string $text): int
      * This is the amount of text that is inside a link divided by the total text in the node.
      * Can exclude external references to differentiate between simple text and menus/infoblocks.
      */
-    public function getLinkDensity(\DOMElement $e, bool $excludeExternal = false): float
+    public function getLinkDensity(JSLikeHTMLElement $e, bool $excludeExternal = false): float
     {
         $links = $e->getElementsByTagName('a');
         $textLength = mb_strlen($this->getInnerText($e, true, true));
diff --git a/stubs/dom.stub b/stubs/dom.stub
index ac85e9d..09a39d6 100644
--- a/stubs/dom.stub
+++ b/stubs/dom.stub
@@ -11,14 +11,18 @@ class DOMDocument
     /** @var JSLikeHTMLElement|null */
     public $documentElement;
 
-    /** @var null */
-    public $ownerDocument;
-
     /**
      * @param string $name
      * @return DOMNodeList<JSLikeHTMLElement>
      */
     public function getElementsByTagName($name) {}
+
+    /**
+     * @param string $localName
+     * @param string $value
+     * @return JSLikeHTMLElement Officially, this can return false but PHPStan decided to ignore that: <https://github.com/phpstan/phpstan-src/pull/1569>
+     */
+    public function createElement($localName, $value = '') {}
 }
 
 class DOMNode

From a7aebb05405220e82b1df9992924aa739d595360 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 12 Oct 2024 02:09:44 +0200
Subject: [PATCH 10/17] fixup! Use JSLikeHTMLElement in type hints

---
 src/Readability.php | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/src/Readability.php b/src/Readability.php
index 5c36b71..3456aa3 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -987,9 +987,9 @@ protected function initializeNode(\DOMElement $node): void
      * Using a variety of metrics (content score, classname, element types), find the content that is
      * most likely to be the stuff a user wants to read. Then return it wrapped up in a div.
      *
-     * @return \DOMElement|false
+     * @return JSLikeHTMLElement|false
      */
-    protected function grabArticle(?\DOMElement $page = null)
+    protected function grabArticle(?JSLikeHTMLElement $page = null)
     {
         if (!$page) {
             $page = $this->dom;
@@ -1166,7 +1166,7 @@ protected function grabArticle(?\DOMElement $page = null)
             for ($c = $candidates->length - 1; $c >= 0; --$c) {
                 $node = $candidates->item($c);
                 // node should be readable but not inside of an article otherwise it's probably non-readable block
-                if ($node->hasAttribute('readability') && (int) $node->getAttributeNode('readability')->value < 40 && ($node->parentNode instanceof \DOMElement ? 0 !== strcasecmp($node->parentNode->tagName, 'article') : true)) {
+                if ($node->hasAttribute('readability') && (int) $node->getAttributeNode('readability')->value < 40 && ($node->parentNode instanceof JSLikeHTMLElement ? 0 !== strcasecmp($node->parentNode->tagName, 'article') : true)) {
                     $this->logger->debug('Removing unlikely candidate (using note) ' . $node->getNodePath() . ' by "' . $node->tagName . '" with readability ' . self::getContentScore($node));
                     $node->parentNode->removeChild($node);
                 }
@@ -1302,7 +1302,7 @@ protected function grabArticle(?\DOMElement $page = null)
         if (0 === strcasecmp($tagName, 'td') || 0 === strcasecmp($tagName, 'tr')) {
             $up = $topCandidate;
 
-            if ($up->parentNode instanceof \DOMElement) {
+            if ($up->parentNode instanceof JSLikeHTMLElement) {
                 $up = $up->parentNode;
 
                 if (0 === strcasecmp($up->tagName, 'table')) {
@@ -1327,7 +1327,7 @@ protected function grabArticle(?\DOMElement $page = null)
             $siblingNode = $siblingNodes->item($s);
             $siblingNodeName = $siblingNode->nodeName;
             $append = false;
-            $this->logger->debug('Looking at sibling node: ' . $siblingNode->getNodePath() . (($siblingNode instanceof \DOMElement && $siblingNode->hasAttribute('readability')) ? (' with score ' . $siblingNode->getAttribute('readability')) : ''));
+            $this->logger->debug('Looking at sibling node: ' . $siblingNode->getNodePath() . (($siblingNode instanceof JSLikeHTMLElement && $siblingNode->hasAttribute('readability')) ? (' with score ' . $siblingNode->getAttribute('readability')) : ''));
 
             if ($siblingNode->isSameNode($topCandidate)) {
                 $append = true;
@@ -1335,11 +1335,11 @@ protected function grabArticle(?\DOMElement $page = null)
                 $contentBonus = 0;
 
                 // Give a bonus if sibling nodes and top candidates have the same classname.
-                if ($siblingNode instanceof \DOMElement && $siblingNode->getAttribute('class') === $topCandidate->getAttribute('class') && '' !== $topCandidate->getAttribute('class')) {
+                if ($siblingNode instanceof JSLikeHTMLElement && $siblingNode->getAttribute('class') === $topCandidate->getAttribute('class') && '' !== $topCandidate->getAttribute('class')) {
                     $contentBonus += ((int) $topCandidate->getAttribute('readability')) * 0.2;
                 }
 
-                if ($siblingNode instanceof \DOMElement && $siblingNode->hasAttribute('readability') && (((int) $siblingNode->getAttribute('readability')) + $contentBonus) >= $siblingScoreThreshold) {
+                if ($siblingNode instanceof JSLikeHTMLElement && $siblingNode->hasAttribute('readability') && (((int) $siblingNode->getAttribute('readability')) + $contentBonus) >= $siblingScoreThreshold) {
                     $append = true;
                 } elseif (0 === strcasecmp($siblingNodeName, 'p')) {
                     $linkDensity = (int) $this->getLinkDensity($siblingNode);
@@ -1426,7 +1426,7 @@ protected function grabArticle(?\DOMElement $page = null)
      * Get an element weight by attribute.
      * Uses regular expressions to tell if this element looks good or bad.
      */
-    protected function weightAttribute(\DOMElement $element, string $attribute): int
+    protected function weightAttribute(JSLikeHTMLElement $element, string $attribute): int
     {
         if (!$element->hasAttribute($attribute)) {
             return 0;
@@ -1470,7 +1470,7 @@ protected function reinitBody(): void
      *
      * @param callable(float): float $f
      */
-    private static function updateContentScore(\DOMElement $element, callable $f): void
+    private static function updateContentScore(JSLikeHTMLElement $element, callable $f): void
     {
         $readabilityAttr = $element->getAttributeNode('readability');
         $prevScore = (float) $readabilityAttr->value;
@@ -1480,7 +1480,7 @@ private static function updateContentScore(\DOMElement $element, callable $f): v
     /**
      * Gets the content score for given element.
      */
-    private static function getContentScore(\DOMElement $element): float
+    private static function getContentScore(JSLikeHTMLElement $element): float
     {
         return $element->hasAttribute('readability') ? (float) $element->getAttribute('readability') : 0;
     }
@@ -1552,11 +1552,11 @@ private function loadHtml(): void
         $this->dom->registerNodeClass(\DOMElement::class, JSLikeHTMLElement::class);
     }
 
-    private function getAncestors(\DOMElement $node, int $maxDepth = 0): array
+    private function getAncestors(JSLikeHTMLElement $node, int $maxDepth = 0): array
     {
         $ancestors = [];
         $i = 0;
-        while ($node->parentNode instanceof \DOMElement) {
+        while ($node->parentNode instanceof JSLikeHTMLElement) {
             $ancestors[] = $node->parentNode;
             if (++$i === $maxDepth) {
                 break;
@@ -1589,10 +1589,10 @@ private function isPhrasingContent($node): bool
      * Returns false if `$node` contains non-empty text nodes
      * or if it contains no element with given tag or more than 1 element.
      */
-    private function hasSingleTagInsideElement(\DOMElement $node, string $tag): bool
+    private function hasSingleTagInsideElement(JSLikeHTMLElement $node, string $tag): bool
     {
         $childNodes = iterator_to_array($node->childNodes);
-        $children = array_filter($childNodes, fn ($childNode) => $childNode instanceof \DOMElement);
+        $children = array_filter($childNodes, fn ($childNode) => $childNode instanceof JSLikeHTMLElement);
 
         // There should be exactly 1 element child with given tag
         if (1 !== \count($children) || $children[0]->nodeName !== $tag) {
@@ -1613,7 +1613,7 @@ private function hasSingleTagInsideElement(\DOMElement $node, string $tag): bool
      * Tidy must be configured to not clean the input for this function to
      * work as expected, see $this->tidy_config['clean']
      */
-    private function isNodeVisible(\DOMElement $node): bool
+    private function isNodeVisible(JSLikeHTMLElement $node): bool
     {
         return !(
             $node->hasAttribute('style')

From 2e9d766f820a8229b2230f387c21e01d79c071c5 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 12 Oct 2024 12:22:01 +0200
Subject: [PATCH 11/17] fixup! fixup! Use JSLikeHTMLElement in type hints

---
 src/Readability.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Readability.php b/src/Readability.php
index 3456aa3..ab4c2d8 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -146,7 +146,7 @@ class Readability implements LoggerAwareInterface
     protected $domainRegExp = null;
 
     /**
-     * @var ?\JSLikeHTMLElement
+     * @var ?JSLikeHTMLElement
      */
     protected $body = null;
 

From 46ec78839d0e730d0dd635dfdcdee3237f377317 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 12 Oct 2024 13:08:17 +0200
Subject: [PATCH 12/17] squash! Use JSLikeHTMLElement in type hints

We cannot use stubs since PHPStan already has them to override
---
 composer.json                                 |  5 ++-
 ...ntGetElementDynamicReturnTypeExtension.php | 38 ++++++++++++++++++
 ...tGetElementsDynamicReturnTypeExtension.php | 39 ++++++++++++++++++
 ...tGetElementsDynamicReturnTypeExtension.php | 39 ++++++++++++++++++
 phpstan.dist.neon                             | 20 ++++++++--
 src/Readability.php                           |  2 +-
 stubs/dom.stub                                | 40 -------------------
 7 files changed, 138 insertions(+), 45 deletions(-)
 create mode 100644 maintenance/PHPStan/DOMDocumentGetElementDynamicReturnTypeExtension.php
 create mode 100644 maintenance/PHPStan/DOMDocumentGetElementsDynamicReturnTypeExtension.php
 create mode 100644 maintenance/PHPStan/DOMElementGetElementsDynamicReturnTypeExtension.php
 delete mode 100644 stubs/dom.stub

diff --git a/composer.json b/composer.json
index 9e7b607..bca31a6 100644
--- a/composer.json
+++ b/composer.json
@@ -44,7 +44,10 @@
         "psr-4": { "Readability\\": "src/" }
     },
     "autoload-dev": {
-        "psr-4": { "Tests\\Readability\\": "tests/" }
+        "psr-4": {
+            "Tests\\Readability\\": "tests/",
+            "Readability\\Maintenance\\": "maintenance/"
+        }
     },
     "scripts": {
         "fix": "php-cs-fixer fix --verbose --diff",
diff --git a/maintenance/PHPStan/DOMDocumentGetElementDynamicReturnTypeExtension.php b/maintenance/PHPStan/DOMDocumentGetElementDynamicReturnTypeExtension.php
new file mode 100644
index 0000000..0196ed0
--- /dev/null
+++ b/maintenance/PHPStan/DOMDocumentGetElementDynamicReturnTypeExtension.php
@@ -0,0 +1,38 @@
+<?php
+
+namespace Readability\Maintenance\PHPStan;
+
+use Readability\JSLikeHTMLElement;
+use PHPStan\Type\Generic\GenericObjectType;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Type;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\ObjectType;
+
+class DOMDocumentGetElementDynamicReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+	public function getClass(): string
+	{
+		return \DOMDocument::class;
+	}
+
+	public function isMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return in_array($methodReflection->getName(),
+			[
+				'createElement',
+			], true);
+	}
+
+	public function getTypeFromMethodCall(
+		MethodReflection $methodReflection,
+		MethodCall $methodCall,
+		Scope $scope
+	): ?Type
+	{
+		return new ObjectType(JSLikeHTMLElement::class);
+	}
+}
diff --git a/maintenance/PHPStan/DOMDocumentGetElementsDynamicReturnTypeExtension.php b/maintenance/PHPStan/DOMDocumentGetElementsDynamicReturnTypeExtension.php
new file mode 100644
index 0000000..f7c28bc
--- /dev/null
+++ b/maintenance/PHPStan/DOMDocumentGetElementsDynamicReturnTypeExtension.php
@@ -0,0 +1,39 @@
+<?php
+
+namespace Readability\Maintenance\PHPStan;
+
+use Readability\JSLikeHTMLElement;
+use PHPStan\Type\Generic\GenericObjectType;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Type;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\ObjectType;
+
+class DOMDocumentGetElementsDynamicReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+	public function getClass(): string
+	{
+		return \DOMDocument::class;
+	}
+
+	public function isMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return in_array($methodReflection->getName(),
+			[
+				'getElementsByTagName',
+			], true);
+	}
+
+	public function getTypeFromMethodCall(
+		MethodReflection $methodReflection,
+		MethodCall $methodCall,
+		Scope $scope
+	): ?Type
+	{
+		$elementType = new ObjectType(JSLikeHTMLElement::class);
+		return new GenericObjectType(\DOMNodeList::class, [$elementType]);
+	}
+}
diff --git a/maintenance/PHPStan/DOMElementGetElementsDynamicReturnTypeExtension.php b/maintenance/PHPStan/DOMElementGetElementsDynamicReturnTypeExtension.php
new file mode 100644
index 0000000..e6a7d34
--- /dev/null
+++ b/maintenance/PHPStan/DOMElementGetElementsDynamicReturnTypeExtension.php
@@ -0,0 +1,39 @@
+<?php
+
+namespace Readability\Maintenance\PHPStan;
+
+use Readability\JSLikeHTMLElement;
+use PHPStan\Type\Generic\GenericObjectType;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Type;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\ObjectType;
+
+class DOMElementGetElementsDynamicReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+	public function getClass(): string
+	{
+		return \DOMElement::class;
+	}
+
+	public function isMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return in_array($methodReflection->getName(),
+			[
+				'getElementsByTagName',
+			], true);
+	}
+
+	public function getTypeFromMethodCall(
+		MethodReflection $methodReflection,
+		MethodCall $methodCall,
+		Scope $scope
+	): ?Type
+	{
+		$elementType = new ObjectType(JSLikeHTMLElement::class);
+		return new GenericObjectType(\DOMNodeList::class, [$elementType]);
+	}
+}
diff --git a/phpstan.dist.neon b/phpstan.dist.neon
index 4e2f08f..aca4130 100644
--- a/phpstan.dist.neon
+++ b/phpstan.dist.neon
@@ -8,9 +8,23 @@ parameters:
     bootstrapFiles:
         - vendor/bin/.phpunit/phpunit/vendor/autoload.php
 
-    stubFiles:
-        - stubs/dom.stub
-
 includes:
     - vendor/phpstan/phpstan-phpunit/extension.neon
     - vendor/phpstan/phpstan-phpunit/rules.neon
+    - phar://phpstan.phar/conf/bleedingEdge.neon
+
+services:
+    -
+        class: Readability\Maintenance\PHPStan\DOMDocumentGetElementDynamicReturnTypeExtension
+        tags:
+            - phpstan.broker.dynamicMethodReturnTypeExtension
+
+    -
+        class: Readability\Maintenance\PHPStan\DOMDocumentGetElementsDynamicReturnTypeExtension
+        tags:
+            - phpstan.broker.dynamicMethodReturnTypeExtension
+
+    -
+        class: Readability\Maintenance\PHPStan\DOMElementGetElementsDynamicReturnTypeExtension
+        tags:
+            - phpstan.broker.dynamicMethodReturnTypeExtension
diff --git a/src/Readability.php b/src/Readability.php
index ab4c2d8..b0a4a12 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -844,7 +844,7 @@ public function removeFlag(int $flag): void
     /**
      * Get the article title as an H1.
      *
-     * @return \DOMElement
+     * @return JSLikeHTMLElement
      */
     protected function getArticleTitle()
     {
diff --git a/stubs/dom.stub b/stubs/dom.stub
deleted file mode 100644
index 09a39d6..0000000
--- a/stubs/dom.stub
+++ /dev/null
@@ -1,40 +0,0 @@
-<?php
-
-// SPDX-FileCopyrightText: 2022 Ondřej Mirtes
-// SPDX-License-Identifier: MIT
-// Based on https://github.com/phpstan/phpstan-src/blob/b2a9ba4b82d19b01f37eb983746f1840f1213851/stubs/dom.stub
-
-use Readability\JSLikeHTMLElement;
-
-class DOMDocument
-{
-    /** @var JSLikeHTMLElement|null */
-    public $documentElement;
-
-    /**
-     * @param string $name
-     * @return DOMNodeList<JSLikeHTMLElement>
-     */
-    public function getElementsByTagName($name) {}
-
-    /**
-     * @param string $localName
-     * @param string $value
-     * @return JSLikeHTMLElement Officially, this can return false but PHPStan decided to ignore that: <https://github.com/phpstan/phpstan-src/pull/1569>
-     */
-    public function createElement($localName, $value = '') {}
-}
-
-class DOMNode
-{
-
-}
-
-class DOMElement extends DOMNode
-{
-    /**
-     * @param string $name
-     * @return DOMNodeList<JSLikeHTMLElement>
-     */
-    public function getElementsByTagName($name) {}
-}

From 573b139a4b19874879f805787076aebb27102831 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 12 Oct 2024 13:08:37 +0200
Subject: [PATCH 13/17] fixup! Add type annotations to properties

---
 src/Readability.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Readability.php b/src/Readability.php
index b0a4a12..30cbade 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -113,7 +113,7 @@ class Readability implements LoggerAwareInterface
     ];
 
     /**
-     * @var array<string, bool|string>
+     * @var array<string, bool|int|string>
      */
     public $tidy_config = [
         'tidy-mark' => false,

From c6d0eb2345cf1633e95bc618bb1e4b6a7247052b Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 12 Oct 2024 13:11:31 +0200
Subject: [PATCH 14/17] Remove redundant is_object check

The argument can only be `DOMElement`.

Discovered by bleeding edge PHPStan.
---
 src/Readability.php | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/src/Readability.php b/src/Readability.php
index 30cbade..6dea5fd 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -572,12 +572,10 @@ public function getInnerText(?\DOMNode $e, bool $normalizeSpaces = true, bool $f
      */
     public function cleanStyles(\DOMElement $e): void
     {
-        if (\is_object($e)) {
-            $elems = $e->getElementsByTagName('*');
+        $elems = $e->getElementsByTagName('*');
 
-            foreach ($elems as $elem) {
-                $elem->removeAttribute('style');
-            }
+        foreach ($elems as $elem) {
+            $elem->removeAttribute('style');
         }
     }
 

From 6a7f008f72c5ecbc90f3cb83076aa8a657b9f6aa Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 12 Oct 2024 13:41:38 +0200
Subject: [PATCH 15/17] Replace isset with clearer null check

`isset` does two things: it checks if the entity resulting from the chain of accessors is defined, and if it is not `null`.
We know that the properties are always defined so we can just replace those `isset`s with `null` checks.
This will allow us to reason about the code more clearly.
---
 src/Readability.php | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/Readability.php b/src/Readability.php
index 6dea5fd..1432d90 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -308,7 +308,7 @@ public function init(): bool
     {
         $this->loadHtml();
 
-        if (!isset($this->dom->documentElement)) {
+        if (null === $this->dom || null === $this->dom->documentElement) {
             return false;
         }
 
@@ -400,7 +400,7 @@ public function addFootnotes(\DOMElement $articleContent): void
             $refLink = $this->dom->createElement('a');
             $footnote = $this->dom->createElement('li');
             $linkDomain = @parse_url($footnoteLink->getAttribute('href'), \PHP_URL_HOST);
-            if (!$linkDomain && isset($this->url)) {
+            if (!$linkDomain && null !== $this->url) {
                 $linkDomain = @parse_url($this->url, \PHP_URL_HOST);
             }
 
@@ -1223,15 +1223,16 @@ protected function grabArticle(?JSLikeHTMLElement $page = null)
             $topCandidate = $this->dom->createElement('div');
 
             if ($page instanceof \DOMDocument) {
-                if (!isset($page->documentElement)) {
+                $documentElement = $page->documentElement;
+                if (null === $documentElement) {
                     // we don't have a body either? what a mess! :)
                     $this->logger->debug('The page has no body!');
                 } else {
                     $this->logger->debug('Setting body to a raw HTML of original page!');
-                    $topCandidate->setInnerHtml($page->documentElement->getInnerHTML());
-                    $page->documentElement->setInnerHtml('');
+                    $topCandidate->setInnerHtml($documentElement->getInnerHTML());
+                    $documentElement->setInnerHtml('');
                     $this->reinitBody();
-                    $page->documentElement->appendChild($topCandidate);
+                    $documentElement->appendChild($topCandidate);
                 }
             } else {
                 $topCandidate->setInnerHtml($page->getInnerHTML());
@@ -1457,7 +1458,7 @@ protected function weightAttribute(JSLikeHTMLElement $element, string $attribute
      */
     protected function reinitBody(): void
     {
-        if (!isset($this->body->childNodes)) {
+        if (null === $this->body) {
             $this->body = $this->dom->createElement('body');
             $this->body->setInnerHtml($this->bodyCache);
         }

From 2982f306e3f12b86f4d7e2ba9acc42f688ffefaf Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sun, 13 Oct 2024 03:30:03 +0200
Subject: [PATCH 16/17] fixup! fixup! Use JSLikeHTMLElement in type hints

---
 src/Readability.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/Readability.php b/src/Readability.php
index 1432d90..4528eae 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -1223,6 +1223,7 @@ protected function grabArticle(?JSLikeHTMLElement $page = null)
             $topCandidate = $this->dom->createElement('div');
 
             if ($page instanceof \DOMDocument) {
+                /** @var JSLikeHTMLElement|null $documentElement (overridden by registerNodeClass) */
                 $documentElement = $page->documentElement;
                 if (null === $documentElement) {
                     // we don't have a body either? what a mess! :)

From 1b5911572cc5b1519155f58bc3fc3480cf9957d1 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Tue, 4 Mar 2025 03:18:29 +0100
Subject: [PATCH 17/17] wip

---
 src/Readability.php | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/Readability.php b/src/Readability.php
index 4528eae..a2efc36 100644
--- a/src/Readability.php
+++ b/src/Readability.php
@@ -1207,13 +1207,13 @@ protected function grabArticle(?JSLikeHTMLElement $page = null)
             }
         }
 
-        /** @var \DOMNodeList<\DOMElement> */
         $topCandidates = array_filter(
             $topCandidates,
             fn ($v, $idx) => 0 === $idx || null !== $v,
             \ARRAY_FILTER_USE_BOTH
         );
         $topCandidate = $topCandidates[0];
+                \PHPStan\dumpType($topCandidates);
 
         /*
          * If we still have no top candidate, just use the body as a last resort.
@@ -1264,11 +1264,17 @@ protected function grabArticle(?JSLikeHTMLElement $page = null)
                     }
                     $parentOfTopCandidate = $parentOfTopCandidate->parentNode;
                 }
+                // For PHPStan: the loop terminates either when the parent node is body (a HTML element),
+                // or when $parentOfTopCandidate is in at least three candidate ancestor lists.
+                // TODO: Fuzz this.
+                \assert($parentOfTopCandidate instanceof JSLikeHTMLElement);
+                \assert($topCandidate instanceof JSLikeHTMLElement);
             }
             if (!$topCandidate->hasAttribute('readability')) {
                 $this->initializeNode($topCandidate);
             }
             $parentOfTopCandidate = $topCandidate->parentNode;
+            \assert($parentOfTopCandidate instanceof JSLikeHTMLElement);
             $lastScore = (int) $topCandidate->getAttribute('readability');
             $scoreThreshold = $lastScore / 3;
             while ('body' !== $parentOfTopCandidate->nodeName) {
@@ -1552,6 +1558,9 @@ private function loadHtml(): void
         $this->dom->registerNodeClass(\DOMElement::class, JSLikeHTMLElement::class);
     }
 
+    /**
+     * @return array<JSLikeHTMLElement>
+     */
     private function getAncestors(JSLikeHTMLElement $node, int $maxDepth = 0): array
     {
         $ancestors = [];