ExampleRunner

MMO\doc · 1 symbol · generated 30 Sep 2026

class

ExampleRunner

Runs an @example PHP snippet in an isolated, sandboxed subprocess.

class MMO\doc\ExampleRunner extends MMO\core\classes\aModule

Namespace: MMO\doc
Extends: aModule

Defense in depth, layered from the outside in: 1. The snippet is never client-supplied -- [`ExampleController`](https://mmoframework.fr/documentation/mmo.doc/php/controllers/ExampleController.md#examplecontroller) resolves it itself from the doc comment of a symbol it re-resolves via reflection; the client only ever sends a symbol name and an example index. 2. OS-level sandbox via `bwrap` (bubblewrap): a fresh mount namespace with only the package source trees and the system's PHP runtime bound read-only, a fresh network namespace (no network at all), a fresh PID namespace, and the only writable location is a throwaway scratch folder deleted right after the run. 3. A long `disable_functions` deny-list (shell/process spawning, `dl`, `putenv`, mail) passed to the PHP CLI invocation itself, on top of the OS-level boundary above (no `open_basedir` on top of it too -- that was tried and reverted: it's redundant with bwrap's mount namespace, and unlike bwrap it fails as a PHP warning rather than a silent false, which the framework's own error-to-exception handling made worse, not better). 4. Resource limits: a short wall-clock timeout enforced *both* by `Process`'s own timeout (which kills the process) and by `max_execution_time`, plus a `memory_limit`. This is deliberately not a perfect jail -- a kernel or `bwrap` vulnerability is out of scope -- but it is a real, meaningfully-layered boundary rather than "just run it". NOTE: the sandboxed process still needs the framework's own classes/functions loaded (an example legitimately calls into MMOFramework code), which means giving it something to `require`. Reconstructing an app's full boot state generically isn't safe to guess at, so this is explicit: set `bootstrap` to the absolute path of a small, side-effect-free PHP file that loads the framework the way `libs/doc/test.php` does (define the `MMO_*` constants, require core's bootstrap, call `\MMO\app([...])` -- NOT `\MMO\run()`, which starts full HTTP handling). Execution is refused with a clear error until this is configured.

Index

	bootstrap
	disabledFunctions
	maxOutputBytes
	memoryLimit
	timeout
	autoReturnLastExpression($code)	Many `@example` docblocks follow a "call(); // expected result" convention (a bare expression statement, the result only shown as a trailing comment) -- runnable, but silent: no `echo`, nothing to …
	buildCommand($script, $scratch, $roots)	Builds the full `bwrap ...
	buildHarness($code, $namespace)	The snippet, wrapped in a function (so a trailing `return ...;` is captured and reported), after requiring
	DefaultConfig() static
	getPackageRoots()
	run($code, $namespace)

Properties5

bootstrap

?string $bootstrap = null

Type: null | string

disabledFunctions

array $disabledFunctions = […20 items]

Type: array

maxOutputBytes

int $maxOutputBytes = 65536

Type: int

memoryLimit

string $memoryLimit = '32M'

Type: string

timeout

float $timeout = 5.0

Type: float

Methods6

autoReturnLastExpression($code)

ExampleRunner.php:106

Many @example docblocks follow a "call(); // expected result" convention (a bare expression statement, the result only shown as a trailing comment) -- runnable, but silent: no echo, nothing to show in the output panel. If the LAST non-blank line is a bare name(...); call (optionally followed by a // comment) and isn't already a return/echo/control-flow/declaration, prefix it with return so

protected function autoReturnLastExpression(string $code): string

See: buildHarness's wrapper function reports its value -- otherwise the code is returned unchanged.

$code	string
returns	string

buildCommand($script, $scratch, $roots)

ExampleRunner.php:183

Builds the full bwrap ... php ... snippet.php shell command line, every token individually escaped.

protected function buildCommand(string $script, string $scratch, array $roots): string

$script	string
$scratch	string
$roots	array
returns	string

buildHarness($code, $namespace)

ExampleRunner.php:147

The snippet, wrapped in a function (so a trailing return ...; is captured and reported), after requiring

protected function buildHarness(string $code, string $namespace = ''): string

Uses the braced multi-namespace syntax so the bootstrap/setup code stays in the global namespace while the snippet itself runs inside $namespace -- letting a doc example call sibling functions/classes unqualified, exactly as if it were pasted right after the documented symbol's own declaration.

See: $bootstrap. NOTE: this deliberately does NOT also blindly require every *other* discovered package's own bootstrap.php on top of it (an earlier version of this method did) -- that bypasses PackageManager's own dependency-ordered inc() and can require a package before one of *its* dependencies is loaded (e.g. a controller class using a trait from a package it doesn't declare a dependency on), which is exactly, $bootstrap's job to get right via a real PackageManager::Shared()->inc(...) call.

$code	string
$namespace = ''	string
returns	string

DefaultConfig()

staticExampleRunner.php:54

static function DefaultConfig(): array

returns

array

getPackageRoots()

ExampleRunner.php:126

protected function getPackageRoots(): array

returns

array

the absolute root folder of every loaded package (bound read-only into the sandbox)

run($code, $namespace)

ExampleRunner.php:67

function run(string $code, string $namespace = ''): array

$code	string	the PHP statements to run (no `<?php` tag)
$namespace = ''	string	the namespace to run $code in, so bare/unqualified references (a function or sibling class used without its full path, as doc examples conventionally assume "you're already in this namespace") resolve the same way they would if $code were pasted right after the documented symbol's own declaration.
returns	array	{output: string, error: string, timedOut: bool, exitCode: ?int, duration: float}
throws		if `$bootstrap` isn't set

Inherited members (47)

Constants	Declared by	Description
`ALERT`	iLogLevel	Alert: Action must be taken immediately.
`ALL`	iLogLevel	Mask for all
`ALL_PLUS`	iLogLevel	debug everything
`BACKTRACE`	iLogLevel
`CRITICAL`	iLogLevel	Critical: Critical conditions.
`DEBUG`	iLogLevel	Debug: Detailed debug information.
`DEEP`	iLogLevel	debug everything with arguments
`EMERGENCY`	iLogLevel	Emergency: System is unusable.
`ERROR`	iLogLevel	Error: Runtime errors that do not require immediate action but should typically be logged and monitored.
`ERROR_PLUS`	iLogLevel	Mask for all error
`FATAL`	iLogLevel	Mask for all fatal error
`INFO`	iLogLevel	Info: Interesting events.
`INFO_PLUS`	iLogLevel	Mask for all errors/warning/notices/info
`MEMORY`	iLogLevel	include backtrace object
`NOTICE`	iLogLevel	Notice: Normal but significant events.
`NOTICE_PLUS`	iLogLevel	Mask for all errors/warning/notices/info
`TRACE`	iLogLevel	include backtrace as origins
`WARNING`	iLogLevel	Warning: Exceptional occurrences that are not errors.
`WARNING_PLUS`	iLogLevel	Mask for all errors and warnings

	Properties	Declared by	Description
	`verbosity`	aModule

Methods	Declared by	Description
`alert($message, $context)`	aModule	Action must be taken immediately.
`backtraces($message, $context)`	aModule	Force-log a message at INFO level together with a full stack trace/memory snapshot (`iLogLevel::BACKTRACE`), bypassing the verbosity mask entirely (any non-zero verbosity is enough to trigger it).
`Configure($config)`	aModule	Merge $config into this module's configuration in the shared `Configuration`.
`critical($message, $context)`	aModule	Critical conditions. No-op if CRITICAL is currently filtered out by the verbosity mask.
`debug($message, $context)`	aModule	Detailed debug information.
`debugName()`	aModule	Human-readable identifier used as the default `{origin}` in this instance's log messages.
`emergency($message, $context)`	aModule	System is unusable. No-op if EMERGENCY is currently filtered out by the verbosity mask.
`error($message, $context)`	aModule	Runtime errors that do not require immediate action but should typically be logged and monitored.
`getVerbosity()`	aModule
`info($message, $context)`	aModule	Interesting events. No-op if INFO is currently filtered out by the verbosity mask.
`Instantiate($config)`	aModule	(Re)create the shared instance immediately, configured with $config merged into the class's existing config.
`IsShared()`	aModule
`log($level, $message, $context)`	aModule	Logs with an arbitrary level.
`notice($message, $context)`	aModule	Normal but significant events.
`offsetExists($key)`	aModule	\ArrayAccess::offsetExists -- tells whether $key is a declared property at all, regardless of whether it is currently readable/writable through array access.
`offsetGet($key)`	aModule	\ArrayAccess::offsetGet -- reads a property directly, unless it has a `#[Serialize(serialize: 'methodName')]` attribute, in which case that zero-argument method is called instead (e.g.
`offsetSet($key, $value)`	aModule	\ArrayAccess::offsetSet -- sets a property directly, unless it has a `#[Serialize(unserialize: 'methodName')]` attribute, in which case that method is called with $value instead (e.g.
`offsetUnset($key)`	aModule	\ArrayAccess::offsetUnset -- equivalent to `$module[$key] = null`.
`serialize($path, $serializer)`	aModule	\MMO\core\interfaces\iSerializable::serialize -- exports every property (via
`setVerbosity($verb)`	aModule	Set the current verbosity mask, replacing whatever it was before.
`Shared()`	aModule	Get the shared instance, creating (and configuring) it on first call.
`testVerbosity($level)`	aModule	Test whether a given level (or set of levels) is currently enabled by this instance's verbosity mask.
`traitUnshare($serialize)`	aModule	Remove the shared instance, so the next `Shared()` call creates a fresh one.
`unserialize($data, $path, $instances)`	aModule	\MMO\core\interfaces\iSerializable::unserialize -- merges $data onto `DefaultConfig`, runs it through the (possibly overridden) constructor, then applies each resulting value to its property (via
`Unshare($serialize)`	aModule	Like `tSingleton::Unshare`, but also disconnects this module's instance from every event it was listening to (via `Event::DisconnectListeners`) before dropping it.
`warning($message, $context)`	aModule	Exceptional occurrences that are not errors.
`__construct($config)`	aModule	protected constructor, so it is not possible to do `new Module(...)` called by the serialization process just before being injected with data.