DocumentRender

MMO\core\events · 1 symbol · generated 30 Sep 2026

class

DocumentRender

Dispatched by Document::render(), letting a listener supply the rendered output itself (via setReturn) instead of the document's default printer -- e.g. to inject caching, post-processing, or an alternate format.

class MMO\core\events\DocumentRender implements MMO\core\interfaces\iStoppableEvent, MMO\core\interfaces\iSignal use MMO\core\classes\tEvent, MMO\core\classes\tStoppableEvent, MMO\core\classes\tWithOptions

Namespace: MMO\core\events
Implements: iStoppableEvent, iSignal
Uses traits: tEvent, tStoppableEvent, tWithOptions

If no listener overrides it, [`getReturn`](https://mmoframework.fr/documentation/mmo.core/php/events/DocumentRender.md#documentrender-getreturn) lazily falls back to the document's own printer.

DocumentRender::AddListener(function (DocumentRender $e) { if ($e->document->getOption('cached')) { $e->setReturn('<cached output>', true); // supply output and stop further listeners } }); echo $document->render();

Index

	document	The document being rendered.
	Listeners static
	opts
	return
	stopped
	AddListener($handler, $order) static	Register a listener directly (as opposed to `ConnectListeners`'s attribute-based discovery).
	addOptions($opts, $appendList)	Merge $opts into the existing options (through `merge`), rather than replacing them wholesale like `setOptions`.
	clearOptions()	Empty the options bag.
	ConnectListeners($obj) static	Scan $obj's methods for #[Listen(EventClass::class)] attributes and register each one as a listener on the matching event class.
	DisconnectListeners($obj) static	Undo a previous `ConnectListeners`: removes every listener that `connect` had registered for $obj on this event class.
	dispatch()	Invoke every `GetListeners` listener with $this.
	getBody()
	GetListeners() static	Collect every listener for this class, including those registered on its parent classes (so a subclass event is also caught by listeners of its parent event), sorted by ascending $order (ties keep …
	getOption($key, $default)
	getOptions()
	getOrigin()
	getReturn()
	HasListener($handler) static
	isPropagationStopped()
	RemoveListener($handler) static	Remove the last added handler from the listeners.
	Send($args) static	Construct a new instance of this class with $args, then `dispatch` it to every listener.
	SetListenerOrder($handler, $order) static	Change the order of an already-registered listener, whether added directly via `AddListener` or indirectly via `ConnectListeners` (which also stores its `[$obj, $methodName]` callables here).
	setOption($key, $value)	Set (or, with a null $value, remove) a single option.
	setOptions($opts)	Replace the whole options bag.
	setReturn($output, $stop)	Override the rendered output, e.g.
	stopPropagation()	Prevent any remaining listener in the current dispatch chain from being called.
	__clone()	A cloned event starts fresh: propagation is never considered stopped on the clone, even if it was on the original instance.
	__construct($document, $opts)

Properties5

document

The document being rendered.

MMO\core\documents\Document $document

Type: Document

Listeners

static

protected static array $Listeners = []

Type: array

opts

protected array $opts = []

Type: array

return

protected ?string $return = null

Type: null | string

stopped

protected $stopped = false

Methods23

AddListener($handler, $order)

statictEvent.php:62

static function AddListener(callable $handler, int $order = 0): void

$handler	callable	called as $handler($eventInstance) when this event class is `Send` / `dispatch-ed`
$order = 0	int	listeners run in ascending order (lower first); listeners with an equal order run in the order they were added
returns	void

UserCreated::AddListener(function (UserCreated $e) {...}, 10);

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)

clearOptions()

tWithOptions.php:39

Empty the options bag.

function clearOptions(): void

returns

void

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

ConnectListeners($obj)

statictEvent.php:37

Scan $obj's methods for #[Listen(EventClass::class)] attributes and register each one as a listener on the matching event class. connect does the actual reflection/registration.

static function ConnectListeners(object|string $obj): void

$obj	object \| string	an instance (or class name, for static-only listener methods)
returns	void
throws

class UserService { #[Listen(UserCreated::class, order: 1)] public function onUserCreated(UserCreated $e): void {...} } UserCreated::ConnectListeners(new UserService()); // onUserCreated() is now called on every UserCreated::Send()

DisconnectListeners($obj)

statictEvent.php:49

Undo a previous ConnectListeners: removes every listener that connect had registered for $obj on this event class.

static function DisconnectListeners(object|string $obj): void

$obj	object \| string
returns	void
throws

UserCreated::DisconnectListeners($service); // $service's #[Listen] methods stop firing

dispatch()

tEvent.php:153

Invoke every GetListeners listener with $this. If the class also implements PSR-14's StoppableEventInterface, dispatch stops early as soon as isPropagationStopped() becomes true.

function dispatch(): static

returns

static

$this, for chaining

(new UserCreated('Marc'))->dispatch(); // what Send() does internally

getBody()

DocumentRender.php:45

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

returns

iArray | array

the document's current body

GetListeners()

statictEvent.php:123

Collect every listener for this class, including those registered on its parent classes (so a subclass event is also caught by listeners of its parent event), sorted by ascending $order (ties keep insertion order).

static function GetListeners(): array

returns

array

[[callable $handler, int $order], ...]

UserCreated::GetListeners(); // [[$handlerB, 5], [$handlerA, 10]] -- lower order first

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']]

getOrigin()

DocumentRender.php:40

function getOrigin(): object

returns object the document (same as $document)

getReturn()

DocumentRender.php:53

function getReturn(): string

returns string the rendered output -- either what a listener supplied via setReturn, or (lazily, the first time this is called) the document's own printer output for its current body.

HasListener($handler)

statictEvent.php:109

static function HasListener(callable|object $handler): bool

$handler	callable \| object	either the exact callable passed to `AddListener`, or (for a `[$obj, $methodName]` listener registered via `ConnectListeners`) just the object, to check whether any of its methods are currently listening
returns	bool

UserCreated::HasListener($handler); // true if $handler is currently registered

UserCreated::HasListener($service); // true if any of $service's methods were connected via #[Listen]

isPropagationStopped()

tStoppableEvent.php:21

function isPropagationStopped(): bool

returns bool true once stopPropagation has been called on this instance

RemoveListener($handler)

statictEvent.php:91

Remove the last added handler from the listeners.

static function RemoveListener(callable $handler): bool

NOTE: if you added the same handler multiple time, you need to call this function the same amount of times.

$handler	callable
returns	bool	true if a listener was removed

Send($args)

statictEvent.php:143

Construct a new instance of this class with $args, then dispatch it to every listener.

static function Send(mixed ...$args): static

...$args	mixed
returns	static	the constructed (and dispatched) event instance

UserCreated::Send('Marc'); // equivalent to (new UserCreated('Marc'))->dispatch()

SetListenerOrder($handler, $order)

statictEvent.php:75

Change the order of an already-registered listener, whether added directly via AddListener or indirectly via ConnectListeners (which also stores its [$obj, $methodName] callables here).

static function SetListenerOrder(callable $handler, int $order): bool

$handler	callable
$order	int
returns	bool	true if $handler was found and its order changed

UserCreated::SetListenerOrder($handler, 20); // moves $handler later in the dispatch order

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]);

setReturn($output, $stop)

DocumentRender.php:66

Override the rendered output, e.g. from a listener.

function setReturn(?string $output, bool $stop = false): void

$output	null \| string	the new rendered output (a later, un-stopped listener may still override it again)
$stop = false	bool	if true, also stop propagation so no later listener can override this again
returns	void

stopPropagation()

tStoppableEvent.php:29

Prevent any remaining listener in the current dispatch chain from being called.

function stopPropagation()

returns

__clone()

tStoppableEvent.php:38

A cloned event starts fresh: propagation is never considered stopped on the clone, even if it was on the original instance.

function __clone()

returns

__construct($document, $opts)

DocumentRender.php:34

function __construct(MMO\core\documents\Document $document, array $opts = [])

$document	Document
$opts = []	array	render options, forwarded to the document's printer (see `Document::render`)