Download the PHP package vzgcoders/telegramphp without Composer

TelegramPHP

An async ReactPHP framework for the Telegram Bot API, built the way DiscordPHP is built: a non-blocking HTTP transport, an event-emitting client, hydrated "parts" for every API object, and repositories that cache what the bot has seen.

The API surface is generated from the Bot API specification. spec/openapi.json — an OpenAPI 3.1 document built from PaulSonOfLars/telegram-bot-api-spec, which is scraped from the official documentation — is the single input to the code generator, and the test suite reads the same document to prove that every method and every one of its fields is reachable from PHP.

Bot API 10.3 · 185 methods · 400 types.

Documentation

• Guide — getting started, calling the API, updates and events, parts, keyboards and files, commands, webhooks, error handling, and how the generated code works.
• API reference — every class, generated from the source by phpDocumentor.

Both are published to GitHub Pages on release, and can be built locally with composer docs.

Requirements

• PHP 8.4 or newer
• ext-json, ext-mbstring

Installation

Windows and SSL

A Windows PHP build usually ships without a CA bundle, so TLS to api.telegram.org fails. Point the socket connector at one:

Running the examples

examples/bootstrap.php reads that .env and finds a CA bundle for Windows PHP builds; the environment wins over the file, so TELEGRAM_TOKEN=… php examples/ping.php works too. The library itself reads no configuration and needs no dotenv package — everything is passed to the constructor.

Getting started

run() identifies the bot with getMe, starts long polling, and runs the event loop. Pass false to keep the loop under your own control when the bot shares it with other services.

Calling the API

Every Bot API method is a real method on the client, named exactly as Telegram names it, taking exactly the fields Telegram documents. Required fields are positional; everything else is a named argument:

Calls resolve with the result already hydrated: a Message part, a Collection of Update parts, a bool. They reject with a typed exception when Telegram says no.

A method this build has never heard of — a newer Bot API server, or a local one with an extension — is still reachable:

Updates

Each update is emitted twice: once as Event::UPDATE carrying the whole Update, and once under its own type carrying just that payload. The type constants are generated from the Update object, so they are exactly the 27 types this Bot API version defines, and the same strings go in allowed_updates.

Webhooks

Give the client a webhook option and it listens instead of polling. Telegram requires HTTPS on the public endpoint, so in practice this sits behind a reverse proxy that terminates TLS; the secret_token is what separates a real delivery from anyone else who finds the URL.

Parts

Every Bot API object is a part: array and property access, nested objects hydrated into parts, Array of X into a Collection, timestamps into CarbonImmutable, and JSON serialisation back to exactly what Telegram sent.

Parts also carry behaviour, so the ids come off the object rather than out of your variables:

Union types (ChatMember, InputMedia, ReactionType, …) resolve to the right member on the way in, so a getChatMember answer arrives as a ChatMemberAdministrator, not a bag of attributes. A member Telegram adds after this build was generated falls back to the closest match rather than failing the update.

Keyboards and uploads

Pass an InputFile anywhere the API accepts InputFile or String and the request becomes a multipart/form-data upload — including files nested inside an InputMedia, which are rewritten to attach:// references for you. A file_id or an HTTP URL needs none of that; pass the string.

Downloads go the other way:

A local Bot API server

Telegram's servers cap downloads at 20 MB and uploads at 50 MB. A local Bot API server — telegram-bot-api, run with --local — lifts both (uploads up to 2000 MB) by working with files on its own disk: getFile answers with an absolute path there instead of a download link, and an upload can name a file there instead of sending it.

Point base_url at the server, and local_files at where its files are as this process sees them:

Then nothing else changes for downloads. downloadFile() and File::download() read the file from disk rather than over HTTP, and File::save() copies it without holding it in memory — which is the point, at these sizes. For a file too big to want as a string at all, ask for its path:

To upload a file the server can see without sending its bytes, pass its file:// URI:

Only files under local_files are ever read or offered. The path comes from the server, and a client that followed wherever it pointed would read any file this process can open.

Switching a bot over. Call $telegram->logOut() once against Telegram's own server before the first request to a local one; otherwise Telegram does not guarantee the bot receives its updates there. After that the bot cannot log back in to Telegram's server for ten minutes. Moving between two local servers, call close() on the old one first.

Commands

TelegramCommandClient is a client that routes slash commands — the counterpart of DiscordPHP's DiscordCommandClient. A callback that returns a string has it sent back as a reply, and the listed commands are published with setMyCommands when the bot is ready, so they appear in the command menu.

/command@yourbot is accepted as well as /command, which is how commands are addressed in groups, and a command aimed at another bot is ignored. /help is built in; pass help_command => null to turn it off, or prefix => '!' to answer to something other than a slash.

Caches

$telegram->chats and $telegram->users hold what updates have brought in. The Bot API has no list endpoints, so these are caches, not queries — a chat can be refreshed with getChat, while a user can only be looked up through a chat you share with them.

Errors

Failed calls reject with a subclass of Telegram\Http\Exceptions\HttpException chosen by the error code, carrying what Telegram said:

A 429 is held for exactly the retry_after Telegram asks for and then replayed; transient 5xx and transport failures back off and retry. Only what is still failing afterwards reaches you.

Configuration

Development

The library is generated from the spec, so a new Bot API version is a regeneration rather than a rewrite:

composer spec:build runs three steps, each usable on its own — spec:fetch, spec:openapi, spec:generate. Regenerating overwrites src/Telegram/Parts/*, src/Telegram/Api/*, Http/Endpoint.php and Events/Event.php wholesale, so hand-written behaviour lives in src/Telegram/Parts/Concerns/<Type>Behaviour.php — a trait the generator mixes into the matching part when the file exists.

The suite is mostly generated too: every method is checked for a PHP method with the documented parameters and types, then called with every field the spec lists to prove that each one reaches the request, and every type is hydrated from a synthetic payload and serialised back. If Telegram adds a method or a field and nobody regenerates, the tests say so.

composer docs builds with discord-php/phpdoc-tool — phpDocumentor carrying the DiscordPHP family's patches for ?T|null types, the same builder DiscordPHP and TwitchPHP use. It is not on Packagist, so install it from its repository:

An existing checkout works too — PHPDOC=../phpdoc-tool/vendor/bin/phpdoc composer docs. The site is published to GitHub Pages by .github/workflows/docs.yml on a release, on a manual dispatch, or on a push whose commit message contains build docs.

License

MIT. See LICENSE.