phpbotgram

WebApp
in package

FinalYes

HMAC-SHA256-based standard WebApp signature validation and init data parsing.

Port of upstream aiogram/utils/web_app.py.

This variant uses the bot token to derive the HMAC secret and verify the hash field in the init data. Use this on the bot server where the token is available.

Table of Contents

Methods

checkSignature()  : bool
Verify the HMAC-SHA256 signature of WebApp init data.
parseInitData()  : WebAppInitData
Parse a WebApp init data query string into a {@see WebAppInitData} DTO.
safeParseInitData()  : WebAppInitData
Parse and validate WebApp init data in one step.
__construct()  : mixed
parseQuery()  : array<string, string>
Parse a URL-encoded query string into a string-keyed assoc array, preserving the literal key names (no `.` or space mangling). Mirrors Python's `urllib.parse.parse_qsl(strict_parsing=True)`.

Methods

checkSignature()

Verify the HMAC-SHA256 signature of WebApp init data.

public static checkSignature(string $token, string $initData) : bool

The algorithm:

  1. Parse the query string.
  2. Remove hash (the signature to verify) and signature (Ed25519).
  3. Sort remaining fields alphabetically.
  4. Build data-check string as "key=value" pairs joined by newlines.
  5. Derive HMAC key: HMAC-SHA256("WebAppData", token).
  6. Compute HMAC-SHA256(secret, data_check_string).
  7. Compare with the received hash using constant-time comparison.
Parameters
$token : string

the bot token (e.g. "123456:ABC-DEF...")

$initData : string

the raw WebApp init data query string

Return values
bool —

true if the signature is valid, false otherwise

parseInitData()

Parse a WebApp init data query string into a {@see WebAppInitData} DTO.

public static parseInitData(string $initData) : WebAppInitData

Any value that starts with [ or { is auto-decoded as JSON before DTO construction, mirroring upstream web_app.py:parse_webapp_init_data:

if value.startswith(('[', '{')):
    value = json.loads(value)

Known structured fields (user, receiver, chat) are additionally converted to typed DTOs.

Parameters
$initData : string

the raw WebApp init data query string

Tags
throws
JsonException

if any JSON-shaped field is malformed

InvalidArgumentException

if required fields (auth_date, hash) are missing

Return values
WebAppInitData

safeParseInitData()

Parse and validate WebApp init data in one step.

public static safeParseInitData(string $token, string $initData) : WebAppInitData

Calls self::checkSignature() first and throws if the signature is invalid, then delegates to self::parseInitData().

Parameters
$token : string

the bot token

$initData : string

the raw WebApp init data query string

Tags
throws
InvalidArgumentException

if the signature is invalid or required fields are missing

JsonException

if any nested JSON field is malformed

Return values
WebAppInitData

__construct()

private __construct() : mixed

parseQuery()

Parse a URL-encoded query string into a string-keyed assoc array, preserving the literal key names (no `.` or space mangling). Mirrors Python's `urllib.parse.parse_qsl(strict_parsing=True)`.

private static parseQuery(string $input) : array<string, string>
Parameters
$input : string
Return values
array<string, string>
On this page

Search results