phpbotgram

SceneRegistry
in package
implements SceneRegistryInterface

FinalYes

Registry that owns all registered scene classes and wires the per-update `ScenesManager` into the dispatcher middleware stack.

Mirrors SceneRegistry (aiogram/fsm/scene.py:746-887).

Middleware wiring

When the constructor receives a Dispatcher the registry attaches a single outer-middleware to the update observer (the synthetic dispatcher-level update channel). For any other Router it attaches to all observers except update and error.

Both middleware paths inject a ScenesManager under the 'scenes' key of the dispatcher data bag whenever a FsmContext ('state') is present.

Signature deviation from upstream

Python's add(*scenes, router=None) uses positional variadics followed by a named default — a combination PHP supports since 8.1. However, forwarding a named argument after a variadic in PHP 8.1+ requires the call-site to use the named-argument syntax explicitly, which is awkward for most callers. This port uses add(array $scenes, ?Router $router = null) instead: callers pass a list of class-strings as the first argument and an optional target router as the second. register() is unchanged from upstream and delegates to add().

Table of Contents

Interfaces

SceneRegistryInterface
Resolves a scene identifier to a concrete `Scene` subclass name.

Constants

NULL_STATE_KEY  : string = "\x00null"
Sentinel used as the array key for scenes registered under `null` state.

Properties

$registerOnAdd  : bool
$router  : Router
$scenes  : array<string, Scene>>
Registered scenes keyed by their FSM state string, or the `NULL_STATE_KEY` sentinel for scenes registered under `null` state.

Methods

__construct()  : mixed
add()  : void
Register one or more scene classes.
get()  : Scene>
Resolve `$sceneType` to a concrete `Scene` class-string.
register()  : void
Register scenes and always include them into `$this->router`.
buildMiddleware()  : BaseMiddleware
Build the per-observer middleware for the non-Dispatcher Router path.
buildUpdateMiddleware()  : BaseMiddleware
Build the update middleware for the Dispatcher path.
setupMiddleware()  : void
Attach outer middleware to the appropriate observers on `$router`.

Constants

NULL_STATE_KEY

Sentinel used as the array key for scenes registered under `null` state.

private string NULL_STATE_KEY = "\x00null"

PHP 8.5 deprecates null as an array key / array_key_exists argument. Internally we substitute \0null (a NUL-prefixed string guaranteed not to appear in any real state name) so null-state scenes can still be stored and retrieved without deprecation warnings.

Properties

$scenes

Registered scenes keyed by their FSM state string, or the `NULL_STATE_KEY` sentinel for scenes registered under `null` state.

private array<string, Scene>> $scenes = []

Methods

__construct()

public __construct(Router $router[, bool $registerOnAdd = true ]) : mixed
Parameters
$router : Router

The root router (or Dispatcher) to attach outer middleware to and to include scene routers into when $registerOnAdd is true.

$registerOnAdd : bool = true

When true (default), every scene added via add() without an explicit $router argument is included into $this->router automatically.

add()

Register one or more scene classes.

public add(array<int, Scene>> $scenes[, Router|null $router = null ]) : void

For each scene:

  • Its FSM state (from $class::sceneConfig()->state via sceneState()) is stored in the registry.
  • When $router is non-null the scene's router sub-tree is included into that router.
  • When $router is null and $registerOnAdd is true, the sub-tree is included into $this->router.
  • When $router is null and $registerOnAdd is false, the scene is stored in the registry only (no router inclusion).

Deviation from upstream's add(*scenes, router=None): PHP signature is add(array $scenes, ?Router $router = null). See class-level docblock.

Parameters
$scenes : array<int, Scene>>
$router : Router|null = null
Tags
throws
InvalidArgumentException

When the list is empty.

SceneException

When a scene with the same state is already registered.

get()

Resolve `$sceneType` to a concrete `Scene` class-string.

public get(null|Scene>|State|string $sceneType) : Scene>

Accepted forms (mirrors upstream SceneRegistry.get):

  • class-string<Scene> — resolve via $class::sceneConfig()->state.
  • State instance — resolve via $state->state().
  • string — resolved directly as the state key.
  • null — returns the scene registered under null state (or throws).
Parameters
$sceneType : null|Scene>|State|string
Tags
throws
SceneException

When the identifier does not match any registered scene.

Return values
Scene>

register()

Register scenes and always include them into `$this->router`.

public register(array<int, Scene>> $scenes) : void

Sugar for add($scenes, $this->router). Mirrors upstream's register(*scenes) → add(*scenes, router=self.router).

Parameters
$scenes : array<int, Scene>>
Tags
throws
InvalidArgumentException

When the list is empty.

SceneException

When a scene with the same state is already registered.

buildMiddleware()

Build the per-observer middleware for the non-Dispatcher Router path.

private buildMiddleware() : BaseMiddleware

Reads $data['event_update'] to determine the update type and delegates to the handler after injecting ScenesManager under 'scenes'.

Mirrors SceneRegistry._middleware (aiogram/fsm/scene.py:793-808).

Return values
BaseMiddleware

buildUpdateMiddleware()

Build the update middleware for the Dispatcher path.

private buildUpdateMiddleware() : BaseMiddleware

Injects ScenesManager into the data bag keyed as 'scenes' when the data bag already contains a 'state' (FsmContext) value. Bypasses the chain with a plain delegate when 'state' is absent.

The event is expected to be an Update (Dispatcher path). The event_type and concrete sub-event are read from the Update.

Mirrors SceneRegistry._update_middleware (aiogram/fsm/scene.py:776-791).

Return values
BaseMiddleware

setupMiddleware()

Attach outer middleware to the appropriate observers on `$router`.

private setupMiddleware(Router $router) : void
  • When $router is a Dispatcher: register updateMiddleware on the update observer. Upstream attaches to the single synthetic update observer (router.update.outer_middleware).
  • Otherwise: register middleware on every observer except update and error (which are internal / infrastructure channels).

Mirrors SceneRegistry._setup_middleware (aiogram/fsm/scene.py:765-774).

Parameters
$router : Router
On this page

Search results