API Reference

API Cheatsheet

Namespace HtmlPhp\. Identical in both editions. Everything instance-based; nothing reads globals. Full docblocks live in the source — this is the map.

Note

Canonical spec: docs/API.md.

Engine — the facade

$engine = Engine::create($configArrayOrObject, fn(Container $c) => …);

Method	Returns	Purpose
render(string $name, array $vars = [], ?RenderOptions $o = null)	string	locator-resolved template
renderFile(string $path, …)	string	host-trusted path (size-guarded, SSI-anchored)
renderString(string $source, …)	string	inline/DB templates
display(…) / displayString(…)	void	echo variants
processSsi(string $content, ?DocumentInfo $d = null)	string	standalone SSI pass
ssiVariables(?DocumentInfo $d = null)	array<string,string>	built-in SSI map
t / n / x / nx(…)	string	translations
setLocale(string) / locale()	—	active locale
loadTranslations(string $locale, ?string $domain)	list<string>	force-load i18n.paths
lint($nameOrPath) / lintString($src) / lintDirectory($dir)	list<LintIssue> / map	static validation
clearCache()	int	purge cache + parse memo
stats()	?RenderStats	last render's profile
config() container() renderer() locator() ssi() translator() filters() events() cache() logger() diagnostics() clock() linter() escaper()	service	lazy singletons
version()	string	"5.0.0 (8.3 edition)"

Container & service ids

Engine::create($config, function (Container $c): void {
    $c->instance(Contracts\CacheInterface::class, new MyRedisCache());
    $c->instance(Support\ClockInterface::class, new FrozenClock(1700000000));
    $c->instance(Log\LoggerInterface::class, Log\Psr3Adapter::wrap($monolog));
    $c->instance(I18n\TranslatorInterface::class, new MyDbTranslator());
});

Ids are class names: Config::class · Contracts\CacheInterface::class · Log\LoggerInterface::class · Event\Dispatcher::class · Diagnostics::class · Support\ClockInterface::class · Html\Escaper::class · I18n\Formats::class · I18n\TranslatorInterface::class · Template\{Filters, TemplateLocator, Renderer, Linter}::class · Ssi\Processor::class · Engine::class. API: factory(id, fn) instance(id, $obj) get has service<T>() ids reset.

Value objects

Class	Shape
Config (+9 group classes, 6 enums)	immutable, fromArray/toArray/merge/with*, validates at construction
Template\RenderOptions	readonly, all-nullable: file root request ssi structure autoEscape missingVar cache ttl locale ssiVars (+fromArray() migration aid)
Template\RenderStats	template durationMs cacheHit substitutions loops loopRows conditionals includes sections translations ssiDirectives outputBytes peakMemoryKb templates[] (+ summary hook in the 8.5 edition)
Template\LintIssue	readonly severity code message file line context + format()/isError()/toArray()
Ssi\DocumentInfo	readonly file root request vars + forString()/withVars()
RequestContext	readonly; fromServer($_SERVER) / cli($cwd) / http(name)
Scope	push/pop/with/get/has/set/find/all/depth — dot paths over arrays, ArrayAccess, props, get*/is*/has* accessors; no globals fallback. v5 statics: Scope::step(value, path) (dotted walk) and Scope::index(value, key) (one dynamic key — arrays / ArrayAccess / UTF-8 string offsets only, never object props)

Events (tag → payload)

Tag	Kind	Payload
htmlphp.render.before	action	origin, vars, renderContext
htmlphp.render	filter	text, origin, vars
htmlphp.render.after	action	origin, text
htmlphp.rendered	action	RenderStats
htmlphp.error	action	code, message, context
htmlphp.translate	filter	text, msgid, domain, locale
htmlphp.translate.miss	action	msgid, domain, locale
htmlphp.filter.apply	action	filterName, args
htmlphp.ssi.builtins	filter	built-in map
htmlphp.ssi.include_path	filter	resolvedPath, label
htmlphp.ssi.echo	filter	value, name

Dispatcher: on(tag, cb, prio=10): Closure(unsubscribe) · dispatch · filter (null keeps previous) · off/has/tags/reset.

Contracts & implementations

Contracts\CacheInterface { get set has delete clear(): int }
  ├─ Cache\FileCache (sharded, atomic, probabilistic GC, dir hardening)
  ├─ Cache\ApcuCache · ArrayCache · NullCache · Psr16Adapter
  └─ WordPress\WpCache (object cache + transients + key registry)

Log\LoggerInterface { log debug info notice warning error critical alert emergency }
  ├─ Log\FileLogger · ErrorLogLogger · SyslogLogger · ArrayLogger · NullLogger
  ├─ Log\Psr3Adapter (wraps Monolog & friends — no psr/log required)
  └─ WordPress\WpLogger

I18n\TranslatorInterface { t n x nx locale setLocale }
  └─ I18n\Translator (own implementation; WP delegation built in)

Support\ClockInterface { now dateTime }
  ├─ SystemClock └─ FrozenClock (tests/CLI)

Ssi\DirectiveInterface { name render(attrs, SsiContext) }

Exceptions

HtmlPhpException  (readonly context map, withContext(), describe())
├─ ConfigException        ├─ ContainerException   ├─ IoException
├─ CacheException         ├─ RegexException       ├─ SsiException
├─ I18nException          └─ TemplateException
                              ├─ TemplateNotFoundException
                              └─ TemplateSyntaxException   (file + line in context)

Support utilities worth knowing

Class	Highlights
Support\Str	stringify (enum/Stringable-safe) · numericValue (intl formats) · round/cleanRound/number/divide · v5: power/sqrt (INF/NAN → 0.0), accumulate (capped sum+count, MAX_AGGREGATE_ITEMS = 100 000) · truncate (word-boundary, mb) · slugify (deterministic: built-in map first, ICU fallback for unmapped scripts) · normalizeEntities · formatSize (Apache style) · isValidVariableName · sanitizeRecursive
Template\Expression	closed interpreter behind @If/@Set/loop ranges/@Trans count and v5 inline %{= …}: evaluate/validate/truthy/reset, FUNCTIONS whitelist (23). Budgets: length, depth 32, AST memo 4 096 FIFO, iterable walks 100 000
Template\Substitution	public statics for host tooling: splitFilters · v5: splitExpressionPayload (quote/bracket-aware) · splitArguments · parseSegments
Support\Pcre	throwing wrappers (replace/replaceCallback/split), degrading match/matchAll, replaceUnicode, isValid
Io\Files / AtomicWriter / PathGuard	capped slurp · temp+verify+rename writes · realpath containment + extension deny-lists
Html\Escaper	html attr url json js css byStrategy sanitizeArray; subclassable/replaceable
Html\Cleaner	cleanHtml (allow-list, script/style removal) · normalize · lcTags · trimSpaces
Input	all()/source() — sanitised superglobal copies (the sanctioned edge)
I18n\{Extractor, Auditor, Formats}	POT extraction w/ references · missing/unused audit · locale number/date/ago

WordPress namespace

WordPress\Bridge (boot/engine/booted/reset) · TemplateLoader · Shortcodes · WpCache · WpLogger · AdminPage · Cli · Mailer · Maintenance\{Nonces Options Transients Notices Db Cron Logs SystemInfo Updates Health Assets Rest} → WordPress Integration