HtmlDocument

MMO\core\documents · 1 symbol · generated 5 Oct 2026

class

HtmlDocument

An HTML XmlDocument (rendered via HtmlPrinter), with a ready-made <html><head>...</head><body>...</body></html> skeleton (createBody): a charset/viewport meta, an <base href> set to the current URL, and (unless

class MMO\core\documents\HtmlDocument extends MMO\core\documents\XmlDocument

Namespace: MMO\core\documents
Extends: XmlDocument
See: Document::isRaw, e.g. for an email body) a collapsible "SERVER CONSOLE" block that recorded, Log entries are rendered into (by HtmlPrinter, which escapes their message and backtrace).

$doc = new HtmlDocument(); $doc->setTitle('My Page'); $doc->addStylesheet('/css/main.css'); echo $doc->render();

Index

	addBreadcrumb($link)	Add a link tagged 'breadcrumb' (in addition to any rel(s) it already has).
	addInlineScript($script, $inHeader)	Append raw JS to a single shared inline `<script>` node (creating it on first use).
	addMenu($link)	Add a link tagged 'menu' (in addition to any rel(s) it already has).
	addNavigation($link)	Add a link tagged 'navigation' (in addition to any rel(s) it already has).
	addScript($url, $inHeader)	Add a `<script src="...">`.
	addStylesheet($url, $first)	Add a `<link rel="stylesheet">` to the `<head>`.
	createBody($charset, $opts)	Build the `<html><head>...</head><body>...</body></html>` skeleton.
	getBreadcrumbs()
	getMenus()
	getMeta($name, $key)	Get the html header's meta tag(s).
	getNavigations()
	getScriptVariable($name)
	getTitle()
	import($_FILENAME, $_VARS, $_KEY)	Same as `Document::import`, but $_KEY defaults to 'body' (imported content is appended there, not to the document root).
	render($opts)
	setFavicon($url, $type)	Set (or replace) the favicon `<link>`.
	setMeta($name, $content, $key)	Add or set meta to the html header
	setScriptVariable($name, $value)	Expose a value as a `window`-scope JS variable (via a shared `<head>` `<script>` node), e.g.
	setTitle($text)	Set (or replace) the `<title>`.
	startCapture($key)	Same as `Document::startCapture`, but $key defaults to 'body'.
	__construct($body, $opts)

Methods21

addBreadcrumb($link)

HtmlDocument.php:77

Add a link tagged 'breadcrumb' (in addition to any rel(s) it already has). getBreadcrumbs

function addBreadcrumb(Psr\Link\LinkInterface|array|string $link): MMO\core\server\Link

$link	`LinkInterface` \| array \| string
returns	Link

addInlineScript($script, $inHeader)

HtmlDocument.php:212

Append raw JS to a single shared inline <script> node (creating it on first use). It is printed as it is, also in a document that escapes the strings it prints (HtmlPrinter::exportRenderable).

function addInlineScript(string $script, bool $inHeader = true): self

$script	string
$inHeader = true	bool	if true (default), append to the `<head>`'s inline script; otherwise the `<body>`'s.
returns	self	for chaining.

addMenu($link)

HtmlDocument.php:101

Add a link tagged 'menu' (in addition to any rel(s) it already has). getMenus

function addMenu(Psr\Link\LinkInterface|array|string $link): MMO\core\server\Link

$link	`LinkInterface` \| array \| string
returns	Link

addNavigation($link)

HtmlDocument.php:89

Add a link tagged 'navigation' (in addition to any rel(s) it already has). getNavigations

function addNavigation(Psr\Link\LinkInterface|array|string $link): MMO\core\server\Link

$link	`LinkInterface` \| array \| string
returns	Link

addScript($url, $inHeader)

HtmlDocument.php:198

Add a <script src="...">.

function addScript(string $url, bool $inHeader = true): self

$url	string	if it is a relative url or a filename, will resolve the alias and trigger the makefile if any
$inHeader = true	bool	if true (default), add it to the `<head>`; otherwise the `<body>`.
returns	self	for chaining.

addStylesheet($url, $first)

HtmlDocument.php:186

Add a <link rel="stylesheet"> to the <head>.

function addStylesheet(string $url, bool $first = false): self

$url	string	if it is a relative url or a filename, will resolve the alias and trigger the makefile if any
$first = false	bool	if true, insert before every existing `<head>` child; otherwise (default) append last.
returns	self	for chaining.

createBody($charset, $opts)

HtmlDocument.php:41

Build the <html><head>...</head><body>...</body></html> skeleton. Unless $opts['raw'] is true, also builds the "SERVER CONSOLE" block (kept in $logs, see logEvent) and includes it in the body.

protected function createBody(string $charset, array $opts = []): MMO\core\helpers\XmlNodes

$charset	string
$opts = []	array
returns	XmlNodes

getBreadcrumbs()

HtmlDocument.php:84

function getBreadcrumbs(): array

returns array every link tagged 'breadcrumb' (see addBreadcrumb), in the order added.

getMenus()

HtmlDocument.php:108

function getMenus(): array

returns array every link tagged 'menu' (see addMenu), in the order added.

getMeta($name, $key)

HtmlDocument.php:171

Get the html header's meta tag(s).

function getMeta(?string $name = null, string $key = 'name'): array|string|null

NOTE: this used to `return $this->body['head']['meta']` (an XmlNodes object) for $name === null, and `return $meta` (an XmlNode) for a single match -- neither actually satisfies the declared `array`/`string` return type, so PHP was silently coercing both through `__toString()` (since neither type is an `array`), returning the node(s) rendered as markup instead of their content. Fixed to match [`setMeta`](https://mcp.mmoframework.fr/documentation/mmo.core/php/documents/HtmlDocument.md#htmldocument-setmeta)'s counterpart role (getter/setter for a meta tag's content): an array of nodes for $name === null (via

See: XmlNodes::toArray), and the matched node's own content string otherwise.

$name = null	null \| string	if null, return every meta node; otherwise, only the one matching $key.
$key = 'name'	string	can be 'name','property','http-equiv'
returns	array \| string \| null	the found meta's content string, every meta node (as an array) if $name is null, or null if $name doesn't match any meta.

getNavigations()

HtmlDocument.php:96

function getNavigations(): array

returns array every link tagged 'navigation' (see addNavigation), in the order added.

getScriptVariable($name)

HtmlDocument.php:239

function getScriptVariable(string $name): ?MMO\core\helpers\JSVariable

$name	string
returns	null \| JSVariable	the variable set via `setScriptVariable`, or null if none.

getTitle()

HtmlDocument.php:126

function getTitle(): ?string

returns null | string the <title>'s text, or null if none is set.

import($_FILENAME, $_VARS, $_KEY)

HtmlDocument.php:113

Same as Document::import, but $_KEY defaults to 'body' (imported content is appended there, not to the document root).

function import( string $_FILENAME, ArrayAccess|array $_VARS = [], string|false|null $_KEY = 'body' ): MMO\core\helpers\OutputCapture

$_FILENAME	string
$_VARS = []	ArrayAccess \| array
$_KEY = 'body'	string \| false \| null
returns	OutputCapture

render($opts)

HtmlDocument.php:72

function render(array $opts = []): string

$opts = []	array
returns	string	the document with a leading `<!DOCTYPE html>`.

setFavicon($url, $type)

HtmlDocument.php:253

Set (or replace) the favicon <link>.

function setFavicon(string $url, ?string $type = null): self

NOTE: auto-detecting the mime type from the URL's extension used to call `strrpos('.', $url)` -- backwards (haystack/needle swapped: that's "does '.' contain $url", which is essentially never true), so $type was silently never auto-detected for any real URL. Fixed to `strrpos($url, '.')`.

$url	string	if it is a relative url or a filename, will resolve the alias and trigger the makefile if any
$type = null	null \| string	mime type; auto-detected from $url's extension (via `mime`) when null.
returns	self	for chaining.

setMeta($name, $content, $key)

HtmlDocument.php:148

Add or set meta to the html header

function setMeta(string $name, string $content, string $key = 'name'): void

$name	string
$content	string
$key = 'name'	string	can be 'name','property','http-equiv'
returns	void

setScriptVariable($name, $value)

HtmlDocument.php:228

Expose a value as a window-scope JS variable (via a shared <head> <script> node), e.g. to pass server-side data to client-side JS.

function setScriptVariable(string $name, mixed $value): MMO\core\helpers\JSVariable

$name	string	the JS variable name.
$value	mixed	any JSON-encodable value.
returns	JSVariable	the created/replaced variable (see `JSVariable`).

$doc->setScriptVariable('config', ['apiUrl' => '/api']); // window.config = {"apiUrl": "/api"};

setTitle($text)

HtmlDocument.php:135

Set (or replace) the <title>.

function setTitle(string $text): void

$text	string	text, not markup: held as an `XmlText`, it is escaped when the page is printed
returns	void

$doc->setTitle('Search: ' . $_GET['q']); // a `</title><script>` in the query stays text

startCapture($key)

HtmlDocument.php:118

Same as Document::startCapture, but $key defaults to 'body'.

function startCapture(string|false|null $key = 'body'): MMO\core\helpers\OutputCapture

$key = 'body'	string \| false \| null
returns	OutputCapture

__construct($body, $opts)

HtmlDocument.php:27

function __construct( ?MMO\core\helpers\XmlNodes $body = null, MMO\core\interfaces\iOptions|array $opts = [] )

$body = null	null \| XmlNodes	defaults to `createBody`'s result.
$opts = []	iOptions \| array

new HtmlDocument(null, new DocumentOptions(print: new PrintOptions(escape: true))); // its values HTML-escaped

Inherited members (52)

Properties	Declared by	Description
`body`	Document
`importPaths`	Document
`links`	Document
`logs`	Document
`meta`	Document	Free-form metadata about this document (e.g.
`opts`	Document
`readOnly`	Document	If true, the document's body/links/meta can no longer be modified (setters throw `eRuntime`).

Methods	Declared by	Description
`absoluteUrl($url)`	XmlDocument	Resolve $url against this document's own URL (`getUrl`), or against the application's own base URL if this document has none.
`addContent($data)`	Document	Recursively merge $data into the current body (see `merge`).
`addImportPath($path, $first)`	Document	Add one base directory to the import search paths.
`addLink($link)`	Document	Append a link to this document.
`addMeta($data)`	Document	Recursively merge $data into `$meta` (existing keys are overwritten, not combined -- see `merge`'s `$combine` argument).
`addOptions($opts, $appendList)`	Document	Merge $opts into the existing options (through `merge`), rather than replacing them wholesale like `setOptions`.
`addVars($vars)`	Document	Merge extra variables into the set made available to `import()-ed` files.
`clearLogs()`	Document	Discard all recorded logs.
`clearOptions()`	Document	Empty the options bag.
`createNode($tag, $attrs, $nodes)`	XmlDocument	Build a new XML node (`XmlNodes::create`), without adding it to the document: there is no one right place for it.
`createStream()`	Document
`findImportPath($filename)`	Document	Resolve a relative filename against `getImportPaths` (first match wins).
`getBody()`	Document
`getImportPaths()`	Document
`getLinkByRel($rel)`	Document
`getLinks()`	Document	Returns an iterable of LinkInterface objects.
`getLinksByRel($rel)`	Document	Returns an iterable of LinkInterface objects that have a specific relationship.
`getLogs()`	Document
`getOption($key, $default)`	Document
`getOptions()`	Document
`getPrinter()`	Document
`getUrl()`	XmlDocument
`getVars()`	Document	Get the variables available for import
`hasLogs($flag)`	Document
`isImportValid($filename)`	Document
`isRaw()`	Document
`jsonSerialize()`	Document
`logEvent($event)`	Document	Record a log/event on this document, e.g.
`offsetExists($offset)`	Document	ArrayAccess: `isset($document[$offset])` -- true for a body entry with a non-null value, or, when the body is a plain array, for any existing key (including one whose value is null).
`offsetGet($offset)`	Document	ArrayAccess: `$document[$offset]` -- returns null for a missing entry, same as `$document[$offset] ??
`offsetSet($offset, $value)`	Document	ArrayAccess: `$document[$offset] = $value` sets a body entry (`$document[] = $value` appends).
`offsetUnset($offset)`	Document	ArrayAccess: `unset($document[$offset])` removes a body entry.
`Raw($body, $opts)`	Document	Build a document whose `isRaw` is true from the start (see `setRaw` for what "raw" means).
`removeLink($link)`	Document	Remove a link (by identity).
`renderValue($value, $opts)`	Document	Render an arbitrary value through this document's printer (`getPrinter`, or `TextPrinter` by default), merging $opts over the document's own options.
`setBody($body)`	Document	Replace the document's content, then dispatch `DocumentInit`.
`setImportPaths($paths)`	Document	Replace the base directories searched by `findImportPath`/`import` for a relative filename.
`setLogs($logs)`	XmlDocument	Replace the whole log collection.
`setOption($key, $value)`	Document	Set (or, with a null $value, remove) a single option.
`setOptions($opts)`	Document	Replace the whole options bag.
`setPrinter($printer)`	Document
`setRaw($raw)`	Document	Tells a document should be left as `raw` as possible.
`setUrl($url)`	XmlDocument	Set this document's canonical URL (as a 'current' link -- see `LinkProviderInterface`), used as the base for `absoluteUrl`.
`setVars($vars)`	Document	Replace the variables made available to `import()-ed` files (a 'document' => $this var is always added at construction, see `__construct`).
`__toString()`	Document