Tidy
The ext/tidy HTML repair and inspection API: tidy_* functions, the tidy and tidyNode classes, and PHP 8.5.10's 161 TIDY_* constants.
elephc implements PHP’s ext/tidy through the elephc-tidy bridge. The HTML engine
is libtidy itself — the same library PHP uses — pinned at 5.8.0 and supplied by the
managed native catalog as the libtidy package. The package is linked statically,
so compiled programs are still standalone binaries: the target machine needs neither
PHP nor a system libtidy. Every supported target (macos-aarch64, ios-arm64,
ios-sim-arm64, linux-aarch64, linux-x86_64) uses the same managed package path.
Enabling tidy
tidy needs a native package, so it is opt-in at the project level even though usage detection is automatic. Declare it once:
elephc native add libtidy
libtidy has no catalog dependencies of its own: the one native add builds the
pinned 5.8.0 sources and archives libtidy.a in the cache. See
Native dependencies for the full elephc native workflow (lock file, cache, elephc native install).
After that, an ordinary compile is enough — using any tidy_* function, the tidy
or tidyNode class, or ob_start('ob_tidyhandler') links the bridge and, with it,
the managed package:
elephc clean.php
Use --with-tidy when the surface is only reached at runtime, for example through
opaque dynamic eval() or a runtime-assembled new $class naming tidy or tidyNode; it
force-links the whole elephc_tidy archive and force-injects the prelude even when the
compiler sees no tidy usage:
elephc --with-tidy clean.php
Either way the project must declare libtidy: a compile that plans the bridge
without it fails closed with the elephc native add libtidy recovery, and there is
no fallback to a system -ltidy. extension_loaded('tidy') reports true whenever
the bridge is linked, natively and inside eval().
Both surfaces behave the same inside eval(), which runs the very same compiled
tidy / tidyNode declarations through Magician’s native-function bridge. A
literal eval() string is scanned for tidy function, class, and ob_tidyhandler
identifiers without parsing it, so ob_start('ob_tidyhandler') works in an inline
fragment too. Use --with-tidy when the only tidy call is assembled in opaque
dynamic eval() source, because the compiler cannot inspect that string.
Parsing and repairing
tidy_parse_string() and tidy_parse_file() return a tidy document object;
tidy_repair_string() and tidy_repair_file() return the repaired markup directly.
The configuration argument accepts an associative array of option names or a
libtidy configuration-file path:
$tidy = tidy_parse_string(
'<HTML><BODY BGCOLOR=#FFFFFF><B>Hi</B></BODY></HTML>',
['newline' => 'LF'],
);
tidy_clean_repair($tidy);
echo tidy_get_output($tidy);
$repaired = tidy_repair_string('<B>testing</I>', ['show-body-only' => true]);
// <b>testing</b>
tidy_diagnose() runs the configured accessibility and compatibility diagnostics.
The counts (tidy_error_count(), tidy_warning_count(), tidy_access_count(),
tidy_config_count()), tidy_get_status() and tidy_get_release() read libtidy’s
own state, so their values match the reference extension for the same pinned
library.
The tidy document object
tidy exposes PHP’s public $value and $errorBuffer properties, updated after a
successful parse, cleanRepair() or diagnose() exactly like php-src. echo $tidy
returns the repaired markup. The object methods mirror the procedural functions:
getOpt(), cleanRepair(), parseFile(), parseString(), diagnose(),
getRelease(), getConfig(), getStatus(), getHtmlVer(), getOptDoc(),
isXhtml(), isXml(), root(), head(), html() and body(). The static
repairString() / repairFile() methods are available as well.
tidy_get_config() returns every libtidy option in libtidy’s iterator order, with
string, integer and boolean values typed as PHP scalars. tidy_getopt() returns one
option’s current value; an unknown name is a ValueError, and a read-only option
cannot be set from the configuration array (ValueError).
The tidyNode object
tidyNode is final. Its nine readonly properties — value, name, type, line,
column, proprietary, id, attribute, child — are computed eagerly, including
the recursive child array, so var_dump() output matches php-src. Tree navigation
uses getParent(), getPreviousSibling() and getNextSibling(); the predicates are
hasChildren(), hasSiblings(), isComment(), isHtml(), isText(), isJste(),
isAsp() and isPhp().
A node casts to its serialized text with (string), to 0 with (int) / (float),
and to true with (bool), matching php-src’s object cast handlers.
Configuration files and output handling
tidy.default_config is loaded into every new document. tidy.clean_output=1
installs the automatic output buffer at startup, and ob_start('ob_tidyhandler')
installs it explicitly; the handler repairs the whole buffer on flush.
open_basedir is enforced for configuration-file paths and parsed file paths with
PHP’s normal open_basedir restriction in effect warning. In the constructor’s
EH_THROW window both configuration warnings and file-load failures become the base
Exception, while a malformed configuration file emits a notice and construction
continues.
Runtime limits
tidy.default_config,tidy.clean_outputandopen_basedirare compile-time INI values: they are baked into the binary by--ini. Runtimeini_set()calls do not change them.- The libtidy release is pinned at 5.8.0.
tidy_get_release()reports2021/07/10, the same value the reference extension reports for that library. - The bridge serializes each document on demand; very large documents therefore cost
a full libtidy save per
tidy_get_output()call, as in php-src.
Differences from PHP
- Display-layer blank lines. PHP prints a leading blank line before displayed diagnostics; elephc’s runtime does not. The migrated php-src case harness restores that separator before comparison, so the diagnostic text itself is still compared byte-for-byte.
tidy_parse_string()/tidy_parse_file()return type. The PHP-visible return istidy|false; elephc’s injected prelude declaresmixedso the static checker does not reject atidyresult passed to atidy-typed parameter after a failure check. Runtime behavior is unchanged: failure returnsfalse, success returns atidyobject.- Bridge string boundaries. Strings returned by the C bridge are NUL-terminated. An embedded NUL byte truncates the value; libtidy normally strips NUL bytes from HTML text, so this only affects deliberately embedded control bytes.
- Prelude adapters are visible to reflection. The
tidyandtidyNodeprelude classes carry compiler adapters such as__toString,__debugInfo,__clone, and__destruct;method_exists()and reflection can see those names while php-src’s internal classes expose only their documented surface. The__toStringadapter also makes both classes satisfyStringable, unlike php-src’s cast handlers. Runtime casts, cloning failures, and debug dumps still match PHP. - Configuration and encoding parameter reflection. The injected prelude declares
$configand$encodingasmixedso their public adapters can reproduce internal Tidy’s weak scalar coercion and exactTypeErrorordering. Reflection therefore reportsmixedwhere php-src reportsarray|string|nulland?string; ordinary calls and the documented signatures are unchanged. The checker restores the contract types fordeclare(strict_types=1)call-site validation, so strict scalar arguments are rejected at compile time; weak-mode calls keep the adapter’s runtime coercion andTypeErrorordering. ob_tidyhandleris callable. PHP registers it only as an output-handler alias; elephc also declares it as a prelude function soob_start('ob_tidyhandler')can resolve it. Calling it directly, andfunction_exists('ob_tidyhandler')returningtruein compiled code, are elephc extensions.- Configuration notices use
E_USER_NOTICE. A malformedtidy.default_configfile prints PHP’sNotice:text, but a custom error handler seesE_USER_NOTICEinstead of the engine’sE_NOTICElevel. - Old nodes after reparsing or
cleanRepair(). libtidy releases the previous tree whenparseString()/parseFile()parses again, so elephc invalidates everytidyNodehandle for the document before a reparse, including when the new parse fails. Their methods returnnull, empty values, orfalseinstead of reading freed memory. PHP 8.5.10 leaves reparse wrappers dangling; later 8.5 builds add a parse-generation check and throw anErrorinstead.cleanRepair()instead traverses the repaired tree and keeps handles whose node is still present, matching PHP 8.2–8.5; handles to nodes the cleaner removed answer through the same absent-handle fallbacks. Already cached readonly node properties remain readable. - Opaque dynamic
eval()source. Literaleval()strings are scanned for the tidy surface and link the prelude, sotidy_*,tidy/tidyNode, andob_start('ob_tidyhandler')work in an inline fragment. A string assembled at runtime is invisible to that scan: pass--with-tidy, or register the handler from compiled code, when the buffer is produced by opaque eval source. - Chunked
ob_tidyhandler. libtidy cannot repair cumulative chunks, so the handler leaves intermediate flushes untouched and repairs only the combinedSTART|FINALbuffer. php-src additionally rejects a non-zero chunk size with aCannot use a chunk size for ob_tidyhandlerwarning atob_start()time.
Functions {#functions}
Generated from the shared symbol catalog by scripts/docs/gen_module_sections.py; do not edit this section by hand. Each function links to its reference page.
| Function | Signature | Returns | AOT | eval() |
|---|---|---|---|---|
tidy_access_count() | (mixed $tidy): int | int | ✓ | ✓ |
tidy_clean_repair() | (mixed $tidy): bool | bool | ✓ | ✓ |
tidy_config_count() | (mixed $tidy): int | int | ✓ | ✓ |
tidy_diagnose() | (mixed $tidy): bool | bool | ✓ | ✓ |
tidy_error_count() | (mixed $tidy): int | int | ✓ | ✓ |
tidy_get_body() | (mixed $tidy): mixed | mixed | ✓ | ✓ |
tidy_get_config() | (mixed $tidy): array | array | ✓ | ✓ |
tidy_get_error_buffer() | `(mixed $tidy): string | false` | `string | false` |
tidy_get_head() | (mixed $tidy): mixed | mixed | ✓ | ✓ |
tidy_get_html() | (mixed $tidy): mixed | mixed | ✓ | ✓ |
tidy_get_html_ver() | (mixed $tidy): int | int | ✓ | ✓ |
tidy_get_opt_doc() | `(mixed $tidy, string $option): string | false` | `string | false` |
tidy_get_output() | (mixed $tidy): string | string | ✓ | ✓ |
tidy_get_release() | (): string | string | ✓ | ✓ |
tidy_get_root() | (mixed $tidy): mixed | mixed | ✓ | ✓ |
tidy_get_status() | (mixed $tidy): int | int | ✓ | ✓ |
tidy_getopt() | `(mixed $tidy, string $option): string | int | bool` | `string |
tidy_is_xhtml() | (mixed $tidy): bool | bool | ✓ | ✓ |
tidy_is_xml() | (mixed $tidy): bool | bool | ✓ | ✓ |
tidy_parse_file() | `(string $filename, array | string | null $config = null, ?string $encoding = null, bool $useIncludePath = false): mixed` | mixed |
tidy_parse_string() | `(string $string, array | string | null $config = null, ?string $encoding = null): mixed` | mixed |
tidy_repair_file() | `(string $filename, array | string | null $config = null, ?string $encoding = null, bool $useIncludePath = false): string | false` |
tidy_repair_string() | `(string $string, array | string | null $config = null, ?string $encoding = null): string | false` |
tidy_warning_count() | (mixed $tidy): int | int | ✓ | ✓ |
Classes: tidy, tidyNode.
Constants: 161 constants: TIDY_* (161).