Telegram Bot Cast Laravel Laravel Package

Getting Started

• Install and wire up: composer require appto-dev/telegram-bot-cast-laravel, then publish the package config/views with php artisan vendor:publish (pick the provider tag shown by php artisan vendor:publish --list — the package exposes a service provider that registers the client, facade alias, and config file). Add your bot credentials to .env (typically a TELEGRAM_BOT_TOKEN entry) and never commit the token.
• Look here first: the published config/telegram-bot-cast.php (or similarly named file) is the source of truth for token, base API URL, timeouts, and default chat/channel IDs. Next, check the service provider's bindings — that tells you which contract to type-hint for dependency injection and which facade to use for quick calls.
• Confirm version alignment: this release (3.2.10.3) is a bot-generated sync to Telegram Bot API 10.3. Check composer.json for the supported PHP/Laravel ranges, and note the version suffix tracks the upstream Bot API — not a package-specific patch level.
• First use case: send a test message from php artisan tinker (or a throwaway route) using the facade/default client to a private chat with your bot. This validates token, network egress, and config caching in one step before you build notifications or webhooks on top.
• Then pick your ingress model: either register a webhook route for inbound updates or run long polling for local development — start with polling locally, switch to a webhook in staging/production.

Implementation Patterns

• Inject the contract, not the facade: type-hint the package's client contract in constructors/actions so it can be swapped or mocked in tests; reserve the facade for one-off scripts and Artisan commands.
• Queue outbound sends: wrap message sends in jobs (ShouldQueue) rather than calling the API inline from HTTP requests. This keeps request latency low and gives you a natural place to add rate-limit backoff and retries (retry_after on 429s).
• Named connections for multi-bot setups: if the config supports multiple bots/tokens, treat each as a named connection and resolve per-tenant rather than mutating a global token at runtime — global mutation breaks under Octane and queued workers.
• Notifications integration: use it as the transport behind a Laravel notification channel when you want framework-native via() routing, or call the client directly from a notification's toTelegram() method if the channel isn't provided. Keep message formatting (Markdown/HTML) in a dedicated formatter class so escaping is centralized.
• Webhook controller: register a single POST route outside the web middleware group (no CSRF/session), verify the X-Telegram-Bot-Api-Secret-Token header against config, and dispatch an event/job per update. Return 200 fast; do the work asynchronously.
• Idempotency: store update_id (or message ID for edits) in a cache/DB unique index so retried webhook deliveries don't double-send.
• Testing: use Http::fake() to assert outgoing payloads, and fake the client contract for unit tests. Keep one or two integration smoke tests against a private test bot gated behind an env flag so you catch real API drift without slowing CI.
• Pin and upgrade deliberately: since tags track Bot API releases, constrain the package version in composer.json and read the changelog before bumping minor versions — payload shapes for new media/types can change between Bot API syncs.

Gotchas and Tips

• Bot-generated release notes: entries like [BOT] API 10.3 | release 3.2.10.3 mean an automated API-sync PR, not a curated bugfix. Treat the bump as "new upstream Bot API surface" and diff the actual commits if you depend on a specific method's payload shape.
• Webhook vs polling is exclusive: you cannot have both active for the same bot. setWebhook persists on Telegram's side — remember to deleteWebhook before switching back to polling locally, or you'll spend an hour debugging "no updates received."
• Rate limits and 429s: Telegram enforces roughly 30 messages/second globally and ~1/second per chat. Implement exponential backoff honoring parameters.retry_after; don't blindly retry Retry-After-less failures.
• Config caching: after php artisan config:cache, any runtime config()->set() trick for tokens is ignored. Use env vars plus named connections instead of mutating config at runtime.
• File handling: distinguish file_id reuse from fresh uploads; Bot API caps uploads (~50 MB send / ~20 MB download) and streaming large files through PHP will blow memory limits — prefer URLs or pre-uploaded file_ids.
• Parse mode escaping: Markdown/HTML parse errors are silent-ish (400 Bad Request: can't parse entities). Escape user-supplied text or send as plain text; log the raw response body, not just the status code.
• Token leakage: the base URL contains the token (/bot<token>/method). Ensure your HTTP client logging / Laravel Telescope / exception handlers redact it, and never echo the resolved base URL in error messages.
• Queue workers on deploy: long-running workers cache the container and config — php artisan queue:restart after deploying a package or config change, especially with Octane.
• Extension points: prefer decorating the client contract or listening to package events over forking. If you need custom endpoints (new Bot API 10.3 methods not yet wrapped), most clients expose a generic call(method, payload) escape hatch — use it and file an issue upstream rather than patching vendor code.