PHPackages                             webfactory/html5-tagrewriter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. webfactory/html5-tagrewriter

ActiveLibrary[Parsing & Serialization](/categories/parsing)

webfactory/html5-tagrewriter
============================

A small library that uses a handler pattern to transform HTML documents, based on the PHP 8.4+ HTML5 parser and DOM extension

1.0.0(3mo ago)02151MITPHPPHP >= 8.4CI passing

Since Jan 30Pushed 3mo agoCompare

[ Source](https://github.com/webfactory/html5-tagrewriter)[ Packagist](https://packagist.org/packages/webfactory/html5-tagrewriter)[ Docs](https://github.com/webfactory/html5-tagrewriter)[ RSS](/packages/webfactory-html5-tagrewriter/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (5)Used By (1)

webfactory HTML5 TagRewriter library
====================================

[](#webfactory-html5-tagrewriter-library)

A small library that uses a handler pattern to transform HTML documents. Based on the PHP 8.4+ HTML5 parser and DOM extension.

Useful to make manipulations to HTML5 documents that may not be so easy when generating the HTML output (e.g. a template engine like Twig), but are rather trivial when looking at the final DOM.

Examples:

- Add `target="_blank"` and `rel="noopener"` to all external links
- Find all `` in a page that have a `data-credits` attribute, and place all credits information in a section in the page footer
- Find all headings within the `` section of the page, generate a table of contents with anchor links and place it at the beginning of the page

For the Symfony integration, see .

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

```
use Webfactory\Html5TagRewriter\Implementation\Html5TagRewriter;

$rewriter = new Html5TagRewriter();

// Process a complete HTML5 document
$html = 'Hello';
$result = $rewriter->process($html);

// Process an HTML fragment
$fragment = 'Hello World';
$result = $rewriter->processBodyFragment($fragment);
```

Note

The `processBodyFragment()` method is currently limited in that it can only process HTML strings that come from within the `` section. This has to do with the HTML 5 parsing rules defining different [parsing states](https://html.spec.whatwg.org/multipage/parsing.html#parse-state), and the PHP DOM API for the HTML 5 parser does currently not expose a (documented) way to create fragments and passing the required context information. For correct results, you should limit its usage to fragments that shall be processed starting in the `in body` parsing state and where the `data state` [tokenization mode](https://html.spec.whatwg.org/multipage/parsing.html#tokenization)is active.

### Creating a Handler

[](#creating-a-handler)

Implement the `RewriteHandler` interface or extend `BaseRewriteHandler` to create custom tag transformations. The `BaseRewriteHandler` provides empty default implementations, so you only need to override the methods you need:

```
use Dom\Element;
use Webfactory\Html5TagRewriter\Handler\BaseRewriteHandler;

class ExternalLinkHandler extends BaseRewriteHandler
{
    public function appliesTo(): string
    {
        // XPath expression to match elements
        // Use 'html:' prefix for HTML5 elements, 'svg:' for SVG and 'mathml:' for MathML
        return '//html:a[@href]';
    }

    public function match(Element $element): void
    {
        $href = $element->getAttribute('href');
        if (str_starts_with($href, 'http')) {
            $element->setAttribute('target', '_blank');
            $element->setAttribute('rel', 'noopener');
        }
    }
}
```

### Registering Handlers

[](#registering-handlers)

```
$rewriter = new Html5TagRewriter();
$rewriter->register(new ExternalLinkHandler());
$rewriter->register(new AnotherHandler());

$result = $rewriter->process($html);
```

### XPath Namespaces

[](#xpath-namespaces)

The following namespaces are pre-registered for XPath queries:

PrefixNamespace URI`html``http://www.w3.org/1999/xhtml``svg``http://www.w3.org/2000/svg``mathml``http://www.w3.org/1998/Math/MathML`### ESI Tag Support

[](#esi-tag-support)

The library preserves Edge Side Includes (ESI) tags verbatim during HTML5 processing. ESI tags present multiple challenges:

1. **Self-closing syntax**: Tags like `` don't exist in HTML5
2. **Arbitrary interleaving**: ESI tags can span across HTML element boundaries
3. **Attribute encoding**: Characters like `&` must not become `&`

The [ESI Language Specification 1.0](https://www.w3.org/TR/esi-lang/) describes ESI as "XML-based" (Section 1), but also states that documents containing ESI markup are not valid. From Section 1.1:

> the markup that is emitted by the origin server is not valid; it contains interposed elements from the ESI namespace

ESI elements can be arbitrarily interleaved with the underlying content, which does not even need to be HTML. The standard makes no statements about whether HTML entities must be applied. Since XML parsing is not feasible for such documents, assuming XML encoding rules is not warranted.

This library wraps every ESI tag (opening, closing, or self-closing) in an HTML comment using the ESI comment syntax defined in Section 3.7 of the ESI specification (`\`). This hides the tags from the HTML5 parser while preserving them verbatim.

Important

During processing, ESI tags appear as Comment nodes in the DOM. If RewriteHandler transformations move or delete these comment nodes, the final result may not match expectations.

Credits, Copyright and License
------------------------------

[](#credits-copyright-and-license)

This library is based on internal work that we have been using at webfactory GmbH, Bonn, at least since 2012. However, that (old) code was written with the legacy PHP DOM extension, leading to several quirks in HTML processing and requiring the use of [Polyglot HTML 5](https://www.w3.org/TR/html-polyglot/)which is processable as XML.

-

Copyright 2026 webfactory GmbH, Bonn. Code released under [the MIT license](LICENSE).

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance79

Regular maintenance activity

Popularity15

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

108d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d4ed0a0f5a1c56f7df31bb8c854a2ad99d24281dc8df4b4d3dd986a9e84b7a24?d=identicon)[webfactory](/maintainers/webfactory)

---

Top Contributors

[![mpdude](https://avatars.githubusercontent.com/u/1202333?v=4)](https://github.com/mpdude "mpdude (13 commits)")

---

Tags

parserHTML5domtransformerrewriter

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/webfactory-html5-tagrewriter/health.svg)

```
[![Health](https://phpackages.com/badges/webfactory-html5-tagrewriter/health.svg)](https://phpackages.com/packages/webfactory-html5-tagrewriter)
```

###  Alternatives

[masterminds/html5

An HTML5 parser and serializer.

1.8k242.8M229](/packages/masterminds-html5)[paquettg/php-html-parser

An HTML DOM parser. It allows you to manipulate HTML. Find tags on an HTML page with selectors just like jQuery.

2.4k7.9M123](/packages/paquettg-php-html-parser)[sunra/php-simple-html-dom-parser

Composer adaptation of: A HTML DOM parser written in PHP5+ let you manipulate HTML in a very easy way! Require PHP 5+. Supports invalid HTML. Find tags on an HTML page with selectors just like jQuery. Extract contents from HTML in a single line.

1.3k9.4M61](/packages/sunra-php-simple-html-dom-parser)[simplehtmldom/simplehtmldom

A fast, simple and reliable HTML document parser for PHP.

1921.3M14](/packages/simplehtmldom-simplehtmldom)[scotteh/php-dom-wrapper

Simple DOM wrapper to select nodes using either CSS or XPath expressions and manipulate results quickly and easily.

1471.9M10](/packages/scotteh-php-dom-wrapper)[ressio/pharse

Fastest PHP HTML Parser

8478.4k](/packages/ressio-pharse)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)