Download the PHP package wackowiki/htmlsax3 without Composer

HTMLSax3

A modernized PHP 8.5-compatible port of the classic HTMLSax3 SAX-style parser for HTML/XML, maintained by the WackoWiki team. Drop-in compatible with the original API, fully strict-typed, namespace-clean, and free of legacy PEAR dependencies.

Originally ported from Python to PHP by Alexander Zhukov, then refactored for PEAR by Harry Fuecks, with extensive contributions from the Sitepointforums Advanced PHP community.

Features

• PHP 8.5 ready — strict types, constructor property promotion, match expressions, readonly properties where applicable, no legacy quirks.
• Zero PEAR dependency — the original PEAR::raiseError() calls have been replaced with native InvalidArgumentException.
• PSR-4 autoloaded under the HTMLSax3\ namespace with sub-namespaces for States\ and Decorators\.
• Fully decorator-driven options system — trim, case-folding, entity parsing, escape stripping, linefeed/tab breaks.
• Lightweight — no external dependencies, runs anywhere PHP 8.5+ runs.
• Used in production by SafeHTML and WackoWiki.

Installation

Via Composer (recommended)

As a local path repository in WackoWiki

In your WackoWiki composer.json:

The symlink: true option means edits to your local src/lib/HTMLSax3/ are picked up immediately without re-running composer update.

Manual installation

If you can't use Composer, require the autoloader (or each file in dependency order):

Namespace map

All classes live under HTMLSax3\:

The parser-state constants (STATE_START, STATE_TAG, STATE_OPENING_TAG, STATE_CLOSING_TAG, STATE_ESCAPE, STATE_JASP, STATE_PI, STATE_STOP) are declared as global constants at the top of src/States/StateParser.php for backward compatibility with code that referenced them directly.

Quick start

Output:

API reference

HTMLSax3 — the user-facing class

__construct()

Instantiates the parser, attaches a NullHandler as the default handler for every callback channel, and pre-creates all state objects.

set_object(object &$object): true

Attaches the user handler object. Stored by reference so that decorators can wrap it in place.

set_option(string $name, int $value = 1): true

Switches parser options on or off. Throws InvalidArgumentException for unknown options.

set_data_handler(string $method): void

Sets the name of the data handler method on the attached handler object.

set_element_handler(string $open_method, string $close_method): void

Sets the names of the open and close tag handler methods.

set_pi_handler(string $method): void

Sets the name of the processing-instruction handler method.

set_escape_handler(string $method): void

Sets the name of the XML-escape handler method (comments, CDATA, doctype).

set_jasp_handler(string $method): void

Sets the name of the JSP/ASP <% %> handler method.

get_current_position(): int

Returns the current cursor position inside the parsed document.

get_length(): int

Returns the length of the document being parsed.

parse(string $data): void

Begins parsing $data. All callbacks fire on the attached handler object.

Handler object signature

Each callback should return true. Returning false does not halt parsing (this matches the original HTMLSax3 semantics).

Migration from the original HTMLSax3

The public API is fully preserved. Existing handler code works without modification. The only breaking changes are:

If you have a non-Composer installation that referenced HTMLSax3\StateParser at the root, add this to your bootstrap:

Development

Requirements

• PHP 8.5 or later
• Composer

Setup

Running tests

Directory layout

Related projects

• SafeHTML — the HTML sanitizer that uses HTMLSax3 to strip dangerous markup. Maintained in the same monorepo.
• WackoWiki — the wiki engine that originally bundled this parser.

Contributing

Pull requests welcome! Please ensure:

• All tests pass (composer test)
• PHPStan is clean (composer stan)
• Code style is consistent (composer cs-check)

For bug reports and feature requests, open an issue at https://github.com/WackoWiki/htmlsax3/issues.

License

This project is licensed under the BSD 3-Clause "New" or "Revised" License — see the LICENSE file for details.

Historical note: The original HTMLSax3 source carried a PHP License 3.0 header. That license has been retired by the PHP project and superseded by the PHP License 4.0, which is itself the BSD 3-Clause License. As this library is no longer part of the PEAR ecosystem, the BSD-3-Clause terms now govern all use, modification, and distribution. The original copyright holders are preserved in the LICENSE file for historical accuracy.