TelegramPHP Documentation

Http
in package
implements HttpInterface

FinalYes

Non-blocking transport for the Telegram Bot API.

Every call is a POST to /bot<token>/<method>, queued behind a concurrency ceiling, encoded as JSON - or as multipart/form-data the moment the payload carries an InputFile. A 429 is held for exactly the retry_after Telegram asks for and then replayed; transient 5xx and transport failures back off exponentially. Successful calls resolve with the result member of the envelope, already unwrapped.

Point $baseUrl at a local Bot API server to lift the official file-size limits.

Tags
link
https://core.telegram.org/bots/api#making-requests
author

Valithor Obsidion valithor@valgorithms.com

Table of Contents

Interfaces

HttpInterface
The contract {@see Http} fulfils. Depend on this rather than the concrete class so the transport can be decorated or faked (test doubles, alternative drivers, a local Bot API server).

Constants

BASE_URL  : mixed = 'https://api.telegram.org'
The official Bot API server.
CONCURRENT_REQUESTS  : mixed = 8
In-flight request ceiling.
MAX_ATTEMPTS  : mixed = 4
Give up after this many attempts at one request.
VERSION  : mixed = '1.0.0'

Properties

$baseUrl  : string
$driver  : ?DriverInterface
$inFlight  : int
$logger  : LoggerInterface
$loop  : LoopInterface
$queue  : SplQueue<string|int, Request>
$throttled  : bool
Set while the client is serving a `retry_after` hold-off.
$token  : string

Methods

__construct()  : mixed
create()  : self
Convenience constructor that wires the default ReactPHP driver against the shared event loop.
download()  : PromiseInterface<string|int, string>
Downloads a file previously located with `getFile`, resolving with its bytes.
execute()  : PromiseInterface<string|int, mixed>
Calls one Bot API method.
fileUrl()  : string
The absolute URL a `file_path` resolves to, token included.
methodUrl()  : string
The absolute URL one Bot API method is called at.
setDriver()  : void
setToken()  : void
Swap in a different bot token; queued requests pick it up.
decode()  : array<string, mixed>|null
encode()  : array{0: string, 1: array}
Chooses the wire format: JSON for ordinary calls, multipart the moment the payload carries a file.
handleRateLimit()  : void
Holds the whole queue for `retry_after` seconds, then replays the request - Telegram's limits are per bot, so racing ahead with other calls only earns more 429s.
handleResponse()  : void
pump()  : void
Dispatches queued requests up to the concurrency ceiling.
retry()  : void
send()  : void

Constants

BASE_URL

The official Bot API server.

public mixed BASE_URL = 'https://api.telegram.org'

CONCURRENT_REQUESTS

In-flight request ceiling.

public mixed CONCURRENT_REQUESTS = 8

MAX_ATTEMPTS

Give up after this many attempts at one request.

public mixed MAX_ATTEMPTS = 4

VERSION

public mixed VERSION = '1.0.0'

Properties

$baseUrl read-only

private string $baseUrl = self::BASE_URL

$inFlight

private int $inFlight = 0

$logger

private LoggerInterface $logger

$loop read-only

private LoopInterface $loop

$throttled

Set while the client is serving a `retry_after` hold-off.

private bool $throttled = false

$token

private string $token

Methods

__construct()

public __construct(string $token, LoopInterface $loop[, ?LoggerInterface $logger = null ][, ?DriverInterface $driver = null ][, string $baseUrl = self::BASE_URL ]) : mixed
Parameters
$token : string
$loop : LoopInterface
$logger : ?LoggerInterface = null
$driver : ?DriverInterface = null
$baseUrl : string = self::BASE_URL

create()

Convenience constructor that wires the default ReactPHP driver against the shared event loop.

public static create(string $token[, ?LoggerInterface $logger = null ][, ?LoopInterface $loop = null ][, array<string, mixed> $socketOptions = [] ][, string $baseUrl = self::BASE_URL ]) : self
Parameters
$token : string
$logger : ?LoggerInterface = null
$loop : ?LoopInterface = null
$socketOptions : array<string, mixed> = []

Forwarded to the socket connector.

$baseUrl : string = self::BASE_URL
Return values
self

download()

Downloads a file previously located with `getFile`, resolving with its bytes.

public download(string $filePath) : PromiseInterface<string|int, string>
Parameters
$filePath : string

The file_path from a File.

Return values
PromiseInterface<string|int, string>

execute()

Calls one Bot API method.

public execute(string $method[, array<string, mixed> $content = [] ]) : PromiseInterface<string|int, mixed>
Parameters
$method : string
$content : array<string, mixed> = []
Return values
PromiseInterface<string|int, mixed>

fileUrl()

The absolute URL a `file_path` resolves to, token included.

public fileUrl(string $filePath) : string
Parameters
$filePath : string
Return values
string

methodUrl()

The absolute URL one Bot API method is called at.

public methodUrl(string $method) : string
Parameters
$method : string
Return values
string

setToken()

Swap in a different bot token; queued requests pick it up.

public setToken(string $token) : void
Parameters
$token : string

decode()

private decode(string $body) : array<string, mixed>|null
Parameters
$body : string
Return values
array<string, mixed>|null

encode()

Chooses the wire format: JSON for ordinary calls, multipart the moment the payload carries a file.

private encode(array<string, mixed> $content) : array{0: string, 1: array}
Parameters
$content : array<string, mixed>
Tags
throws
JsonException
Return values
array{0: string, 1: array}

handleRateLimit()

Holds the whole queue for `retry_after` seconds, then replays the request - Telegram's limits are per bot, so racing ahead with other calls only earns more 429s.

private handleRateLimit(Request $request, ResponseInterface $response, array<string, mixed>|null $decoded) : void
Parameters
$request : Request
$response : ResponseInterface
$decoded : array<string, mixed>|null

handleResponse()

private handleResponse(Request $request, ResponseInterface $response) : void
Parameters
$request : Request
$response : ResponseInterface

pump()

Dispatches queued requests up to the concurrency ceiling.

private pump() : void

retry()

private retry(Request $request, float $delay) : void
Parameters
$request : Request
$delay : float
On this page

Search results