Download the PHP package diffen/justhtml without Composer

JustHTML for PHP

PHP HTML5 parser ported from Emil Stenström's JustHTML, targeting PHP 7.4+. Inspired by Simon Willison's JavaScript port, justjshtml. It is built for correctness and passes the html5lib test suite (tree builder, tokenizer, serializer, and encoding tests).

Why use JustHTML?

If you are on PHP 8.4+ and need to process a complete document, start with PHP's built-in DOM\\HTMLDocument. Its C implementation is faster and is a better fit for many projects.

Choose JustHTML when you need one or more of these:

• Pure PHP support across PHP 7.4 through 8.5.
• Browser-like handling of malformed HTML.
• CSS selectors plus HTML, text, and Markdown extraction helpers.
• Targeted extraction of a few known elements without always parsing and retaining the complete document.

For most tasks, start with the full parser shown below. The parsing guide explains when targeted extraction is worthwhile.

Requirements

• PHP 7.4+ (tested with 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5)
• ext-mbstring
• ext-iconv

Installation

Non-Composer use: include src/JustHTML/*.php with your autoloader and keep data/ alongside src/.

CLI via Homebrew (6.0.0+ requires a one-time trust step, which lets Homebrew run this MIT-licensed formula's install code):

Quickstart

Expected output:

Text extraction

toText() returns normalized human-readable text. textContent returns the exact text stored in the parsed DOM:

Output:

toText() concatenates DOM text first, collapses HTML whitespace runs to one space, and trims the complete result. It takes no arguments.

The read-only textContent property follows the DOM Node.textContent contract. It does not trim, collapse whitespace, or add separators at element boundaries. It includes script, style, and hidden text; br and block elements do not add line breaks. Document and doctype nodes return null. Template contents are available through $template->templateContent->textContent, not $template->textContent.

Run examples/text.php for a complete example of normalized text, DOM text content, and template content.

CSS selectors

Input HTML:

Expected output:

Multiple selectors (comma-separated):

Expected output:

Markdown

Note: toMarkdown() is a convenience helper (best-effort conversion) and not part of the HTML specification.

Detailed example (Wikipedia Earth)

The script loads examples/fixtures/wikipedia-earth.html and prints a walkthrough of selectors, attributes, classes, inner/outer HTML, text, and Markdown extraction.

Choosing a parsing API

For most crawling tasks, use the full parser shown in the quickstart. Choose Stream::select() only when you need one or a few known matches and want to avoid unnecessary work after finding them. Stop iteration to stop parsing:

This optimized path trades flexibility for lower work and memory: it supports a documented subset of CSS selectors, may offer little benefit when a match is late or absent, and returns nodes that should be treated as read-only while the generator is active. Like the full parser, it accepts a complete in-memory HTML string or byte buffer; it does not stream a network response or file in chunks.

See Streaming.md for a task-based decision guide, selector support, risks, encoding options, and the lower-level event API for specialized scanners.

CLI

For more detailed examples, see CLI.md.

For basic first-result extractions, the CLI automatically chooses a significantly faster parsing method when appropriate.

More examples:

Comparison to other parsers

Compliance results use the html5lib tree-construction tests. Performance results use a 1,000-document Common Crawl fixture set and report average milliseconds per document (lower is better). Compliance was verified and performance rerun on 2026-07-22 using PHP 8.5.8 with libxml 2.9.13.

See the benchmark guide for dependencies, reproduction commands, methodology, and historical results.

Lead paragraph extraction benchmark

This benchmark parses the bundled Wikipedia Earth fixture and extracts its first non-empty lead paragraph.

Example results (PHP 8.5.8, rerun 2026-07-22, 5-run average; all outputs match the JustHTML baseline):

For this selective early-result workload, Stream::select() was 2.19× faster than JustHTML's full-parser path and used 99.3% fewer retained parser nodes in a controlled memory proxy. The complete input string remains in memory with both APIs. These gains are most relevant when a crawler needs a small number of early matches; late, absent, or broad matches can erase the advantage. See the benchmark guide for the protocol and detailed results.

Tests

Test against multiple PHP versions via Docker:

Notes

• This repo includes a copy of html5lib tests in html5lib-tests.
• Ported from Emil Stenström's JustHTML (Python) under the MIT License.
• Inspired by Simon Willison's justjshtml port.
• Most of this work was done by GPT-5.2-Codex, with a little help from Claude Opus 4.5.