tException

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

trait

tException

Trait giving an exception class placeholder-based, i18n-aware messages: the constructor takes a {xxx}-style $format and a $context array (like the framework's logging functions), renders them into the final message, and also makes the exception class itself an tEvent event bus: \MMO\core\Application's top-level error handler calls $e->dispatch() on every uncaught iException, so listeners registered on a specific exception class (e.g. eNotFound::AddListener(...)) can react whenever that exception type goes uncaught.

trait MMO\core\classes\tException use MMO\core\classes\tEvent

Namespace: MMO\core\classes
Uses traits: tEvent

throw new eInvalid($this, 'invalid value [{value}] for [{field}].', ['value' => $v, 'field' => 'age']); // getMessage() === 'invalid value [...] for [age].', with {origin} available too (see getOrigin())

Index

	context
	format
	Listeners static
	AddListener($handler, $order) static	Register a listener directly (as opposed to `ConnectListeners`'s attribute-based discovery).
	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.
	getContext()
	getFormat()
	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 …
	getOrigin()
	HasListener($handler) static
	jsonSerialize()	\JsonSerializable::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).
	__construct($origin, $format, $context, $previous, $code)

Properties3

context

protected array $context

Type: array

format

protected string $format

Type: string

Listeners

static

protected static array $Listeners = []

Type: array

Methods14

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

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

getContext()

tException.php:48

function getContext()

See: getFormat into Exception::getMessage

returns

the raw placeholder values passed to the constructor (plus 'origin'), as used to render

$e->getContext(); // ['value' => 5, 'field' => 'age', 'origin' => $someObject]

getFormat()

tException.php:56

function getFormat()

returns the original, untranslated {xxx}-placeholder message format passed to the constructor

$e->getFormat(); // 'invalid value [{value}] for [{field}].'

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

getOrigin()

tException.php:65

function getOrigin(): object|string

returns

object | string

whatever was passed as $origin to the constructor (typically the object -- or its class name -- that threw the exception)

$e->getOrigin(); // e.g. the object instance that constructed and threw this exception

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]

jsonSerialize()

tException.php:74

\JsonSerializable::jsonSerialize

function jsonSerialize(): mixed

returns

mixed

string, trace: array}

json_encode($e); // '{"message":"...","trace":[...]}'

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

__construct($origin, $format, $context, $previous, $code)

tException.php:31

function __construct( $origin, string $format, array $context = [], ?Throwable $previous = null, int $code = 0 )

$origin		the exception origin (object throwing)
$format	string	the message's format. Can contain placeholders {xxx} replaced by values in context. {origin} is replaced by origin.
$context = []	array	the message context.
$previous = null	null \| Throwable
$code = 0	int

new eInvalid($this, 'invalid value [{value}].', ['value' => $v]); // getMessage() === 'invalid value [...].'