Laragram Laravel Package

Getting Started

LaraGram is a Laravel-native framework for building Telegram bots: you get config-driven bot setup, an update dispatcher, handler/command classes, and a runtime that can either poll Telegram or receive webhooks. v4.3.0 is the first release with a formal runtime-driver abstraction (native, Surge, RoadRunner, FrankenPHP) and a built-in image driver, so treat 4.3 as the baseline for new projects.

Minimal path:

1. composer require laraxgram/laragram — this meta-package is now a thin aggregator over the split components, so confirm which laraxgram/* sub-packages it pulled in (composer show | grep laraxgram).
2. Publish the config: php artisan vendor:publish --tag=laragram-config (check config/laragram.php for the token, webhook, runner and image blocks).
3. Add LARAGRAM_BOT_TOKEN= to .env. Do not commit it; per-environment tokens (dev bot vs prod bot).
4. Register your handlers/commands in the bot kernel or via the laragram route/handler file the package provides.
5. Run in long-polling locally (php artisan laragram:poll or equivalent), webhook in production.

Where to look first, in order: the published config file (it documents the runner + image driver options added in 4.3), the bot kernel/entry class, then the split component READMEs for the feature you actually need. Because components are now separate packages, the config file is the fastest map of what is bundled versus what you must install explicitly.

First use case: a /start command that replies with a text message, wired to a single handler class. Get that round-tripping over long polling before you touch webhooks or runtime drivers — it isolates token/permission problems from infrastructure problems.

Implementation Patterns

Handler-per-command, not a switch statement. Put each command in its own class and let the dispatcher resolve it. Updating a command then means touching one file, and the handler becomes trivially unit-testable by constructing it with a fake update.

Keep the runtime swappable. Since 4.3, the runner is a config concern rather than an application concern: native (php-fpm/built-in server) for simple webhook deployments, frankenphp or roadrunner for persistent workers, surge if you are already on that stack. Write your handlers so they never assume a request lifecycle — no $_SERVER reads, no reliance on request() in a worker context. This is what makes moving from native to RoadRunner/FrankenPHP a config change instead of a rewrite.

Long polling in dev, webhook in prod. Local: polling loop, no public URL, no TLS. Production: webhook route registered with setWebhook, secret token header validated. Keep both paths behind the same handler layer so staging and prod behave identically.

Image work through the driver, not raw GD/Imagick calls. The 4.3 native image driver means image manipulation (resizing photos before sendPhoto, generating thumbnails, watermarking) goes through a configured driver. Set it explicitly in config rather than letting auto-detection decide — production boxes often have GD but not Imagick, and the difference is only visible at runtime.

Queue anything that touches the network. Handler execution happens inside Telegram's webhook timeout expectations. Sending N media messages inline will burn through it. Dispatch a job per outbound batch, and use the package's rate-limit awareness rather than sleep().

Test against a faked API client. Assert the outgoing payload (method name + params) rather than hitting Telegram. Keep a small set of recorded update fixtures (message, callback query, edited message, channel post) and feed them to the dispatcher directly.

Multi-bot setups. If you run several bots, scope config per bot and avoid global singletons holding a token; the meta-package split in 4.3 makes it easier to instantiate independent bot instances from the sub-packages.

Gotchas and Tips

• The component split is the real upgrade risk. v4.3 "split all laragram components" means the package you used to require may now be a shell that depends on laraxgram/* packages. Symptoms after upgrading: classes suddenly missing, Class not found on handlers, or two versions of a component installed. Fix with composer update "laraxgram/*" --with-dependencies and check composer show for version drift between the meta-package and sub-packages. Pin exact versions in CI.
• "Fix dependencies" can move your floor. Re-read composer.json after upgrading — a bumped PHP or framework constraint is the usual cause of "works locally, fails in CI". Run composer why-not laraxgram/laragram 4.3.0 if the update refuses to install.
• Runtime drivers leak state. Under Surge/RoadRunner/FrankenPHP your process is long-lived. Anything cached on a singleton (the current update, the resolved chat, a per-request container binding) will bleed into the next update. Reset per-update state in the dispatcher lifecycle hook, and never store the "current" update in a static.
• Webhook vs polling double-processing. If a webhook is still registered while you run the poller, updates get consumed and dropped silently. getWebhookInfo / deleteWebhook before polling. The reverse mistake — running the webhook route without the secret token check — is a security issue, not just a bug.
• Flood control is not optional. Telegram's 429 responses carry retry_after. Honour it; the package can retry, but retries without backoff will get you temporarily restricted. Watch for per-chat rate limits when broadcasting.
• File download limits. Bot API caps getFile downloads (20 MB at time of writing) — check size before attempting, and stream large files rather than buffering them in memory, especially on single-worker native runtimes.
• Image driver pitfalls. Verify the driver at boot, not on first use — an image request that fails three hours after deploy because Imagick is absent is a bad way to find out. Also confirm memory limits: resizing a large photo with GD will happily exceed a 128 MB memory_limit.
• Debugging outbound calls. Enable the package's debug logging, but redact the bot token from logs — it appears in request URLs for the Telegram API and copies of logs leak tokens easily. Rotate the token via BotFather immediately if it lands in a log aggregator.
• Extension points to prefer. Custom drivers (image or runtime) should be registered via config/container bindings rather than by editing vendor files — v4.3's driver abstraction is new and will keep shifting; config-level extension survives minor upgrades.
• Upgrade checklist for 4.2 → 4.3. Re-publish config and diff it (new runner/image keys almost certainly landed), clear config:cache, confirm the webhook or poll command you use still exists under the same name, then smoke-test one message, one photo, one callback query.