Masterminds/html5-php: HTML5 Parsing and Serialization in PHP

Why Masterminds/html5-php Exists in PHP Applications

Masterminds/html5-php addresses a specific problem in PHP document processing: parsing and writing HTML5 without treating the input as XML. The README describes the project as an HTML5 parser and writer written entirely in PHP, running on PHP 7.4 or newer. It is intended for PHP code that needs to read HTML, build a DOMDocument, inspect or modify the resulting tree, and write HTML5 again.

The library is not limited to one API shape. Its high-level `HTML5` class provides document loading and saving, while the lower-level API exposes a SAX-like event parser, configurable error reporting, and a DOM implementation based on PHP's built-in DOM library. This makes it relevant to applications that receive markup from users, process templates, transform document fragments, or need a serializer whose behavior follows the HTML5 serialization rules documented by the project.

The project also lists interoperability with QueryPath. That matters when an application works with DOM-like trees but needs an HTML5-oriented parser and writer. The README does not describe a command-line application, a hosted service, or a JavaScript runtime. Its scope is a library embedded in PHP projects.

The library is not a browser engine. It recognizes document structure and creates or serializes markup, but it does not execute scripts or apply CSS. The architecture therefore belongs after text acquisition and before application-specific DOM processing. For code that only needs narrow string replacement, treating it as a full HTML5 parser may add more machinery than the job requires. Conversely, code that needs standards-oriented tokenization and a document tree receives a purpose-built API rather than a collection of ad hoc regular expressions.

Inside the Scanner, Tokenizer, EventHandler, and DOMBuilder Chain

The documented parsing path is divided into four cooperating parts. `Scanner` handles scanning on behalf of the parser. `Tokenizer` requests data from the scanner, parses it, classifies it, and sends semantic events to an `EventHandler`. The README describes the tokenizer as a recursive descent parser.

`DOMBuilder` is an event handler that listens for those parsing events and constructs a `DOMDocument` tree. At the high level, `HTML5::loadHTML()` sends HTML through this machinery and returns a full `DOMDocument`. The result can be inspected with PHP DOM APIs, modified, or passed back to the serializer.

For applications that do not need a complete tree, the SAX-like event API provides a lower-level route. An `EventHandler` can receive notifications and data for semantic events as tokenization proceeds. The documentation also describes a flexible error-reporting mechanism that can be tuned for document syntax checking. The README does not enumerate every event name, handler method, or error setting, so those details must be checked in the public API documentation or source before an integration depends on them.

Namespace handling is explicit rather than automatic in every context. By default, the parser supports HTML5's selected namespace model, where `:` has no special XML-style meaning. The README provides the `implicit_namespaces` option and points to an XML Namespaces section for enabling XML-style namespace handling. This distinction matters when input contains prefixed elements or when downstream DOM tools expect XML namespace semantics.

The architecture offers a clear choice between two processing models. `DOMBuilder` converts the event stream into a complete document when a tree is needed, while a custom handler can process selected events when only stream processing is needed. The same parser foundation supports both paths, although choosing the high-level tree does not remove the parser's tokenization and event overhead.

Composer Installation and a First PHP Parse

The documented installation uses Composer. Add the package to `composer.json` with the following dependency:

{
  "require" : {
    "masterminds/html5": "^2.0"
  }
}

The README also gives this command for adding the dependency to an existing PHP project:

composer require masterminds/html5

After installation, the first real use is to load Composer's autoloader, create an `HTML5` instance, parse a document, and print or save the result. This compact version follows the API shown in the README:

<?php
require "vendor/autoload.php";

use Masterminds\HTML5;

$html = "<html><head><title>TEST</title></head><body id='foo'><h1>Hello World</h1></body></html>";
$html5 = new HTML5();
$dom = $html5->loadHTML($html);
print $html5->saveHTML($dom);

The call to `loadHTML()` returns a `DOMDocument`. Passing that document to `saveHTML()` prints serialized HTML, while `save()` can write it to a file. The README does not document command-line operation, so Composer installation followed by inclusion from PHP code is the confirmed workflow.

The constructor accepts an associative array of options. `encode_entities` controls aggressive entity encoding. `disable_html_ns` prevents automatic assignment of the HTML5 namespace for non-namespace-aware DOM tools. `target_document` supplies an existing `DOMDocument` as the destination for parsed nodes. `implicit_namespaces` maps tag prefixes to namespace URIs. These settings belong on the `HTML5` instance before `loadHTML()` runs when they affect a parse.

The package requirement is `^2.0`, while the repository also lists individual 2.x releases. Composer resolves the eligible version for the project's PHP constraints and dependency graph. A first integration should therefore inspect the resulting lock file rather than assuming that the repository's newest listed release will always be installed.

Serialization Rules Behind saveHTML and save

Serialization is implemented separately from parsing. `OutputRules` defines how DOM elements become strings through `RulesInterface`. `Traverser` walks the document tree and applies those rules. `HTML5` manages the traverser and places the resulting data in the required output.

The README states that the serializer follows section 8.9 of the referenced HTML 5.0 specification. Its documented examples distinguish three cases. A tag with children is written as `<foo>CHILDREN</foo>`. A tag that cannot have content is written as `<foo>` without a closing tag. A tag that can have content but currently has none is written as `<foo></foo>`.

This separation has a practical consequence. A DOM tree is not simply echoed back as the original input. The serializer applies element rules while traversing the tree, and the `encode_entities` option changes how characters are represented in output. Without aggressive encoding, the README says the serializer encodes only the bare minimum. Applications that compare source and output text should expect structural normalization rather than guaranteed byte-for-byte preservation.

The `RulesInterface` boundary also means that serialization rules are not tied directly to the event parser. Code can use the high-level convenience API, while lower-level integrations can examine the documented rules and traverser components. The README says every public function is documented and that unit tests exercise each API area, but it does not publish compatibility guarantees for exact output formatting across every release.

When preserving source formatting matters, the acceptance criteria should include representative fixtures rather than only successful parsing. Empty elements, entities, namespace attributes, implied elements, and malformed input can all affect the relationship between a source string and serialized output. The README documents the governing model but does not provide a complete output corpus for checking those cases.

Namespace, Script, and Error-Handling Boundaries

The largest documented constraint is namespace behavior. HTML5 supports a selected namespace set and does not treat namespaces exactly like XML. The README specifically says that `:` has no special meaning by default. Applications expecting arbitrary XML-style prefixes must not assume that the default parser will interpret them as XML namespaces. The `implicit_namespaces` option supplies mappings for namespace-aware parsing, while `disable_html_ns` exists for non-namespace-aware DOM tools.

This design makes the project different from an XML parser. In XML, namespace syntax and processing rules follow XML conventions. In this HTML5 library, namespace behavior follows the selected HTML5 model unless the documented configuration changes it. Code migrating from `DOMDocument` XML processing should examine this distinction before using prefixed markup or asserting namespace URIs.

The library also does not contain a JavaScript or CSS interpreter. It handles markup but does not run scripts found inside documents or interpret stylesheets. Consumers that need browser-side behavior still need a separate execution environment. A successful parse says nothing about whether embedded code is valid, safe to run, or visually correct in a browser.

The error-reporting mechanism is described as flexible and tunable for syntax checking, but the README excerpt gives no configuration example for it. That leaves a concrete verification point for adopters: inspect the API documentation and source before assuming that malformed markup causes exceptions, warnings, or a particular reporting mode.

The repository includes `src/`, `test/`, `bin/`, `example.php`, `phpunit.xml.dist`, `UPGRADING.md`, and `RELEASE.md`. Based on this layout, the project is primarily a library with tests, examples, and release documentation rather than an application with a documented user-facing service.

Masterminds/html5-php Compared with Direct DOMDocument Processing

The closest alternative approach is to use PHP's built-in DOM facilities directly and write application-specific parsing and serialization code around them. The difference is architectural. Masterminds/html5-php places an HTML5-oriented scanner, tokenizer, event handlers, tree builder, output rules, and traverser between the application and PHP's `DOMDocument`. Direct DOM processing leaves more parsing and output behavior inside the application.

The package is a better fit when the application needs HTML5 event processing, DOM construction through the documented pipeline, or serialization based on the referenced HTML5 rules. Its low-level API can serve code that wants semantic events instead of a complete tree. QueryPath interoperability is another documented consideration for applications that already use DOM-oriented querying and transformation tools.

Direct DOMDocument handling may be more appropriate when the application already has a fixed XML-compatible grammar, its own parsing behavior, or output rules that must remain independent of this library. The README does not publish a compatibility benchmark, so the practical distinction is the processing model rather than a claimed performance advantage. Masterminds/html5-php supplies HTML5-specific components; direct DOM code gives the application control but requires it to implement or select those behaviors elsewhere.

Another alternative is application-specific string or regular-expression processing. That approach can be sufficient for a small, fixed substitution, but it does not provide the documented tokenizer, event stream, DOM tree, or HTML5 serializer. The decision therefore depends on whether the application needs structured document handling or only literal text replacement.

Maintenance, Releases, Licensing, and Upgrade Checks

The repository is not archived, and its last push was on 2026-08-18. Recent releases listed with the repository are 2.11.0 on 2026-08-18, 2.10.1 on 2026-06-23, and 2.10.0 on 2025-07-25. That history shows releases across several dates in 2025 and 2026. The README calls the project stable, but repository activity is best described through the dated release and push facts rather than through a broad maintenance claim.

The documented runtime requirement is PHP 7.4 or newer. Applications need to confirm that their runtime satisfies this minimum. Composer is the documented installation mechanism, and the package name is `masterminds/html5`. Updating through Composer changes the installed version and may expose differences in parsing, namespaces, entities, error handling, or serialization.

The repository contains `UPGRADING.md`, which is the specific file to inspect for version migration instructions. The README does not summarize that file, so it cannot establish which releases require code or configuration changes. The repository also does not document a rollback procedure in the README. Teams therefore need to check their own Composer lock and deployment process rather than assuming that downgrade behavior is guaranteed by this project.

Licensing requires a separate check. GitHub classifies the repository license as a custom license that it cannot map to a standard category, and the repository identifies `LICENSE.txt` as the governing file. The README excerpt does not state its permissions, conditions, or warranty terms. No legal conclusion can be drawn from the repository classification alone; the actual file must be reviewed before use or redistribution.

Editorial conclusion

Adopt Masterminds/html5-php when a PHP application needs an HTML5 parser, DOM tree, event stream, or serializer and can accept the documented PHP 7.4 minimum. Do not choose it for JavaScript execution, CSS interpretation, unrestricted XML-style namespace behavior, or workloads that require XML rather than HTML parsing. Before adoption, read LICENSE.txt, confirm that the PHP and Composer setup matches the application, and test the documented parser options against the namespace and serialization behavior required by downstream code.

Frequently asked questions

Official sources

1. Issues
2. Masterminds/html5-php on GitHub
3. Project website
4. README
5. Releases