DeepLinking
in package
Telegram deep-linking helpers.
Port of upstream aiogram/utils/deep_linking.py.
Deviation from upstream: createDeepLink accepts a DeepLinkType enum
instead of an arbitrary string $linkType, providing compile-time safety.
The upstream Python API uses an await bot.me() coroutine; this PHP port
calls Bot::getMe() which is synchronous.
Caching: getUsername() memoises the bot username in a WeakMap keyed by
the Bot instance. Unlike spl_object_id(), WeakMap keys are true object
identities that auto-evict when the object is garbage-collected, eliminating
the GC-reuse hazard present in long-running daemons (or test suites that
recreate Bot instances).
Table of Contents
Constants
- BAD_PATTERN : mixed = '/[^A-Za-z0-9_-]/'
- Pattern that matches characters NOT allowed in a raw (un-encoded) payload.
- PAYLOAD_MAX_LENGTH : mixed = 64
- Maximum allowed payload length (bytes / characters — ASCII printable only).
Properties
- $usernameCache : null|WeakMap<Bot, string>
- Username cache keyed by Bot instance. WeakMap entries are automatically evicted when the Bot object is garbage-collected, preventing stale-cache bugs from `spl_object_id` reuse.
Methods
- createDeepLink() : string
- Build a Telegram deep link for the given bot username and link type.
- createStartAppLink() : string
- Create a `https://t.me/<bot>/<appName>?startapp=<payload>` link.
- createStartGroupLink() : string
- Create a `https://t.me/<bot>?startgroup=<payload>` link.
- createStartLink() : string
- Create a `https://t.me/<bot>?start=<payload>` link.
- __construct() : mixed
- getUsername() : string
- Return the bot's username, fetching it via `getMe()` on the first call and serving subsequent calls from the in-process WeakMap cache.
Constants
BAD_PATTERN
Pattern that matches characters NOT allowed in a raw (un-encoded) payload.
private
mixed
BAD_PATTERN
= '/[^A-Za-z0-9_-]/'
PAYLOAD_MAX_LENGTH
Maximum allowed payload length (bytes / characters — ASCII printable only).
private
mixed
PAYLOAD_MAX_LENGTH
= 64
Properties
$usernameCache
Username cache keyed by Bot instance. WeakMap entries are automatically evicted when the Bot object is garbage-collected, preventing stale-cache bugs from `spl_object_id` reuse.
private
static null|WeakMap<Bot, string>
$usernameCache
= null
Methods
createDeepLink()
Build a Telegram deep link for the given bot username and link type.
public
static createDeepLink(string $username, DeepLinkType $linkType, string $payload[, string|null $appName = null ][, bool $encode = false ][, null|callable(string): string $encoder = null ]) : string
Parameters
- $username : string
- $linkType : DeepLinkType
- $payload : string
- $appName : string|null = null
- $encode : bool = false
- $encoder : null|callable(string): string = null
-
optional payload encoder
Tags
Return values
stringcreateStartAppLink()
Create a `https://t.me/<bot>/<appName>?startapp=<payload>` link.
public
static createStartAppLink(Bot $bot, string $payload[, bool $encode = false ][, string|null $appName = null ][, null|callable(string): string $encoder = null ]) : string
Parameters
- $bot : Bot
- $payload : string
- $encode : bool = false
- $appName : string|null = null
- $encoder : null|callable(string): string = null
-
optional payload encoder
Return values
stringcreateStartGroupLink()
Create a `https://t.me/<bot>?startgroup=<payload>` link.
public
static createStartGroupLink(Bot $bot, string $payload[, bool $encode = false ][, null|callable(string): string $encoder = null ]) : string
Parameters
- $bot : Bot
- $payload : string
- $encode : bool = false
- $encoder : null|callable(string): string = null
-
optional payload encoder
Return values
stringcreateStartLink()
Create a `https://t.me/<bot>?start=<payload>` link.
public
static createStartLink(Bot $bot, string $payload[, bool $encode = false ][, null|callable(string): string $encoder = null ]) : string
Parameters
- $bot : Bot
- $payload : string
- $encode : bool = false
- $encoder : null|callable(string): string = null
-
optional payload encoder (implies $encode=true)
Return values
string__construct()
private
__construct() : mixed
getUsername()
Return the bot's username, fetching it via `getMe()` on the first call and serving subsequent calls from the in-process WeakMap cache.
private
static getUsername(Bot $bot) : string
Parameters
- $bot : Bot