phpbotgram

State
in package

Represents a single FSM state value with optional group association.

Mirrors aiogram.fsm.state.State (aiogram/fsm/state.py:1-85).

Upstream vs PHP differences

Python's State relies on the __set_name__ PEP 487 hook to bind the attribute name when the class is defined and on StatesGroupMeta to set the parent group. PHP has neither mechanism: class declaration is passive and constants/static properties are not observed by the runtime. The PHP port therefore uses explicit bootstrap via StatesGroup::bootstrap():

  • setName(string) — called by StatesGroup::bootstrap() to default the raw state to the property name (mirrors __set_name__).
  • setParent(string) — called by StatesGroup::bootstrap() to bind the owning group class (mirrors set_parent(group)).

Both setters are idempotent after the first call; subsequent calls are silently ignored so that bootstrap can be called multiple times safely.

Qualified state name

state() returns:

  • null — when $rawState is null (unbound or no-state sentinel).
  • '*' — when $rawState === '*' (any-state sentinel).
  • '<group>:<name>' — otherwise, where <group> is resolved from (in priority): an explicit $groupName constructor arg → the owning group's fullGroupName() → the bare fallback '@'.

Filter contract

__invoke matches the Filter::__invoke signature (object $event, mixed ...$kwargs): bool|array. State reads $kwargs['rawState'] ?? null and:

  • returns true when $rawState === '*' (always matches).
  • returns true when the raw state string equals $this->state().
  • returns false otherwise.

Mirrors State.__call__ (aiogram/fsm/state.py:60-68).

Tags
see
StatesGroup

for the bootstrap mechanism.

States

for the module-level default_state and any_state equivalents.

Table of Contents

Properties

$group  : null|StatesGroup>
The owning `StatesGroup` subclass, set by `setParent()` at bootstrap.
$groupName  : string|null
Optional explicit group-name prefix. When provided it overrides the parent group's `fullGroupName()` when building the qualified name.
$nameSet  : bool
Whether `setName` has already been called (idempotency guard).
$parentSet  : bool
Whether `setParent` has already been called (idempotency guard).
$rawState  : string|null
The raw (unqualified) state name as supplied at construction or via `setName()`. `null` means the no-state sentinel (default_state).

Methods

__construct()  : mixed
Construct a new State.
__invoke()  : array<string, mixed>|bool
Evaluate whether the event is in this state.
equals()  : bool
Equality comparison.
rawState()  : string|null
Return the raw (unqualified) state name as stored.
setName()  : void
Default the raw state to `$name` when no explicit state was given at construction. Idempotent — subsequent calls are silently ignored.
setParent()  : void
Bind this state to the owning `StatesGroup` subclass. Idempotent — subsequent calls are silently ignored.
state()  : string|null
Return the fully-qualified state name, or `null` / `'*'` for sentinels.

Properties

$group

The owning `StatesGroup` subclass, set by `setParent()` at bootstrap.

private null|StatesGroup> $group = null

$groupName

Optional explicit group-name prefix. When provided it overrides the parent group's `fullGroupName()` when building the qualified name.

private string|null $groupName

$nameSet

Whether `setName` has already been called (idempotency guard).

private bool $nameSet = false

$parentSet

Whether `setParent` has already been called (idempotency guard).

private bool $parentSet = false

$rawState

The raw (unqualified) state name as supplied at construction or via `setName()`. `null` means the no-state sentinel (default_state).

private string|null $rawState

'*' means the any-state sentinel.

Methods

__construct()

Construct a new State.

public __construct([null|string $state = null ][, null|string $groupName = null ]) : mixed
Parameters
$state : null|string = null

Raw state name. Pass null for the no-state sentinel or '*' for any-state.

$groupName : null|string = null

Explicit group-name prefix. When omitted the bootstrap-assigned parent group's fullGroupName() is used.

__invoke()

Evaluate whether the event is in this state.

public __invoke(object $event, mixed ...$kwargs) : array<string, mixed>|bool

Reads $kwargs['raw_state'] ?? null (snake_case, matching FsmContextMiddleware::RAW_STATE_KEY) from the variadic dispatcher kwargs bag and matches:

  • always returns true when $this->rawState === '*'.
  • returns true when the raw-state string equals $this->state().
  • returns false otherwise.

Signature matches Filter::__invoke so instances can be registered directly as dispatcher filters.

Mirrors State.__call__ (aiogram/fsm/state.py:60-68).

Parameters
$event : object
$kwargs : mixed
Return values
array<string, mixed>|bool

equals()

Equality comparison.

public equals(State|string $other) : bool

Accepts another State (compare qualified names) or a string (compare the qualified name to the string).

Mirrors State.__eq__ (aiogram/fsm/state.py:70-76).

Parameters
$other : State|string
Return values
bool

rawState()

Return the raw (unqualified) state name as stored.

public rawState() : string|null
Return values
string|null

setName()

Default the raw state to `$name` when no explicit state was given at construction. Idempotent — subsequent calls are silently ignored.

public setName(string $name) : void

Framework-internal: called once by StatesGroup::bootstrap() to mirror Python's __set_name__ PEP 487 hook.

Parameters
$name : string

setParent()

Bind this state to the owning `StatesGroup` subclass. Idempotent — subsequent calls are silently ignored.

public setParent(StatesGroup> $groupClass) : void

Framework-internal: called once by StatesGroup::bootstrap() to mirror Python's set_parent(group).

Parameters
$groupClass : StatesGroup>

state()

Return the fully-qualified state name, or `null` / `'*'` for sentinels.

public state() : string|null

Resolution order for the group prefix:

  1. Explicit $groupName constructor arg.
  2. $group::fullGroupName() (set at bootstrap).
  3. The bare fallback '@'.

Mirrors State.state property (aiogram/fsm/state.py:36-46).

Return values
string|null
On this page

Search results