Log

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

class

Log

A single log entry -- carries a level (one of the iLogLevel flags), a printf-style message + context, where it originated (file/line, and an optional call stack), and renders itself either as a plain apache-log-style line (__toString) or as a JSON-serializable structure (jsonSerialize).

class MMO\core\events\Log implements MMO\core\interfaces\iEvent, MMO\core\interfaces\iStoppableEvent, MMO\core\interfaces\iLogLevel, JsonSerializable, Stringable use MMO\core\classes\tEvent, MMO\core\classes\tStoppableEvent

Namespace: MMO\core\events
Implements: iEvent, iStoppableEvent, iLogLevel, JsonSerializable, Stringable
Uses traits: tEvent, tStoppableEvent

Dispatched (via `\MMO\log()`/`Log::Send()`) so listeners (e.g. a file logger, a console printer) can react to it -- being an [`iStoppableEvent`](https://mmoframework.fr/documentation/mmo.core/php/interfaces/iStoppableEvent.md#istoppableevent), an early listener can stop propagation to prevent later ones from also handling it.

Log::AddListener(fn(Log $log) => file_put_contents('app.log', (string)$log, FILE_APPEND)); new Log(iLogLevel::ERROR, 'user {id} not found', ['id' => 42]); // ->Send() is normally called for you, e.g. by \MMO\log()

Index

	code readonly
	context readonly
	file readonly
	line readonly
	Listeners static
	message readonly
	num readonly	a unique, per-request, incrementing number (starts from 1), useful to tell same-timestamp entries apart.
	stopped
	time readonly	unix timestamp (seconds) this entry was created at.
	time_ms readonly	the sub-second part of `$time`, in microseconds (0-999999) -- despite the name, NOT milliseconds.
	traces
	AddListener($handler, $order) static	Register a listener directly (as opposed to `ConnectListeners`'s attribute-based discovery).
	clearTraces()	Discard `$traces` (e.g.
	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.
	FromException($exception, $context, $level) static	Build a Log entry from a caught exception, using the exception's own message and stack trace.
	getLevel()
	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 …
	getMessage($withOrigin)
	getOrigin()
	getTraceAsString($separator)
	HasListener($handler) static
	isPropagationStopped()
	jsonSerialize()
	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).
	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($code, $message, $context)
	__toString()

Properties11

code

readonly

readonly int $code

Type: int

context

readonly

readonly array $context

Type: array

file

readonly

readonly string $file

Type: string

line

readonly

readonly int $line

Type: int

Listeners

static

protected static array $Listeners = []

Type: array

message

readonly

readonly array|string $message

Type: array | string

num

readonly

a unique, per-request, incrementing number (starts from 1), useful to tell same-timestamp entries apart.

readonly int $num

Type: int

stopped

protected $stopped = false

time

readonly

unix timestamp (seconds) this entry was created at.

readonly int $time

Type: int

time_ms

readonly

the sub-second part of $time, in microseconds (0-999999) -- despite the name, NOT milliseconds.

readonly int $time_ms

Type: int

traces

array $traces

Type: array

Methods21

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

clearTraces()

Log.php:182

Discard $traces (e.g. to shrink a Log entry before storing/transmitting it).

function clearTraces(): void

returns

void

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

FromException($exception, $context, $level)

staticLog.php:121

Build a Log entry from a caught exception, using the exception's own message and stack trace.

static function FromException(Throwable $exception, $context = [], $level = self::CRITICAL): self

$exception	Throwable
$context = []		extra context (e.g. ['origin' => $this]) -- 'exception' is set for you.
$level = self::CRITICAL		the `iLogLevel` level to log at (TRACE is always added, to capture $exception's trace)
returns	self

Log::FromException($e, ['origin' => $this])->Send();

getLevel()

Log.php:192

function getLevel(): string

returns string the PSR-3 level name for $code (e.g. 'error', 'critical').

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

getMessage($withOrigin)

Log.php:157

function getMessage(bool $withOrigin = true): string

$withOrigin = true	bool	if true (default) and an 'origin' was given in the context, prefix the message with it.
returns	string	the message, resolved against `$context` (printf-style, via `printfd`)

$log->getMessage(); // "MyOrigin: user 42 not found"

getOrigin()

Log.php:187

function getOrigin(): object|string

returns

object | string

the 'origin' given in the context, or the literal string 'UNKNOWN' if none was given.

getTraceAsString($separator)

Log.php:165

function getTraceAsString(string $separator = MMO\core\events\PHP_EOL): string

$separator = MMO\core\events\PHP_EOL	string
returns	string	`$traces` rendered as "file:line name(args)" lines (oldest call first), joined by $separator.

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

jsonSerialize()

Log.php:127

function jsonSerialize(): mixed

returns

mixed

the data used when this Log is JSON-encoded (level, num, time, file, line, message, traces).

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

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($code, $message, $context)

Log.php:55

function __construct($code, string $message, array $context = [])

$code		a bitmask combining one `iLogLevel` level constant with any of its flags (e.g. TRACE)
$message	string	a printf-style message (see `printfd`), resolved against $context
$context = []	array	printf arguments, plus optional special keys: 'origin' (the object/string this log is about, used by `getMessage`/`getOrigin`), 'exception' (a \Throwable to build `$traces` from when TRACE is set), '$file'/'$line' (explicit origin location, overriding the auto-detected one)

__toString()

Log.php:140

function __toString(): string

returns

string

this entry rendered as a single apache-log-style line (with a trailing newline).

Inherited members (19)

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