phpbotgram

ExceptionMessageFilter extends Filter
in package

FinalYes

Filter that accepts an `ErrorEvent` whose `->exception->getMessage()` matches a regex pattern; on match, returns the match metadata as kwargs so the dispatcher merges them into the handler invocation.

Port of aiogram.filters.exception.ExceptionMessageFilter (aiogram/filters/exception.py:30-57).

Pattern format

$pattern is a PCRE pattern STRING WITH DELIMITERS — the form preg_match consumes directly, e.g. '/^api error: (.*)$/'. Upstream accepts either a string or a precompiled re.Pattern; PHP has no standalone pattern object so the string form is the only option. The pattern is held verbatim on a readonly property so debuggers and potential future __toString introspection can recover it.

Upstream-parity anchoring

Upstream uses pattern.match(message) (exception.py:54). Python's re.Pattern.match is anchored at the start of the string — it matches only if the pattern satisfies at position 0, equivalent to wrapping the pattern in (?:\A). PHP's preg_match is unanchored by default and would match mid-string. To restore parity we apply the PCRE A modifier (PREG_ANCHOR), which anchors the pattern at the start of the subject string. The modifier is appended after the user-supplied closing delimiter, e.g. '/boom/' becomes '/boom/A'. Patterns that already include ^ or \A continue to work correctly (they anchor at the start, same as A); the A modifier is simply redundant in that case. Modifiers already present in the user pattern (/i, /u, etc.) are fully preserved.

Return shape

On accept the filter returns:

[
    'match'  => string, // the full matched substring ($matches[0])
    'groups' => list<string>, // numbered capture groups ($matches[1..])
]

Deviates from upstream's {'match_exception': re.Match} because PHP has no re.Match analogue; we surface the most useful pieces (matched text

  • captured groups) under stable kwarg names instead. Handlers that declare an $match and/or $groups parameter receive the values directly via the dispatcher's named-kwarg binding.

The match is performed against getMessage() (the throwable's textual message), not against the class name or the trace. Mirrors upstream's self.pattern.match(str(event.exception)) where str(exception) is Python's textual representation — for our PHP port the closest analogue is the human-readable message.

Table of Contents

Properties

$pattern  : string

Methods

__construct()  : mixed
__invoke()  : array{match: string, groups: list}|false
Match the registered pattern against `event->exception->getMessage()`.
all()  : AndFilter
Compose an AND across filters: every child must accept, kwargs cascade. PHP equivalent of Python's `f1 & f2`.
any()  : OrFilter
Compose an OR across filters: the first accepting child wins, no cascade. PHP equivalent of Python's `f1 | f2`.
invertOf()  : InvertFilter
Invert a filter's accept/reject decision. Named `invertOf` rather than `not` because PHP forbids a static and an instance method sharing one name in a single class (the instance-side `$f->not()` convenience may land in a later task).

Properties

Methods

__construct()

public __construct(string $pattern) : mixed
Parameters
$pattern : string

PCRE pattern STRING with delimiters (e.g. '/boom/'). Held verbatim — no compilation step because PHP's preg_match caches compiled patterns internally per process.

__invoke()

Match the registered pattern against `event->exception->getMessage()`.

public __invoke(object $event, mixed ...$kwargs) : array{match: string, groups: list}|false
Parameters
$event : object
$kwargs : mixed

Dispatcher kwargs bag — captured variadically so the full bag passes through CallableObject::prepareKwargs. Unused by this filter (event-only decision).

Return values
array{match: string, groups: list}|false —

On match, a kwargs dict for the dispatcher to merge. On miss or non-ErrorEvent event, false.

all()

Compose an AND across filters: every child must accept, kwargs cascade. PHP equivalent of Python's `f1 & f2`.

public static all(Filter ...$filters) : AndFilter
Parameters
$filters : Filter
Return values
AndFilter

any()

Compose an OR across filters: the first accepting child wins, no cascade. PHP equivalent of Python's `f1 | f2`.

public static any(Filter ...$filters) : OrFilter
Parameters
$filters : Filter
Return values
OrFilter

invertOf()

Invert a filter's accept/reject decision. Named `invertOf` rather than `not` because PHP forbids a static and an instance method sharing one name in a single class (the instance-side `$f->not()` convenience may land in a later task).

public static invertOf(Filter $filter) : InvertFilter
Parameters
$filter : Filter
Return values
InvertFilter
On this page

Search results