From c366e85b59f20d0e85623d26503c79cc5969551b Mon Sep 17 00:00:00 2001
From: Matthias Pigulla <mp@webfactory.de>
Date: Wed, 21 Jan 2026 23:04:50 +0100
Subject: [PATCH 1/2] Use Psalm for static analysis

---
 .github/workflows/static-analysis.yml   | 32 +++++++++++++++++++++++++
 psalm.xml                               | 18 ++++++++++++++
 src/Handler/BaseRewriteHandler.php      |  3 +++
 src/Implementation/Html5TagRewriter.php |  8 ++++++-
 src/TagRewriter.php                     |  2 +-
 5 files changed, 61 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/static-analysis.yml
 create mode 100644 psalm.xml

diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml
new file mode 100644
index 0000000..1b54c6f
--- /dev/null
+++ b/.github/workflows/static-analysis.yml
@@ -0,0 +1,32 @@
+name: Static Analysis
+
+permissions:
+    contents: read
+    packages: read
+
+on:
+    push:
+        branches:
+            - main
+    pull_request:
+
+env:
+    PHP_VERSION: 8.4
+    PSALM_VERSION: 6.14.3
+
+jobs:
+    Psalm:
+        name: Psalm
+        runs-on: ubuntu-latest
+        steps:
+            -   uses: shivammathur/setup-php@v2
+                with:
+                  php-version: ${{ env.PHP_VERSION }}
+                  coverage: none
+                  tools: composer:v2
+            -   uses: actions/checkout@v4
+            -   run:  composer install --no-interaction --no-progress --ansi --no-scripts
+            -   name: Run Psalm
+                run: |
+                    docker pull --quiet ghcr.io/webfactory/psalm:$PSALM_VERSION
+                    docker run --tty -v $(pwd):/app -v $HOME/cache:/cache ghcr.io/webfactory/psalm:$PSALM_VERSION --show-info=false --stats --output-format=github
diff --git a/psalm.xml b/psalm.xml
new file mode 100644
index 0000000..2bf1f7b
--- /dev/null
+++ b/psalm.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0"?>
+<psalm
+    resolveFromConfigFile="true"
+    memoizeMethodCallResults="true"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+>
+    <projectFiles>
+        <directory name="src" />
+    </projectFiles>
+
+    <issueHandlers>
+        <!-- Normal for libraries: classes/methods are used by consumers, not internally -->
+        <UnusedClass errorLevel="suppress" />
+        <PossiblyUnusedMethod errorLevel="suppress" />
+    </issueHandlers>
+</psalm>
diff --git a/src/Handler/BaseRewriteHandler.php b/src/Handler/BaseRewriteHandler.php
index 6ae56a0..7785a24 100644
--- a/src/Handler/BaseRewriteHandler.php
+++ b/src/Handler/BaseRewriteHandler.php
@@ -7,6 +7,7 @@
 use Dom\Document;
 use Dom\Element;
 use Dom\XPath;
+use Override;
 use Webfactory\Html5TagRewriter\RewriteHandler;
 
 /**
@@ -14,10 +15,12 @@
  */
 abstract class BaseRewriteHandler implements RewriteHandler
 {
+    #[Override]
     public function match(Element $element): void
     {
     }
 
+    #[Override]
     public function afterMatches(Document $document, XPath $xpath): void
     {
     }
diff --git a/src/Implementation/Html5TagRewriter.php b/src/Implementation/Html5TagRewriter.php
index 3df5e8c..26f114b 100644
--- a/src/Implementation/Html5TagRewriter.php
+++ b/src/Implementation/Html5TagRewriter.php
@@ -1,11 +1,14 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Webfactory\Html5TagRewriter\Implementation;
 
 use Dom\Document;
 use Dom\HTMLDocument;
 use Dom\Node;
 use Dom\XPath;
+use Override;
 use Webfactory\Html5TagRewriter\RewriteHandler;
 use Webfactory\Html5TagRewriter\TagRewriter;
 
@@ -14,11 +17,13 @@ final class Html5TagRewriter implements TagRewriter
     /** @var list<RewriteHandler> */
     private array $rewriteHandlers = [];
 
+    #[Override]
     public function register(RewriteHandler $handler): void
     {
         $this->rewriteHandlers[] = $handler;
     }
 
+    #[Override]
     public function process(string $html5): string
     {
         $document = HTMLDocument::createFromString($html5, LIBXML_NOERROR);
@@ -28,6 +33,7 @@ public function process(string $html5): string
         return $this->cleanup($document->saveHtml());
     }
 
+    #[Override]
     public function processFragment(string $html5Fragment): string
     {
         $document = HTMLDocument::createEmpty();
@@ -64,6 +70,6 @@ private function applyHandlers(Document $document, Node $context): void
 
     private function cleanup(string $html): string
     {
-        return preg_replace('#(<esi:([a-z]+)(?:[^>]*))></esi:\\2>#', '$1 />', $html);
+        return preg_replace('#(<esi:([a-z]+)(?:[^>]*))></esi:\\2>#', '$1 />', $html) ?? $html;
     }
 }
diff --git a/src/TagRewriter.php b/src/TagRewriter.php
index 0e5fd07..17b8ee7 100644
--- a/src/TagRewriter.php
+++ b/src/TagRewriter.php
@@ -4,7 +4,7 @@
 
 interface TagRewriter
 {
-    public function register(RewriteHandler $handler);
+    public function register(RewriteHandler $handler): void;
 
     public function process(string $html5): string;
 

From c8759552c2483bfb2fc7c94affca206364295412 Mon Sep 17 00:00:00 2001
From: Matthias Pigulla <mp@webfactory.de>
Date: Wed, 21 Jan 2026 23:14:46 +0100
Subject: [PATCH 2/2] Add extra type hints

---
 src/Implementation/Html5TagRewriter.php | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/Implementation/Html5TagRewriter.php b/src/Implementation/Html5TagRewriter.php
index 26f114b..97cd229 100644
--- a/src/Implementation/Html5TagRewriter.php
+++ b/src/Implementation/Html5TagRewriter.php
@@ -5,6 +5,7 @@
 namespace Webfactory\Html5TagRewriter\Implementation;
 
 use Dom\Document;
+use Dom\Element;
 use Dom\HTMLDocument;
 use Dom\Node;
 use Dom\XPath;
@@ -43,13 +44,16 @@ public function processFragment(string $html5Fragment): string
         $temp = $document->createElement('temp');
         $temp->innerHTML = $html5Fragment;
 
-        while ($temp->firstChild) {
+        while ($temp->firstChild instanceof Node) {
             $container->appendChild($temp->firstChild);
         }
 
         $this->applyHandlers($document, $container);
 
-        return $this->cleanup($container->innerHTML);
+        /** @var string */
+        $innerHTML = $container->innerHTML;
+
+        return $this->cleanup($innerHTML);
     }
 
     private function applyHandlers(Document $document, Node $context): void
@@ -60,6 +64,7 @@ private function applyHandlers(Document $document, Node $context): void
         $xpath->registerNamespace('mathml', 'http://www.w3.org/1998/Math/MathML');
 
         foreach ($this->rewriteHandlers as $handler) {
+            /** @var iterable<Element> */
             $elements = $xpath->query($handler->appliesTo(), $context);
             foreach ($elements as $element) {
                 $handler->match($element);