Document

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

class

Document

A renderable container for a controller/response's output data (its "body"), plus metadata: HTTP-style Links (LinkProviderInterface), request/response logs (Log), free-form meta.

class MMO\core\documents\Document implements ArrayAccess, Psr\Link\LinkProviderInterface, MMO\core\interfaces\iRenderable, JsonSerializable use MMO\core\classes\tWithOptions

Namespace: MMO\core\documents
Implements: ArrayAccess, LinkProviderInterface, iRenderable, JsonSerializable
Uses traits: tWithOptions

It is an ArrayAccess over its body, so content can be merged directly into it, e.g. `\MMO\core\arrays\merge($this, [...])`. Rendering ([`render`](https://mcp.mmoframework.fr/documentation/mmo.core/php/documents/Document.md#document-render)/[`__toString`](https://mcp.mmoframework.fr/documentation/mmo.core/php/documents/Document.md#document--tostring)) is delegated to a printer ([`getPrinter`](https://mcp.mmoframework.fr/documentation/mmo.core/php/documents/Document.md#document-getprinter)/[`setPrinter`](https://mcp.mmoframework.fr/documentation/mmo.core/php/documents/Document.md#document-setprinter), falls back to [`TextPrinter`](https://mcp.mmoframework.fr/documentation/mmo.core/php/printers/TextPrinter.md#textprinter)) via the [`DocumentRender`](https://mcp.mmoframework.fr/documentation/mmo.core/php/events/DocumentRender.md#documentrender) event, so a listener can override the output entirely. Subclasses ([`JsonDocument`](https://mcp.mmoframework.fr/documentation/mmo.core/php/documents/JsonDocument.md#jsondocument), [`HtmlDocument`](https://mcp.mmoframework.fr/documentation/mmo.core/php/documents/HtmlDocument.md#htmldocument), [`XmlDocument`](https://mcp.mmoframework.fr/documentation/mmo.core/php/documents/XmlDocument.md#xmldocument), [`TextDocument`](https://mcp.mmoframework.fr/documentation/mmo.core/php/documents/TextDocument.md#textdocument)) wire up the printer/`jsonSerialize()` shape appropriate to their format.

$doc = new Document(['user' => 'Marc']); $doc->addMeta(['generatedAt' => time()]); echo $doc->render();

Index

	body
	importPaths
	links
	logs
	meta	Free-form metadata about this document (e.g.
	opts
	readOnly	If true, the document's body/links/meta can no longer be modified (setters throw `eRuntime`).
	addContent($data)	Recursively merge $data into the current body (see `merge`).
	addImportPath($path, $first)	Add one base directory to the import search paths.
	addLink($link)	Append a link to this document.
	addMeta($data)	Recursively merge $data into `$meta` (existing keys are overwritten, not combined -- see `merge`'s `$combine` argument).
	addOptions($opts, $appendList)	Merge $opts into the existing options (through `merge`), rather than replacing them wholesale like `setOptions`.
	addVars($vars)	Merge extra variables into the set made available to `import()-ed` files.
	clearLogs()	Discard all recorded logs.
	clearOptions()	Empty the options bag.
	createStream()
	findImportPath($filename)	Resolve a relative filename against `getImportPaths` (first match wins).
	getBody()
	getImportPaths()
	getLinkByRel($rel)
	getLinks()	Returns an iterable of LinkInterface objects.
	getLinksByRel($rel)	Returns an iterable of LinkInterface objects that have a specific relationship.
	getLogs()
	getOption($key, $default)
	getOptions()
	getPrinter()
	getVars()	Get the variables available for import
	hasLogs($flag)
	import($_FILENAME, $_VARS, $_KEY)	Import (require) a PHP/phtml file as a sub-template, capturing its output.
	isImportValid($filename)
	isRaw()
	jsonSerialize()
	logEvent($event)	Record a log/event on this document, e.g.
	offsetExists($offset)	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)	ArrayAccess: `$document[$offset]` -- returns null for a missing entry, same as `$document[$offset] ??
	offsetSet($offset, $value)	ArrayAccess: `$document[$offset] = $value` sets a body entry (`$document[] = $value` appends).
	offsetUnset($offset)	ArrayAccess: `unset($document[$offset])` removes a body entry.
	Raw($body, $opts) static	Build a document whose `isRaw` is true from the start (see `setRaw` for what "raw" means).
	removeLink($link)	Remove a link (by identity).
	render($opts)	Export view to string
	renderValue($value, $opts)	Render an arbitrary value through this document's printer (`getPrinter`, or `TextPrinter` by default), merging $opts over the document's own options.
	setBody($body)	Replace the document's content, then dispatch `DocumentInit`.
	setImportPaths($paths)	Replace the base directories searched by `findImportPath`/`import` for a relative filename.
	setLogs($logs)
	setOption($key, $value)	Set (or, with a null $value, remove) a single option.
	setOptions($opts)	Replace the whole options bag.
	setPrinter($printer)
	setRaw($raw)	Tells a document should be left as `raw` as possible.
	setVars($vars)	Replace the variables made available to `import()-ed` files (a 'document' => $this var is always added at construction, see `__construct`).
	startCapture($key)	Start output capture.
	__construct($body, $opts)	Constructor
	__toString()

Properties7

body

protected MMO\core\interfaces\iArray|array $body

Type: iArray | array

importPaths

protected array $importPaths = []

Type: array

logs

protected MMO\core\interfaces\iArray|array $logs = []

Type: iArray | array

opts

protected array $opts = []

Type: array

readOnly

If true, the document's body/links/meta can no longer be modified (setters throw eRuntime).

bool $readOnly = false

Type: bool

Methods45

addContent($data)

Document.php:148

Recursively merge $data into the current body (see merge).

function addContent(ArrayAccess|array $data): void

$data	ArrayAccess \| array
returns	void

addImportPath($path, $first)

Document.php:351

Add one base directory to the import search paths.

function addImportPath(string $path, bool $first = false)

$path	string
$first = false	bool	if true, search $path before every existing path; otherwise (default) search it last.
returns

addLink($link)

Document.php:261

Append a link to this document.

function addLink(Psr\Link\LinkInterface|array|string $link): Psr\Link\LinkInterface

$link	`LinkInterface` \| array \| string	a LinkInterface, an href string, or an array of Link attributes (e.g. ['href' => '/next', 'rel' => 'next']) -- see `Link::__construct`.
returns	`LinkInterface`	$link itself (wrapped as a `Link` if it wasn't already one), for chaining.
throws		if the document is read-only.

$doc->addLink(['href' => '/page/2', 'rel' => 'next']);

addMeta($data)

Document.php:153

Recursively merge $data into $meta (existing keys are overwritten, not combined -- see merge's $combine argument).

function addMeta(array $data): void

$data	array
returns	void

addOptions($opts, $appendList)

tWithOptions.php:65

Merge $opts into the existing options (through merge), rather than replacing them wholesale like setOptions.

function addOptions(array $opts, bool $appendList = false): void

$opts	array	the options to merge in
$appendList = false	bool	if true, a list-valued option is appended to (rather than replaced by) the corresponding list in $opts -- see \MMO\core\arrays\merge for the exact semantics
returns	void

$t->setOptions(['a' => 1, 'tags' => ['x']]); $t->addOptions(['b' => 2, 'tags' => ['y']]); $t->getOptions(); // ['a' => 1, 'tags' => ['y'], 'b' => 2] -- 'tags' is replaced, not appended ($appendList=false)

addVars($vars)

Document.php:204

Merge extra variables into the set made available to import()-ed files.

function addVars(array $vars): void

$vars	array
returns	void

clearLogs()

Document.php:102

Discard all recorded logs.

function clearLogs(): void

returns

void

clearOptions()

tWithOptions.php:39

Empty the options bag.

function clearOptions(): void

returns

void

$t->clearOptions(); // getOptions() === []

createStream()

Document.php:186

function createStream(): MMO\core\server\Stream

returns Stream the rendered document wrapped as a text Stream (e.g. to use as an HTTP response body).

findImportPath($filename)

Document.php:362

Resolve a relative filename against getImportPaths (first match wins).

function findImportPath(string $filename): string

$filename	string
returns	string	the resolved, existing filename.
throws		if $filename doesn't exist under any import path.

getBody()

Document.php:132

function getBody(): MMO\core\interfaces\iArray|array

returns

iArray | array

the document's content.

getImportPaths()

Document.php:341

function getImportPaths(): array

returns

array

the current import search paths, in search order.

getLinkByRel($rel)

Document.php:307

function getLinkByRel(string $rel): ?Psr\Link\LinkInterface

$rel	string
returns	null \| `LinkInterface`

getLinks()

Document.php:284

Returns an iterable of LinkInterface objects.

function getLinks(): array

The iterable may be an array or any PHP \Traversable object. If no links are available, an empty array or \Traversable MUST be returned.

returns

array

getLinksByRel($rel)

Document.php:299

Returns an iterable of LinkInterface objects that have a specific relationship.

function getLinksByRel(string $rel): array

The iterable may be an array or any PHP \Traversable object. If no links with that relationship are available, an empty array or \Traversable MUST be returned.

$rel	string	The relationship name for which to retrieve links.
returns	array

getLogs()

Document.php:92

function getLogs(): MMO\core\interfaces\iArray|array

returns iArray | array the events (typically Log) recorded via logEvent.

getOption($key, $default)

tWithOptions.php:49

function getOption(string $key, mixed $default = null): mixed

$key	string
$default = null	mixed	returned if $key is not set
returns	mixed

$t->getOption('a', 'fallback'); // the current value of 'a', or 'fallback' if not set

getOptions()

tWithOptions.php:20

function getOptions(): array

returns

array

every option currently set

$t->getOptions(); // ['a' => 1, 'tags' => ['x']]

getPrinter()

Document.php:82

function getPrinter(): ?callable

returns null | callable the printer used by renderValue, or null to fall back to TextPrinter.

getVars()

Document.php:194

Get the variables available for import

function getVars(): array

returns

array

hasLogs($flag)

Document.php:110

function hasLogs(int $flag = MMO\core\interfaces\iLogLevel::ERROR_PLUS): bool

$flag = MMO\core\interfaces\iLogLevel::ERROR_PLUS	int	a `iLogLevel` bitmask (defaults to any error-or-worse level)
returns	bool	true if any recorded log's level matches $flag.

import($_FILENAME, $_VARS, $_KEY)

Document.php:396

Import (require) a PHP/phtml file as a sub-template, capturing its output.

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

Variables are NOT extracted: the imported file reads them from the `$_VARS` array (`$_VARS['name']`, never a bare `$name`), which holds $_VARS plus this document's own [`getVars`](https://mcp.mmoframework.fr/documentation/mmo.core/php/documents/Document.md#document-getvars) for any key $_VARS lacks. It also sees `$this` (this document), `$_KEY` and `$__output` (the capture). The filename is looked up literally -- no extension is added: pass `'welcome.phtml'`, not `'welcome'`. If the imported file throws, the exception is logged (`log`) and rendered in its place instead of propagating -- a broken sub-template shouldn't take down the whole document.

$_FILENAME	string	a PHP file, absolute or resolved via `findImportPath`.
$_VARS = []	ArrayAccess \| array	variables to make available to the file (take precedence over `getVars`).
$_KEY = null	string \| false \| null	where to add the captured output: null appends to the body, a string path adds it under that key (`push`), false doesn't add it to the body at all.
returns	OutputCapture	the (already-closed) capture -- `OutputCapture::getText()` for its content.

$doc->import('partials/header.phtml', ['title' => 'Home']);

isImportValid($filename)

Document.php:373

function isImportValid(string $filename): bool

$filename	string
returns	bool	whether $filename can currently be resolved by `findImportPath`.

isRaw()

Document.php:222

function isRaw(): bool

returns bool whether setRaw was set (defaults to false).

jsonSerialize()

Document.php:72

function jsonSerialize(): array

returns array the document's full structured content ('meta'/'links'/'data'/'logs'), for json_encode().

logEvent($event)

Document.php:124

Record a log/event on this document, e.g. so it's included in the rendered output (a JSON document typically surfaces these under its 'logs' key -- see jsonSerialize).

function logEvent(object $event): bool

$event	object	typically a `Log`; if it's an `iStoppableEvent`, propagation is stopped so no other listener also handles it (this document is now the one "owning" it).
returns	bool	false (a no-op) if the document is read-only or `isRaw`.

offsetExists($offset)

Document.php:242

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).

function offsetExists(mixed $offset): bool

$offset	mixed
returns	bool

offsetGet($offset)

Document.php:247

ArrayAccess: $document[$offset] -- returns null for a missing entry, same as $document[$offset] ?? null.

function offsetGet(mixed $offset): mixed

$offset	mixed
returns	mixed

offsetSet($offset, $value)

Document.php:235

ArrayAccess: $document[$offset] = $value sets a body entry ($document[] = $value appends). @throws eRuntime if read-only.

function offsetSet(mixed $offset, mixed $value): void

$offset	mixed
$value	mixed
returns	void

offsetUnset($offset)

Document.php:229

ArrayAccess: unset($document[$offset]) removes a body entry. @throws eRuntime if read-only.

function offsetUnset(mixed $offset): void

$offset	mixed
returns	void

Raw($body, $opts)

staticDocument.php:65

Build a document whose isRaw is true from the start (see setRaw for what "raw" means).

static function Raw( MMO\core\interfaces\iArray|array|null $body = null, MMO\core\interfaces\iOptions|array $opts = [] ): self

$body = null	iArray \| array \| null
$opts = []	iOptions \| array
returns	self

removeLink($link)

Document.php:319

Remove a link (by identity).

function removeLink(Psr\Link\LinkInterface $link): bool

$link	`LinkInterface`
returns	bool	false if $link isn't currently one of this document's links.

render($opts)

Document.php:175

Export view to string

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

$opts = []	array	- {bool} raw : if true, won't normalize the view's data before rendering
returns	string

renderValue($value, $opts)

Document.php:165

Render an arbitrary value through this document's printer (getPrinter, or TextPrinter by default), merging $opts over the document's own options.

function renderValue(mixed $value, MMO\core\interfaces\iOptions|array $opts = []): string

$value	mixed
$opts = []	iOptions \| array
returns	string

echo $this->renderValue($_VARS['name'], new PrintOptions(escape: true)); // in a template: the name, HTML-escaped

setBody($body)

Document.php:141

Replace the document's content, then dispatch DocumentInit.

function setBody(MMO\core\interfaces\iArray|array $body): void

$body	iArray \| array
returns	void
throws		if the document is read-only.

setImportPaths($paths)

Document.php:332

Replace the base directories searched by findImportPath/import for a relative filename.

function setImportPaths(array|string $paths): bool

$paths	array \| string	one path, or an ordered list of paths (searched first to last).
returns	bool	false (a no-op) if $paths is identical to the current list.

setLogs($logs)

Document.php:97

function setLogs(MMO\core\interfaces\iArray|array &$logs): void

$logs	iArray \| array	replaces the log list by reference (so external code can keep appending to it).
returns	void

setOption($key, $value)

tWithOptions.php:77

Set (or, with a null $value, remove) a single option.

function setOption(string $key, mixed $value): void

$key	string
$value	mixed	if null, the option is unset entirely rather than being set to null
returns	void

$t->setOption('a', 1);

$t->setOption('a', null); // removes 'a' from getOptions()

setOptions($opts)

tWithOptions.php:30

Replace the whole options bag.

function setOptions(array $opts): void

$opts	array
returns	void

$t->setOptions(['a' => 1]);

setPrinter($printer)

Document.php:87

function setPrinter(?callable $printer): void

$printer	null \| callable	a callable(mixed $value, array $opts): string, or null to use `TextPrinter`.
returns	void

setRaw($raw)

Document.php:217

Tells a document should be left as raw as possible.

function setRaw(bool $raw = true)

ex: - html: don't add js or css (used for email) - json: don't add internal structure around the data

$raw = true	bool
returns

setVars($vars)

Document.php:199

Replace the variables made available to import()-ed files (a 'document' => $this var is always added at construction, see __construct).

function setVars(array $vars): void

$vars	array
returns	void

startCapture($key)

Document.php:424

Start output capture. Start output buffering (capture echo)

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

$key = null	string \| false \| null	the content's key to add output to. if null, add to the content. if false, don't add it to the content (just return)
returns	OutputCapture

__construct($body, $opts)

Document.php:53

Constructor

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

$body = null	iArray \| array \| null
$opts = []	iOptions \| array

__toString()

Document.php:181

function __toString(): string

returns string same as calling render() with no options.