phpbotgram

ChatActionMiddleware extends BaseMiddleware
in package

FinalYes

Dispatcher-side middleware that wraps every Message handler with a {@see ChatActionSender} by default.

Mirrors the second class in upstream aiogram/utils/chat_action.py (ChatActionMiddleware).

Default-ON behaviour (upstream parity): when mounted, the middleware sends typing for every Message handler automatically. To opt out for a specific handler, register it with flags: ['chat_action' => false].

The chat_action flag value controls the behaviour:

  • Absent (null) → use 'typing' (default action)
  • false → explicit opt-out; sender is NOT started
  • A non-empty string → that string is used as the action value (e.g. 'upload_photo')
  • An array with keys action, interval, initial_sleep → overrides the defaults (all keys optional; same shape as upstream's dict form)

Example registration:

// Default: typing is sent automatically for every Message handler.
$router->message->register($handler);

// Custom action:
$router->message->register($handler, flags: ['chat_action' => 'upload_photo']);

// Explicit opt-out:
$router->message->register($handler, flags: ['chat_action' => false]);

The middleware resolves the bot from $data['bot'] and the chat context from the event itself (must be a Message). For non-Message events or absent chat context, the middleware falls through without starting a sender.

Table of Contents

Constants

DEFAULT_ACTION  : string = 'typing'
FLAG_NAME  : string = 'chat_action'

Properties

$initialSleep  : float
$interval  : float

Methods

__construct()  : mixed
__invoke()  : mixed
resolveChatActionFlag()  : null|array<string, mixed>|bool|string
Returns the raw `chat_action` flag value from the handler metadata.

Constants

Properties

Methods

__construct()

public __construct([float $interval = 5.0 ][, float $initialSleep = 0.0 ]) : mixed
Parameters
$interval : float = 5.0

Seconds between repeated sendChatAction calls. Defaults to 5.0 (matches Telegram's 5 s expiry window). Reduced values are useful in tests.

$initialSleep : float = 0.0

Seconds to wait before the first send. Defaults to 0.0.

__invoke()

public __invoke(Closure $handler, object $event, array<string|int, mixed> $data) : mixed
Parameters
$handler : Closure
$event : object
$data : array<string|int, mixed>

resolveChatActionFlag()

Returns the raw `chat_action` flag value from the handler metadata.

private resolveChatActionFlag(array<string, mixed> $data) : null|array<string, mixed>|bool|string
  • Returns null when no HandlerObject is present in $data (e.g. standalone unit tests without dispatcher wiring), OR when the flag key is not set — both cases trigger the default-ON typing path.
  • Returns false when the flag is explicitly set to false (opt-out).
  • Returns the raw value (string, array, true) otherwise.

The handler is injected as $data['handler'] by the dispatcher; if the key is absent, null is returned (default-ON).

Parameters
$data : array<string, mixed>
Return values
null|array<string, mixed>|bool|string —

Flag value, or null if not set.

On this page

Search results