phpbotgram

SceneWizard
in package

Application

FinalYes

Per-scene state machine instance handed to each scene method.

SceneWizard is the surface that scene handler methods use to drive transitions, read/write FSM data, and dispatch lifecycle actions. Each scene handler method receives its enclosing scene's wizard via the $this->wizard property (typed SceneWizard).

Mirrors SceneWizard (aiogram/fsm/scene.py:442-655).

Lifecycle flow

enter() → setState(state) → onAction(Enter) leave() → [history.snapshot()] → onAction(Leave) exit() → history.clear() → onAction(Exit) → manager.enter(null) back() → leave(withHistory=false) → history.rollback() → manager.enter(prev) retake() → goto(sceneConfig.state) goto(target) → leave() → manager.enter(target)

Data delegation

setData, getData, getValue, updateData, and clearData all delegate directly to the injected FsmContext.

SceneConfig.actions shape

actions[SceneAction::Enter->value]['message'] = callable

onAction() resolves actions[$action->value][$updateType] and calls the matching callable with ($this->scene, $this->event, ...$data, ...$kwargs).

Properties

$data : array<string, mixed>
$event : object
$manager : SceneManagerInterface
$scene : Scene|null: The scene instance this wizard is bound to.
$sceneConfig : SceneConfig
$state : FsmContext
$updateType : string

Methods

__construct() : mixed
back() : void: Roll back to the previous scene: leave without snapshot, then re-enter the scene from history.
clearData() : void: Clear the FSM data payload (set to empty array).
enter() : void: Enter the scene: set FSM state, optionally reset data/history, then dispatch the `Enter` lifecycle action.
exit() : void: Exit the FSM entirely: clear history, dispatch `Exit`, then enter `null`.
getData() : array<string, mixed>: Retrieve the current FSM data payload.
getValue() : mixed: Read a single value from the FSM data payload.
goto() : void: Transition to `$scene`: leave (with history snapshot), then enter the target scene.
leave() : void: Leave the scene: optionally snapshot history, then dispatch `Leave`.
retake() : void: Re-enter the current scene (restart from the beginning).
setData() : void: Replace the FSM data payload entirely.
updateData() : array<string, mixed>: Merge data into the existing FSM data payload.
namedOnly() : array<string, mixed>: Strip integer-keyed entries from a kwarg bag before spread.
onAction() : bool: Dispatch a lifecycle action to the registered handler for this wizard's `$updateType`, if one exists.

$data


        public
            array<string, mixed>
    $data

$event read-only


        public
            object
    $event

$manager read-only


        public
            SceneManagerInterface
    $manager

$scene

The scene instance this wizard is bound to.


        public
            Scene|null
    $scene
     = null

Populated after construction by the framework (post-init injection). null until the framework sets it; onAction() throws SceneException if called while still null.

$sceneConfig read-only


        public
            SceneConfig
    $sceneConfig

$state read-only


        public
            FsmContext
    $state

$updateType read-only


        public
            string
    $updateType

__construct()


    public
                    __construct(SceneConfig $sceneConfig, SceneManagerInterface $manager, FsmContext $state, string $updateType, object $event, array<string, mixed> $data) : mixed

Parameters

$sceneConfig : SceneConfig: Immutable scene configuration record.
$manager : SceneManagerInterface: Manager that drives scene entry.
$state : FsmContext: FSM context for state + data operations.
$updateType : string: Telegram update-type key (e.g. 'message').
$event : object: The raw Telegram event object.
$data : array<string, mixed>: Dispatcher kwargs bag (mutable).

back()

Roll back to the previous scene: leave without snapshot, then re-enter the scene from history.


    public
                    back(mixed ...$kwargs) : void

Mirrors SceneWizard.back() (aiogram/fsm/scene.py:499-504).

Parameters

$kwargs : mixed: Extra kwargs forwarded to the action handler. Integer-keyed entries are silently dropped.

clearData()

Clear the FSM data payload (set to empty array).


    public
                    clearData() : void

Delegates to FsmContext::setData([]).

enter()

Enter the scene: set FSM state, optionally reset data/history, then dispatch the `Enter` lifecycle action.


    public
                    enter(mixed ...$kwargs) : void

Mirrors SceneWizard.enter() (aiogram/fsm/scene.py:474-484).

Parameters

$kwargs : mixed: Extra kwargs forwarded to the action handler. Integer-keyed entries are silently dropped to prevent PHP's "positional after named" unpack Error.

exit()

Exit the FSM entirely: clear history, dispatch `Exit`, then enter `null`.


    public
                    exit(mixed ...$kwargs) : void

Mirrors SceneWizard.exit() (aiogram/fsm/scene.py:492-497).

Parameters

$kwargs : mixed: Extra kwargs forwarded to the action handler. Integer-keyed entries are silently dropped.

getData()

Retrieve the current FSM data payload.


    public
                    getData() : array<string, mixed>

Delegates to FsmContext::getData.

Return values

array<string, mixed>

getValue()

Read a single value from the FSM data payload.


    public
                    getValue(string $key[, mixed $default = null ]) : mixed

Delegates to FsmContext::getValue.

Parameters

$key : string: Key within the data payload.
$default : mixed = null: Returned when $key is absent.

goto()

Transition to `$scene`: leave (with history snapshot), then enter the target scene.


    public
                    goto(Scene>|State|string $scene, mixed ...$kwargs) : void

Mirrors SceneWizard.goto() (aiogram/fsm/scene.py:510-513).

Parameters

$scene : Scene>|State|string: Target scene.
$kwargs : mixed: Extra kwargs forwarded to the action handler. Integer-keyed entries are silently dropped.

leave()

Leave the scene: optionally snapshot history, then dispatch `Leave`.


    public
                    leave([bool $withHistory = true ], mixed ...$kwargs) : void

Mirrors SceneWizard.leave() (aiogram/fsm/scene.py:486-490).

Parameters

$withHistory : bool = true: When true (default), push the current scene state onto the history stack before leaving.
$kwargs : mixed: Extra kwargs forwarded to the action handler. Integer-keyed entries are silently dropped.

retake()

Re-enter the current scene (restart from the beginning).


    public
                    retake(mixed ...$kwargs) : void

Requires that the scene has a configured state (i.e. $sceneConfig->state !== null). A scene without a state cannot be re-entered — calling retake() on it is a programming error and throws SceneException.

Mirrors SceneWizard.retake() (aiogram/fsm/scene.py:506-508).

Parameters

$kwargs : mixed: Extra kwargs forwarded to the action handler. Integer-keyed entries are silently dropped.

setData()

Replace the FSM data payload entirely.


    public
                    setData(array<string, mixed> $data) : void

Delegates to FsmContext::setData.

Parameters

$data : array<string, mixed>

updateData()

Merge data into the existing FSM data payload.


    public
                    updateData([array<string, mixed>|null $data = null ], mixed ...$kwargs) : array<string, mixed>

Delegates to FsmContext::updateData.

Parameters

$data : array<string, mixed>|null = null: Optional explicit data to merge.
$kwargs : mixed: Additional named key/value pairs.

Return values

array<string, mixed> —

The merged data map as persisted.

namedOnly()

Strip integer-keyed entries from a kwarg bag before spread.


    private
            static        namedOnly(array<int|string, mixed> $kwargs) : array<string, mixed>

PHP throws "Cannot use positional argument after named argument during unpacking" if an array spread contains any integer-keyed element alongside string-keyed (named) ones. User-supplied ...$kwargs bags may contain integer keys from generic data arrays. Filtering them here keeps all public lifecycle surfaces safe regardless of caller origin.

Parameters

$kwargs : array<int|string, mixed>

Return values

array<string, mixed>

onAction()

Dispatch a lifecycle action to the registered handler for this wizard's `$updateType`, if one exists.


    private
                    onAction(SceneAction $action, mixed ...$kwargs) : bool

Mirrors SceneWizard._on_action() (aiogram/fsm/scene.py:515-527).

Resolution:

Look up sceneConfig->actions[$action->value] (the per-action map).
Look up [$this->updateType] within that map to find the callable.
Call it with ($this->scene, $this->event, ...$this->data, ...$kwargs).

Parameters

$action : SceneAction: The lifecycle action to dispatch.
$kwargs : mixed: Extra kwargs forwarded to the callable.

Return values

bool —

true when a handler was found and called; false otherwise.

SceneWizard in package Application

Lifecycle flow

Data delegation

SceneConfig.actions shape

Table of Contents

Properties

Methods

Properties

$data

$event read-only

$manager read-only

$scene

$sceneConfig read-only

$state read-only

$updateType read-only

Methods

__construct()

Parameters

back()

Parameters

clearData()

enter()

Parameters

exit()

Parameters

getData()

Return values

getValue()

Parameters

goto()

Parameters

leave()

Parameters

retake()

Parameters

Tags

setData()

Parameters

updateData()

Parameters

Return values

namedOnly()

Parameters

Return values

onAction()

Parameters

Tags

Return values

SceneWizard
in package

Application