phpbotgram

SimpleRequestHandler extends BaseRequestHandler
in package

FinalYes

Single-bot webhook handler with optional constant-time secret-token validation.

Port of aiogram.webhook.aiohttp_server.SimpleRequestHandler (lines 212–247).

Secret-token validation

When $secretToken is provided (non-null, non-empty), the X-Telegram-Bot-Api-Secret-Token header value sent by Telegram is compared against it using hash_equals — the PHP stdlib equivalent of Python's secrets.compare_digest. Both functions use constant-time comparison to prevent timing-attack leakage of the stored secret.

Empty-string edge case: PHP's "" is truthy unlike Python's "" which is falsy. An explicit === null || === '' guard ensures that passing an empty string as $secretToken has the same open-access semantics as passing null — matching upstream's if self.secret_token: test.

Background mode

$handleInBackground defaults to true here (upstream default), whereas BaseRequestHandler defaults to false. Callers that need synchronous dispatch can pass handleInBackground: false explicitly.

Table of Contents

Constants

MAX_BODY_BYTES  : mixed = 5 * 1024 * 1024
Maximum number of bytes buffered from the request body.

Properties

$data  : array<string, mixed>
Extra workflow kwargs forwarded to `Dispatcher::feedWebhookUpdate` / `feedRawUpdate` on every request.
$dispatcher  : Dispatcher
$handleInBackground  : bool
$bot  : Bot
$secretToken  : string|null

Methods

__construct()  : mixed
awaitBackgroundTasks()  : void
Await all in-flight background tasks spawned by handleRequestBackground().
close()  : void
Close the bot's underlying HTTP session / connection pool.
handleRequest()  : Response
Entry-point called by amphp/http-server for every incoming POST.
register()  : void
Register this handler at `$path` using the provided registration callback.
resolveBot()  : Bot
Return the pre-configured bot regardless of the incoming request.
verifySecret()  : bool
Validate the Telegram secret-token header value.

Constants

MAX_BODY_BYTES

Maximum number of bytes buffered from the request body.

public mixed MAX_BODY_BYTES = 5 * 1024 * 1024

5 MiB is far larger than any Telegram update (typically < 64 KiB) and prevents an unbounded-buffer DoS from a malicious client.

Properties

$data read-only

Extra workflow kwargs forwarded to `Dispatcher::feedWebhookUpdate` / `feedRawUpdate` on every request.

protected array<string, mixed> $data

Methods

__construct()

public __construct(Dispatcher $dispatcher, Bot $bot[, bool $handleInBackground = true ][, string|null $secretToken = null ][, array<string, mixed> $data = [] ]) : mixed
Parameters
$dispatcher : Dispatcher
$bot : Bot
$handleInBackground : bool = true
$secretToken : string|null = null
$data : array<string, mixed> = []

Extra kwargs forwarded to feedWebhookUpdate.

awaitBackgroundTasks()

Await all in-flight background tasks spawned by handleRequestBackground().

public awaitBackgroundTasks() : void

Call this during graceful shutdown (Setup::register and AmphpServer::run wire it into the onStop callback) to ensure FSM writes and outbound API calls complete before the server shuts down.

close()

Close the bot's underlying HTTP session / connection pool.

public close() : void

handleRequest()

Entry-point called by amphp/http-server for every incoming POST.

public final handleRequest(Request $request) : Response

Flow:

  1. Resolve the bot for this request.
  2. Check the secret token header.
  3. Dispatch in-line or in the background depending on $handleInBackground.
Parameters
$request : Request
Return values
Response

register()

Register this handler at `$path` using the provided registration callback.

public register(callable(string, RequestHandler): void $registerRoute, string $path) : void

Since amphp/http-server-router is an optional dependency not bundled in this project, the caller supplies a routing callback rather than a concrete router type. Typical usage with amphp/http-server-router:

$handler->register(
    fn (string $path, RequestHandler $h) => $router->addRoute('POST', $path, $h),
    '/webhook',
);
Parameters
$registerRoute : callable(string, RequestHandler): void

A callback that registers a POST route for the given path.

$path : string

The URL path to bind (e.g. '/webhook').

resolveBot()

Return the pre-configured bot regardless of the incoming request.

public resolveBot(Request $request) : Bot
Parameters
$request : Request

The incoming HTTP request.

Return values
Bot

verifySecret()

Validate the Telegram secret-token header value.

public verifySecret(string $telegramSecretToken, Bot $bot) : bool

Returns true (accept) when no secret is configured, or when the supplied header value matches the configured secret via a constant-time comparison. Returns false (reject) otherwise.

Parameters
$telegramSecretToken : string

The raw header value (empty string when absent).

$bot : Bot

The resolved bot for this request (unused here).

Return values
bool
On this page

Search results