HTML Purifier

HTML Purifier filters HTML from untrusted sources — user comments, WYSIWYG editor output, pasted rich text — by combining strict, per-element/per-attribute whitelists with aggressive, standards-aware parsing, rather than blacklisting known-bad patterns. The result is markup that isn’t just XSS-safe, it’s actually valid according to the (X)HTML doctype configured, which distinguishes it from simpler strip-tags-style sanitizers that leave behind malformed or invalid fragments.

It is oriented toward richly formatted content that needs a full tag set and CSS support (the kind produced by editors like TinyMCE or FCKeditor), and its extensive HTMLPurifier_Config system lets integrators dial the allowed tag/attribute/CSS surface up or down. Optional integrations with ext-tidy (pretty-printing), ext-iconv (non-UTF-8 encoding conversion), ext-bcmath (image-dimension/imagecrash protection), and cerdic/css-tidy (style-block extraction) round out the feature set.

What You Get

• A configurable HTMLPurifier class driven by HTMLPurifier_Config, controlling allowed HTML elements, attributes, CSS properties, and target doctype
• Standards-aware output: purified HTML validates against the configured (X)HTML doctype, not just “tag-stripped” text
• A full internal pipeline (lexer, Arborize, AttrValidator, ChildDef, CSSDefinition) modeling HTML’s actual content model rather than pattern-matching tags
• Optional ext-tidy, ext-iconv, ext-bcmath, and cerdic/css-tidy integrations for pretty-printing, encoding conversion, imagecrash protection, and style-block extraction
• A definition cache layer (DefinitionCache, DefinitionCacheFactory) so the (expensive) HTML/CSS definition build only runs once per configuration

Common Use Cases

• Sanitizing user-submitted comments, forum posts, or reviews before storing or rendering them
• Cleaning WYSIWYG editor (TinyMCE, FCKeditor/CKEditor) output before it reaches the database or the page
• Any CMS or publishing platform accepting rich HTML from semi-trusted authors that needs both XSS protection and valid markup
• Filtering HTML pulled from third-party feeds or APIs that must be embedded safely into a page’s existing document structure

Under The Hood

Architecture: The library, rooted at library/HTMLPurifier.php (297 lines) with dozens of supporting classes under library/HTMLPurifier/, models HTML purification as a genuine parse-and-rebuild pipeline rather than regex-based stripping: Lexer tokenizes input, Arborize builds a tree honoring HTML’s content model, ChildDef/ElementDef/AttrDef enforce what children/attributes each element may legally have, AttrValidator checks and rewrites attribute values (including AttrTransform for normalizing things like relative URLs), and CSSDefinition applies the same whitelist discipline to inline styles. A Context object threads shared state through the pipeline, and DefinitionCache/DefinitionCacheFactory persist the (expensive-to-build) HTML/CSS definitions across requests.

Tech Stack: Pure PHP with broad version support (PHP 5.6 through 8.5 declared in composer.json), zero required non-PHP-core dependencies, and optional integration points for ext-tidy, ext-iconv, ext-bcmath, and the separate cerdic/css-tidy package. Tests run via simpletest (a dev-dependency pulled from the author’s own fork), reflecting the project’s long history predating PHPUnit’s dominance; a Docker/docker-compose.yaml setup and GitHub Actions CI support modern contributor workflows on top of that legacy test harness.

Code Quality: With 99 contributors and continuous maintenance since the mid-2000s, the codebase carries real project-maturity signal, including a configdoc/ directory that documents every configuration directive, a smoketests/ suite, and benchmarks/ for performance tracking. The whitelist-first, content-model-aware design is itself a code-quality signal specific to this domain: correctness here means “never emits something the whitelist didn’t explicitly allow,” and the layered AttrDef/ChildDef/CSSDefinition classes make that guarantee auditable class-by-class rather than embedded in one large regex.

API Design: The common path is small — construct an HTMLPurifier with an HTMLPurifier_Config, call ->purify($html) — while the config object exposes a large, well-documented directive namespace (HTML.Allowed, CSS.AllowedProperties, URI.*, etc.) for teams that need finer control. Because configuration directly encodes the security policy, the API pushes integrators toward being explicit about what’s allowed rather than what’s blocked, which is the safer default for a sanitizer but does mean nontrivial setups require reading the extensive configdoc/ reference rather than guessing at options.