aMessage

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

class

aMessage

Base implementation of PSR-7's MessageInterface (Request / Response extend this): immutable-by-convention headers, built on tWithHeaders. The trait's own setters (setHeader/addHeader/unsetHeader/setContentType/setCacheControl/setExpires) are narrowed to protected here -- outside code MUST go through the with*() methods below, each of which clones the message first, so a message instance never mutates after it is handed out (the PSR-7 contract).

abstract class MMO\core\classes\aMessage implements MMO\core\interfaces\iEvent, Psr\Http\Message\MessageInterface use MMO\core\classes\tEvent, MMO\core\classes\tWithHeaders

Namespace: MMO\core\classes
Implements: iEvent, MessageInterface
Uses traits: tEvent, tWithHeaders

$msg = new Response(); $msg2 = $msg->withHeader('Content-Type', 'text/html'); // $msg2 !== $msg; $msg itself is untouched

Index

	headers
	ikeys
	Listeners static
	protocol
	addHeader($name, $value)	Append a value to a header, keeping any value(s) already set (as opposed to `setHeader`, which replaces).
	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.
	getCharset()
	getContentExtension()
	getContentType($single)
	getHeader($name)	Retrieves a message header value by the given case-insensitive name.
	getHeaderLine($name)	Retrieves a comma-separated string of the values for a single header.
	getHeaders()	Retrieves all message header values.
	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()	Get origin of the request by looking at 'Origin', then 'Referer', then 'Sender' in the request's headers.
	getParsedBody() abstract
	getProtocolVersion()	Retrieves the HTTP protocol version as a string.
	getUserAgent()
	hasHeader($name)	Checks if a header exists by the given case-insensitive name.
	HasListener($handler) static
	isHTML()
	isIe()
	isIphone()
	isJSON()
	isMac()
	isMobile()
	isWindows()
	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.
	setCacheControl($cache, $pragma)	Set the Cache-Control header (and, optionally, the legacy Pragma header alongside it).
	setContentType($type, $charset)	Set the Content-Type header, appending a charset parameter (unless $charset is null/empty).
	setExpires($time)	Set the Expires header from a unix timestamp, formatted as an RFC 7231 HTTP-date.
	setHeader($name, $value)	Set header, replacing any previous value(s) for the same (case-insensitively matched) header name.
	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).
	unsetHeader($name)	Remove a header entirely.
	withAddedHeader($name, $value)	Return an instance with the specified header appended with the given value.
	withCacheControl($cache, $pragma)	Set cache control of a clone.
	withContentType($type, $charset)	Set content type of a clone.
	withExpires($time)	Set cache expire date of a clone.
	withHeader($name, $value)	Return an instance with the provided value replacing the specified header.
	withHeaders($headers, $reset)	Return a clone with every header in $headers set (through `tWithHeaders::setHeader`, so each value replaces any existing one for the same header name).
	withoutHeader($name)	Return an instance without the specified header.
	withParsedBody($data) abstract
	withProtocolVersion($version)	Return an instance with the specified HTTP protocol version.
	__construct($headers)

Properties4

headers

protected $headers = []

ikeys

protected $ikeys = []

Listeners

static

protected static array $Listeners = []

Type: array

protocol

protected string $protocol = '1.0'

Type: string

Methods43

addHeader($name, $value)

tWithHeaders.php:166

Append a value to a header, keeping any value(s) already set (as opposed to setHeader, which replaces).

protected function addHeader(string $name, array|string $value): self

$name	string
$value	array \| string	a plain string is appended as a single new value (NOT split on ',', unlike setHeader)
returns	self

$msg->addHeader('X-Tags', 'a'); $msg->addHeader('X-Tags', 'b'); $msg->getHeader('X-Tags'); // ['a', 'b']

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

getCharset()

tWithHeaders.php:55

function getCharset(): ?string

returns

null | string

the charset parameter of the Content-Type header, or null if not present

$msg->setContentType('text/html'); $msg->getCharset(); // 'utf-8' (the default charset)

getContentExtension()

tWithHeaders.php:63

function getContentExtension(): ?string

returns

null | string

the file extension conventionally associated with the Content-Type header (e.g. 'html', 'json')

$msg->setContentType('text/html'); $msg->getContentExtension(); // 'html'

getContentType($single)

tWithHeaders.php:47

function getContentType(bool $single = true): array|string

$single = true	bool	if true, return only the media type (e.g. 'text/html'); if false, every parameter too
returns	array \| string

$msg->setContentType('text/html'); $msg->getContentType(); // 'text/html'

getHeader($name)

tWithHeaders.php:254

Retrieves a message header value by the given case-insensitive name.

function getHeader(string $name): array

This method returns an array of all the header values of the given case-insensitive header name. If the header does not appear in the message, this method MUST return an empty array.

$name	string	Case-insensitive header field name.
returns	array	An array of string values as provided for the given header. If the header does not appear in the message, this method MUST return an empty array.

$msg->addHeader('Accept', 'text/html'); $msg->addHeader('Accept', 'application/json'); $msg->getHeader('Accept'); // ['text/html', 'application/json']

getHeaderLine($name)

tWithHeaders.php:281

Retrieves a comma-separated string of the values for a single header.

function getHeaderLine(string $name): string

This method returns all of the header values of the given case-insensitive header name as a string concatenated together using a comma. NOTE: Not all header values may be appropriately represented using comma concatenation. For such headers, use getHeader() instead and supply your own delimiter when concatenating. If the header does not appear in the message, this method MUST return an empty string.

$name	string	Case-insensitive header field name.
returns	string	A string of values as provided for the given header concatenated together using a comma. If the header does not appear in the message, this method MUST return an empty string.

$msg->addHeader('Accept', 'text/html'); $msg->addHeader('Accept', 'application/json'); $msg->getHeaderLine('Accept'); // 'text/html, application/json'

getHeaders()

tWithHeaders.php:218

Retrieves all message header values.

function getHeaders(): array

The keys represent the header name as it will be sent over the wire, and each value is an array of strings associated with the header. // Represent the headers as a string foreach ($message->getHeaders() as $name => $values) { echo $name . ": " . implode(", ", $values); } // Emit headers iteratively: foreach ($message->getHeaders() as $name => $values) { foreach ($values as $value) { header(sprintf('%s: %s', $name, $value), false); } } While header names are not case-sensitive, getHeaders() will preserve the exact case in which headers were originally specified.

returns

array

Returns an associative array of the message's headers. Each key MUST be a header name, and each value MUST be an array of strings for that header.

$msg->getHeaders(); // ['Content-Type' => ['text/html;charset=utf-8']]

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

tWithHeaders.php:35

Get origin of the request by looking at 'Origin', then 'Referer', then 'Sender' in the request's headers.

function getOrigin(): string

returns

string

'' if none of those headers are set

$msg->setHeader('Origin', 'https://example.com'); $msg->getOrigin(); // 'https://example.com'

getParsedBody()

abstractaMessage.php:44

abstract function getParsedBody(): ArrayAccess|array|null

returns

ArrayAccess | array | null

the parsed request/response body (e.g. decoded JSON or form data)

getProtocolVersion()

aMessage.php:111

Retrieves the HTTP protocol version as a string.

function getProtocolVersion(): string

The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").

returns

string

HTTP protocol version.

$msg->getProtocolVersion(); // '1.0'

getUserAgent()

tWithHeaders.php:70

function getUserAgent(): ?string

returns

null | string

the User-Agent header

hasHeader($name)

tWithHeaders.php:231

Checks if a header exists by the given case-insensitive name.

function hasHeader(string $name): bool

$name	string	Case-insensitive header field name.
returns	bool	Returns true if any header names match the given header name using a case-insensitive string comparison. Returns false if no matching header name is found in the message.

$msg->setHeader('Content-Type', 'text/html'); $msg->hasHeader('content-type'); // true

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]

isHTML()

tWithHeaders.php:119

function isHTML(): bool

returns bool true if getContentExtension is 'html'

isIe()

tWithHeaders.php:84

function isIe(): bool

returns

bool

true if the User-Agent looks like Internet Explorer

isIphone()

tWithHeaders.php:77

function isIphone(): bool

returns

bool

true if the User-Agent looks like mobile Safari on iPhone

isJSON()

tWithHeaders.php:126

function isJSON(): bool

returns bool true if getContentExtension is 'json'

isMac()

tWithHeaders.php:98

function isMac(): bool

returns

bool

true if the User-Agent mentions macOS

isMobile()

tWithHeaders.php:105

function isMobile(): bool

returns

bool

true if the User-Agent looks like a mobile device/browser

isWindows()

tWithHeaders.php:91

function isWindows(): bool

returns

bool

true if the User-Agent mentions Windows

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

setCacheControl($cache, $pragma)

tWithHeaders.php:305

Set the Cache-Control header (and, optionally, the legacy Pragma header alongside it).

protected function setCacheControl($cache, $pragma = null): self

$cache		cache method 'public', 'private', 'no-cache', 'no-store'
$pragma = null		if given, also sets the Pragma header (e.g. 'no-cache', for HTTP/1.0 clients)
returns	self

$msg->setCacheControl('no-cache', 'no-cache');

setContentType($type, $charset)

tWithHeaders.php:293

Set the Content-Type header, appending a charset parameter (unless $charset is null/empty).

protected function setContentType(string $type, ?string $charset = 'utf-8'): self

$type	string	the media type, e.g. 'text/html' or one of the framework's MIME_* constants
$charset = 'utf-8'	null \| string	appended as `;charset=$charset`; pass null/'' to omit it entirely
returns	self

$msg->setContentType('text/html'); $msg->getHeaderLine('Content-Type'); // 'text/html;charset=utf-8'

$msg->setContentType('application/octet-stream', null); // no charset appended

setExpires($time)

tWithHeaders.php:317

Set the Expires header from a unix timestamp, formatted as an RFC 7231 HTTP-date.

protected function setExpires(?int $time): self

$time	null \| int	a unix timestamp; 0 (or any past time) tells clients/caches the response is already stale
returns	self

$msg->setExpires(0); $msg->getHeaderLine('Expires'); // 'Thu, 01 Jan 1970 00:00:00 GMT'

setHeader($name, $value)

tWithHeaders.php:143

Set header, replacing any previous value(s) for the same (case-insensitively matched) header name.

protected function setHeader(string $name, array|string $value): self

$name	string
$value	array \| string	if a string, it is split on ',' into the multiple values PSR-7 expects a header to hold (e.g. 'a,b' becomes ['a', 'b']) -- pass an array (even a single-element one, e.g. `[$value]`) if $value may itself legitimately contain a comma that must NOT be split (an HTTP-date value like 'Thu, 01 Jan ...' is the classic example -- see `setExpires`)
returns	self

$msg->setHeader('Content-Type', 'text/html');

$msg->setHeader('Accept', 'text/html,application/json'); // stored as ['text/html', 'application/json']

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

unsetHeader($name)

tWithHeaders.php:179

Remove a header entirely.

protected function unsetHeader(string $name): self

$name	string
returns	self

$msg->unsetHeader('X-Tags'); $msg->hasHeader('X-Tags'); // false

withAddedHeader($name, $value)

aMessage.php:174

Return an instance with the specified header appended with the given value.

function withAddedHeader($name, $value): self

Existing values for the specified header will be maintained. The new value(s) will be appended to the existing list. If the header did not exist previously, it will be added. This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new header and/or value.

$name		Case-insensitive header field name to add.
$value		Header value(s).
returns	self
throws		for invalid header names or values.

$msg->withAddedHeader('Accept', 'application/json'); // appended alongside any existing Accept value(s)

withCacheControl($cache, $pragma)

aMessage.php:85

Set cache control of a clone.

function withCacheControl($cache, $pragma = null): self

$cache		cache method 'public', 'private', 'no-cache', 'no-store'
$pragma = null
returns	self

$msg->withCacheControl('no-cache', 'no-cache');

withContentType($type, $charset)

aMessage.php:73

Set content type of a clone.

function withContentType(string $type, ?string $charset = 'utf-8'): self

$type	string	either one the constant MIME_* or a string
$charset = 'utf-8'	null \| string
returns	self

$msg->withContentType('application/json');

withExpires($time)

aMessage.php:96

Set cache expire date of a clone.

function withExpires($time): self

$time		a unix timestamp
returns	self

$msg->withExpires(0); // clone's Expires header is set to the epoch (already stale)

withHeader($name, $value)

aMessage.php:152

Return an instance with the provided value replacing the specified header.

function withHeader($name, $value): self

While header names are case-insensitive, the casing of the header will be preserved by this function, and returned from getHeaders(). This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new and/or updated header and value.

$name		Case-insensitive header field name.
$value		Header value(s).
returns	self
throws		for invalid header names or values.

$msg->withHeader('Content-Type', 'text/html'); // replaces any existing Content-Type value(s)

withHeaders($headers, $reset)

aMessage.php:56

Return a clone with every header in $headers set (through tWithHeaders::setHeader, so each value replaces any existing one for the same header name).

function withHeaders($headers, $reset = false): self

$headers		name => value
$reset = false		if true, every existing header is dropped first, so the clone ends up with ONLY $headers
returns	self

$msg->withHeaders(['X-New' => 'x'], true); // the clone has just 'X-New', nothing from $msg

withoutHeader($name)

aMessage.php:192

Return an instance without the specified header.

function withoutHeader($name): self

Header resolution MUST be done without case-sensitivity. This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that removes the named header.

$name		Case-insensitive header field name to remove.
returns	self

$msg->withoutHeader('X-Debug');

withParsedBody($data)

abstractaMessage.php:42

abstract function withParsedBody(ArrayAccess|array|null $data): self

$data	ArrayAccess \| array \| null
returns	self	a clone with its parsed body replaced by $data

withProtocolVersion($version)

aMessage.php:129

Return an instance with the specified HTTP protocol version.

function withProtocolVersion($version): self

The version string MUST contain only the HTTP version number (e.g., "1.1", "1.0"). This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new protocol version.

$version		HTTP protocol version
returns	self

$msg->withProtocolVersion('1.1');

__construct($headers)

aMessage.php:36

function __construct(array $headers = [])

$headers = [] array name => value, set directly on this (not-yet-shared) instance -- unlike withHeader, no cloning happens here since the instance doesn't exist yet

Inherited members (2)

	Methods	Declared by	Description
	`getBody()`	`MessageInterface`	Gets the body of the message.
	`withBody($body)`	`MessageInterface`	Return an instance with the specified message body.