Telegram Bot Laravel Package

Technical Evaluation

Architecture fit. This is a framework-agnostic, long-running PHP bot framework rather than an HTTP micro-library: it ships a dispatcher loop, a command registry (system commands, custom commands, admin commands), conversation state, and optional database-backed persistence for chats/users/updates. That is a good fit if the product is a conversational bot with a real command surface (dozens of commands, admin tooling, stateful flows). It is a poor fit if you only need to fire transactional notifications into Telegram — you would be importing a framework to make one API call. Laravel's HTTP client plus a thin TelegramClient wrapper is cheaper for send-only use cases.

Integration feasibility. Composer-installable, PHP 8.x-capable, MIT, active enough to have a 2024-06 release and ~4k stars. Two material caveats for a TPM: (1) package identity mismatch — the record names nicoosh/telegram-bot while the repository resolves to php-telegram-bot/core; before adoption we must confirm whether this is a fork, a mirror, or a stale registry alias, and decide whether to depend on the upstream vendor name directly. Fork drift is a supply-chain and upgrade-path risk, not a cosmetic one. (2) There is no first-class Laravel service provider here; container wiring, config publishing, and command registration are ours to build. The 0 dependents figure is likely a registry artifact for a PHP-only library, but it does mean we cannot lean on an ecosystem of known integrators.

Technical risk.

Key questions. Is our need stateful conversation or one-way notification? Who owns the fork decision and can we depend on the canonical vendor name? Do we accept polling (needs a supervised worker) or webhook (needs public ingress + secret)? What is our fallback if upstream stalls — vendor the code, or swap to a Laravel-native SDK?

Integration Approach

Stack fit. Reasonable for Laravel, with wiring work. The library's command classes can be resolved through Laravel's container, so bot commands can delegate to existing application services rather than reimplementing domain logic. Persistence is the friction point: the package expects its own tables (chats, users, updates), which either coexist with our schema or get mapped onto existing models via custom repositories.

Migration path. Do not retrofit the bot into an existing monolith request cycle. Stand up a dedicated bot process/container (or a single webhook route) that talks to the core application over its service layer or an internal API. That keeps the bot's long-running semantics and its failure domain separate from customer-facing HTTP traffic, and it means a swap of bot library does not touch business logic.

Compatibility. Verify PHP 8.2/8.3 support and the MySQL/Postgres driver actually exercised in tests before committing. Check that our queue driver and the library's update-processing loop do not both claim the same work — pick one ownership model for retries.

Sequencing.

1. Provenance check (1–2 days): diff nicoosh/telegram-bot against php-telegram-bot/core, confirm license and release lineage, decide canonical dependency.
2. Spike (1 week): one webhook endpoint on staging, secret-token validation, two commands, one outbound send through the queue. Prove deploy, logs, and rollback.
3. Abstraction layer: a thin BotGateway interface we own, so the library is an implementation detail and the Laravel-native SDK remains a viable swap.
4. Harden: rate-limit budget, idempotency on update IDs, secret rotation, admin surface disabled or behind SSO.
5. Production cutover behind a feature flag with a notification-only shadow mode first.

Operational Impact

Maintenance. Low-to-moderate code surface, but real ongoing cost: dependency bumps, Bot API compatibility reviews each release cycle, and the fork-ownership question. Budget roughly a day per quarter, more if we fork. Pin to an exact minor version and upgrade deliberately — Telegram Bot API changes occasionally alter payload shapes.

Support. No commercial support; GitHub issues and community channels only. Establish an internal owner (one backend engineer) and document the escalation path. If the bot becomes customer-facing and revenue-adjacent, the absence of an SLA is itself a risk to accept explicitly.

Scaling. Webhook mode scales horizontally behind a load balancer with a shared queue; polling mode scales to exactly one worker (or requires sharding by bot token). Either way, outbound sends must go through a queue with per-chat throttling — direct sends from the request path will hit 429s under load and produce silent message loss. Telegram's own retry semantics (non-2xx triggers redelivery) mean handlers must be idempotent on update_id.

Failure modes. Webhook endpoint down → Telegram retries then drops, with no replay after the window; worker death under polling → bot silently goes deaf (needs a heartbeat alert, not just a process check); token revocation or a leaked token → full account takeover of the bot (store in a secrets manager, rotate); DB outage → command dispatcher fails closed, which is acceptable but must not cascade into the main app; unhandled exceptions in a command → user sees nothing, so per-command error reporting to the user plus structured logging is mandatory.

Ramp-up. One mid-level PHP engineer familiar with Laravel should reach productive velocity in 3–5 days; the library's conventions (command classes, conversation state) are learnable from examples. The slower part is operational literacy — webhook vs polling tradeoffs, Telegram rate limits, and secret handling — which is where review effort should concentrate.

TPM verdict. Adopt for a genuine command-driven bot where a dedicated process is acceptable; treat the package-identity mismatch and webhook security as gating items, wrap the library behind an interface we own, and keep a Laravel-native SDK as a documented exit. For notification-only use, skip it and write the 150-line client.