StateFilter
extends Filter
in package
Filter that matches a Telegram event against one or more FSM states.
Mirrors aiogram.filters.state.StateFilter (aiogram/filters/state.py).
Accepted state types
Each positional argument to the constructor may be:
null— matches whenrawStateisnull(user has no active state).'*'— wildcard; always matches regardless ofrawState.- A plain state-name string — matches when
rawState === $string. - A class-string<StatesGroup> — detected at runtime via
class_exists+is_subclass_of; bootstrapped defensively then delegated to viaStatesGroup::match(). - A
Stateinstance — delegates toState::__invoke. - A
StatesGroupinstance — delegates toStatesGroup::match().
Defensive bootstrapping
StateFilter calls StatesGroup::bootstrapIfNeeded() before any group look-up
so that user code which omits an explicit MyGroup::bootstrap() call still
produces correctly qualified state names. bootstrapIfNeeded() is idempotent
— calling it on an already-bootstrapped group is a no-op.
For State instances the defensive bootstrap is triggered when the State
belongs to a group that was bootstrapped as part of processing the current
filter invocation (e.g. when the group class-string appears alongside the
State instance in the constructor). Passing the group's class-string as one
of the states is the idiomatic way to ensure the group is bootstrapped;
StateFilter also accepts a StatesGroup instance for the same purpose.
Reading raw_state
FsmContextMiddleware injects the current FSM state into the kwargs bag as
raw_state (snake_case, matching FsmContextMiddleware::RAW_STATE_KEY and
the rest of the dispatcher's snake_case kwarg convention).
StateFilter reads $kwargs['raw_state'] ?? null — an absent key is
treated as null (no active state).
Tags
Table of Contents
Properties
- $states : array<int, null|State|StatesGroup|string>
Methods
- __construct() : mixed
- __invoke() : array<string, mixed>|bool
- Evaluate whether the event matches any of the registered states.
- 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
$states read-only
public
array<int, null|State|StatesGroup|string>
$states
Methods
__construct()
public
__construct(null|State|StatesGroup|string ...$states) : mixed
Parameters
- $states : null|State|StatesGroup|string
-
One or more states to match against. Strings may be plain state names,
'*', or class-strings ofStatesGroupsubclasses (detected at runtime).
__invoke()
Evaluate whether the event matches any of the registered states.
public
__invoke(object $event, mixed ...$kwargs) : array<string, mixed>|bool
Reads $kwargs['raw_state'] ?? null (injected by FsmContextMiddleware).
Returns true on the first match, false if no state matched.
Parameters
- $event : object
- $kwargs : mixed
Return values
array<string, mixed>|bool —See class docblock for the interpretation contract.
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
AndFilterany()
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
OrFilterinvertOf()
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