PHPackages merezarezaei/teleproto - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. merezarezaei/teleproto ActiveLibrary merezarezaei/teleproto ====================== Almost-zero-friction Telegram for Laravel & PHP — MTProto 2.0, Bot API, Mini App auth, Passport KYC v1.0.0(today)01↑2900%MITPHPPHP >=8.2CI passing Since Aug 28Pushed todayCompare [ Source](https://github.com/MeRezaRezaei/teleproto)[ Packagist](https://packagist.org/packages/merezarezaei/teleproto)[ Docs](https://github.com/MeRezaRezaei/teleproto)[ RSS](/packages/merezarezaei-teleproto/feed)WikiDiscussions main Synced today READMEChangelogDependencies (12)Versions (3)Used By (0) Teleproto ⚡ =========== [](#teleproto-) **Telegram power with almost zero friction — for PHP & Laravel.** [![GitHub Workflow Status](https://camo.githubusercontent.com/acd35b740f7a595e949034920f4bfaadf61d5ccee3a4bba29084d608a8d4a604/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f4d6552657a6152657a6165692f74656c6570726f746f2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/MeRezaRezaei/teleproto/actions)[![PHP Version](https://camo.githubusercontent.com/96efc47b2f31bb102c209d3526fec122ee4df587ce80db9534164435ab0dab1d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344253230382e322d3838393242462e7376673f7374796c653d666c61742d737175617265)](https://php.net/)[![License](https://camo.githubusercontent.com/942e017bf0672002dd32a857c95d66f28c5900ab541838c6c664442516309c8a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![Latest Version](https://camo.githubusercontent.com/512566124bdd13b0b8862ffa148f073d6b260643e8ef8967afa5d6e5dbd158aa/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6572657a6172657a6165692f74656c6570726f746f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/merezarezaei/teleproto) --- You need to send a message, verify a Mini App, decrypt Passport KYC, run a bot, fetch a file — **occasionally**, inside a Laravel app that is about something else. You should not have to adopt a Telegram framework to do it. - **One composer package, not a framework.** Native MTProto 2.0, Bot API (HTTP), Mini App HMAC auth, Passport KYC decryption, and Storage-backed file streaming — no event loop, no daemon, no IPC. - **Stateless session strings.** Auth lives in a portable base64 string (`.env` or your DB). No session files, no SQLite, no disk locks. The handshake happened once, ever — it is inside the session string. - **Typed errors and AI-shaped docs.** Every RPC error resolves to a typed exception carrying Telegram's official error-database hint, and the `skills/` directory gives AI agents a per-method reference they can drive the package from. --- The friction we remove ---------------------- [](#the-friction-we-remove) **teleproto**MadelineProtoTDLib**Footprint**One composer packageFull amphp-based frameworkNative C++ library + bindings**Session model**Stateless string in `.env`/DBSession files on diskOwn local database**Daemon / event loop**None — plain blocking callsamphp event loopTDLib client process**Learning curve**Facade + `.env`Event loop, wrappers, IPCAuth state machine, build steps**Login wizard**`php artisan teleproto:login` (phone / QR / 2FA / bot)Multi-step manual setupImplement the flows yourself**AI-skill docs**Generated per-method reference files——If you are building a Telegram *client*, MadelineProto and TDLib are the right tools. If you need Telegram call X from your Laravel app tonight, that is the gap teleproto fills. --- What you can do today --------------------- [](#what-you-can-do-today) ### Bot on the HTTP Bot API [](#bot-on-the-http-bot-api) ``` use MeRezaRezaei\Teleproto\Facades\TP; TP::bot()->sendMessage('@channel', 'Hello from Teleproto!'); ``` ### Bot or user over native MTProto 2.0 [](#bot-or-user-over-native-mtproto-20) Binary TCP RPC (Layer 227). Warm calls are a single socket round-trip; file uploads go up to 4 GB. ``` // Bot over MTProto (auth.importBotAuthorization under the hood): $bot = TP::botMtproto(); $bot->login(); $bot->sendMessage(peer: '@channel', text: 'Bot broadcast over MTProto'); // User account over MTProto: $user = TP::user(); $user->sendMessage('@username', 'Hello from a user account!'); ``` ### Mini App auth middleware [](#mini-app-auth-middleware) Cryptographic HMAC-SHA256 verification of Telegram `initData`, as one route middleware: ``` // routes/api.php Route::middleware('tg.miniapp')->group(function () { Route::post('/miniapp/me', function (Request $request) { return response()->json($request->attributes->get('telegram_user')); }); }); ``` ### Passport KYC decryption [](#passport-kyc-decryption) ``` use MeRezaRezaei\Teleproto\Passport\PassportDecryptor; $creds = PassportDecryptor::decryptCredentials( encryptedData: $payload['data'], encryptedSecret: $payload['secret'], privateKeyPem: file_get_contents(storage_path('keys/passport_private.pem')), hash: $payload['hash'], ); $firstName = $creds['personal_details']['first_name']; ``` ### Stream large files straight from Laravel Storage [](#stream-large-files-straight-from-laravel-storage) 512 KB MTProto parts, chunk-by-chunk from any Storage disk (`local`, `s3`, `minio`) — never load the file in memory: ``` use MeRezaRezaei\Teleproto\Facades\TP; use MeRezaRezaei\Teleproto\Media\StorageMedia; $user = TP::user(); $fileId = random_int(1, PHP_INT_MAX); foreach (StorageMedia::readFromDisk('media/large_video.mp4', disk: 's3') as $part) { $user->call('upload.saveBigFilePart', [ 'file_id' => $fileId, 'file_part' => $part['part_index'], 'file_total_parts' => $part['total_parts'], 'bytes' => $part['bytes'], ]); } ``` ### Login wizard: phone / QR / 2FA / bot [](#login-wizard-phone--qr--2fa--bot) ``` php artisan teleproto:login # phone + code, 2FA SRP handled automatically — or pick QR php artisan teleproto:login --qr # scan the terminal QR from Telegram -> Settings -> Devices ``` Sessions land in `.env` as `TELEGRAM_USER_SESSION` / `TELEGRAM_BOT_SESSION`. After that, `TP::user()` and `TP::botMtproto()` take **zero parameters**. ### Typed errors with official hints [](#typed-errors-with-official-hints) Every RPC failure resolves through the packaged catalog of Telegram's official error database (Layer 227) into a typed exception with a doc-backed hint: ``` use MeRezaRezaei\Teleproto\Exceptions\FloodWaitException; try { TP::user()->sendMessage('@channel', 'hello'); } catch (FloodWaitException $e) { logger()->warning("Flood: retry in {$e->seconds}s — {$e->docHint}"); } ``` ### Session strings, not session files [](#session-strings-not-session-files) ``` $sessionString = TP::user()->session->exportString(); // Store encrypted in MySQL/PostgreSQL/Redis: $userModel->update(['telegram_session' => Crypt::encryptString($sessionString)]); // Restore anywhere, in one line: $user = TP::fromSession(Crypt::decryptString($userModel->telegram_session)); ``` --- Zero-friction install --------------------- [](#zero-friction-install) ``` composer require merezarezaei/teleproto php artisan vendor:publish --tag="teleproto-config" ``` ``` # Bot API (HTTP) — optional if you only use MTProto TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" # MTProto 2.0 (required for user + bot binary sessions) # Get yours at https://my.telegram.org (API development tools) TELEGRAM_API_ID=12345678 TELEGRAM_API_HASH="your_api_hash_here" # Written automatically by the login wizard: TELEGRAM_USER_SESSION="2:AQAD...:12345678:0" TELEGRAM_BOT_SESSION="2:AQAD...:98765432:0" ``` Then log in once: `php artisan teleproto:login`. That is the only setup for MTProto user (and binary-bot) sessions — HTTP Bot API users need nothing but the bot token. > **Note:** In a Laravel app use `php artisan teleproto:login`. The wizard also ships as `vendor/bin/teleproto login` (in a repo clone: `./bin/teleproto login`). --- Tradeoffs — and why they are deliberate --------------------------------------- [](#tradeoffs--and-why-they-are-deliberate) - **Blocking wire, batched where it counts.** No Fibers, no event loop: `call()` (encrypt → send → read) keeps the engine small and stateless, and `callMany()` ships N independent requests in ONE round-trip via `msg_container` batching — live-measured on production DC4 at 2.3–2.7× vs sequential ([docs/scaling.md](docs/scaling.md)). - **No update-handler framework.** Updates arrive as Laravel events (`TelegramUpdateReceived`) and through the one-method `UpdateSinkInterface` contract — your pipeline (Redis Stream, queue, Spatie models) plugs in at that seam. Building opinionated handlers on top is deliberately left to higher layers. - **Full schema registry, curated fluent builders.** Every schema method is callable *today* via `call('method.name', [...])`; generated fluent builders (`Methods::auth()->signIn()->…`) are added from a curated list validated against the schema artifacts. - **No proxy tunneling yet.** `setProxy()` accepts config, but connections are currently direct — tracked in the transport layer. Details and the ranked roadmap: [docs/scaling.md](docs/scaling.md) · [Core design spec](docs/superpowers/specs/2026-08-27-teleproto-core-design.md). --- Going faster ------------ [](#going-faster) The DH handshake happened once, ever — it is baked into the session string — so a cold start is just connect + salt (~49 ms measured), and a warm call is one socket round-trip (< 5 ms). For N independent calls, `callMany()` puts them all in one round-trip (N-in-1-RTT, live-measured 2.3–2.7× on production DC4). Three patterns: - **Plain FPM** — completely fine for occasional calls per request. - **One queue worker per account** — Horizon/queue fan-out is the supported multi-account model. - **Octane** — keeps workers (and sockets) warm between requests. Full scaling guide, Horizon config, and honest load limits: [docs/scaling.md](docs/scaling.md). --- AI-friendly by design --------------------- [](#ai-friendly-by-design) The [`skills/telegram-methods/`](skills/telegram-methods/) directory is a generated, per-method reference — parameter tables, return types, every official error with Telegram's own hint, and copy-paste usage: ``` use MeRezaRezaei\Teleproto\Methods\Methods; $request = Methods::auth()->signIn() ->phoneNumber('+15551234567') ->phoneCodeHash($hash) ->phoneCode($code) ->toRequest(); $result = app(\MeRezaRezaei\Teleproto\Services\TeleprotoClient::class)->dispatch($request); ``` The same information is indexed for agent crawlers in [`llms.txt`](llms.txt). Both are generated from the packaged schema artifacts — regenerate with `php bin/generate-skill-files.php`. --- Documentation ------------- [](#documentation) - [Changelog & Release Notes](CHANGELOG.md) - [Quickstart: Install → First Call](docs/quickstart.md) - [Docs Index](docs/index.md) - [User MTProto Client Guide](docs/user-client.md) - [Bot API Client Guide](docs/bot-client.md) - [Telegram Passport KYC Guide](docs/telegram-passport.md) - [Scaling: Multiple Accounts & Load Limits](docs/scaling.md) - [Core Engine Design Spec](docs/superpowers/specs/2026-08-27-teleproto-core-design.md) Testing ------- [](#testing) ``` composer test ``` Contributing ------------ [](#contributing) Please see [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) for details. License ------- [](#license) Teleproto is open-sourced software licensed under the [MIT license](LICENSE). ### Health Score 41 — FairBetter than 87% of packages Maintenance100 Actively maintained with recent releases Popularity2 Limited adoption so far Community6 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 0d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/77894240?v=4)[Reza Rezaei](/maintainers/MeRezaRezaei)[@MeRezaRezaei](https://github.com/MeRezaRezaei) --- Top Contributors [![openhands-agent](https://avatars.githubusercontent.com/u/175740463?v=4)](https://github.com/openhands-agent "openhands-agent (90 commits)") --- Tags phplaravelpassportsessionbottelegrambot apitelegram botmtprotokyctelegram-clientmini-appqr-login ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/merezarezaei-teleproto/health.svg) ``` [![Health](https://phpackages.com/badges/merezarezaei-teleproto/health.svg)](https://phpackages.com/packages/merezarezaei-teleproto) ``` ### Alternatives [laravel/ai The official AI SDK for Laravel. 1.1k4.6M343](/packages/laravel-ai)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9922.4M148](/packages/roots-acorn)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 80427.1M252](/packages/laravel-mcp)[psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel)[laravel/cashier Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services. 2.5k31.8M163](/packages/laravel-cashier)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 265.2k](/packages/aedart-athenaeum) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)