Telegram Bot Api Bundle Laravel Package

Getting Started

• Install via Composer and check the package’s composer.json constraints first: this release targets Symfony 6.4 and explicitly does not support Symfony 7.0 yet (blocked by irazasyed/telegram-bot-sdk and illuminate/support requirement bumps).
• Confirm your app’s Laravel/Illuminate version is compatible with the package’s illuminate/support constraint before upgrading. If you’re on Symfony 7 components, pin this package to the previous release or wait for the upstream bumps.
• Publish any package config (php artisan vendor:publish --provider=...) and set the bot token/credentials in .env.
• First use case: register a bot command and invoke it from the CLI. This release migrates from the deprecated $defaultName property to the #[AsCommand] attribute, so inspect any existing command classes and align them with the new attribute style.

Implementation Patterns

• Service container integration: Bind the bot client/manager in a service provider and inject it into commands, jobs, and listeners rather than resolving it ad hoc. This keeps configuration (token, HTTP client, webhook settings) centralized.
• Console commands: Define commands with #[AsCommand(name: 'bot:...', description: '...')]. The attribute is now the canonical way to declare command names; keep command classes small and delegate business logic to services.
• Webhook controller pattern: Expose a route/controller that receives Telegram updates, validates the secret token, and dispatches handling to a service or queued job. Keep the controller thin.
• Queued processing: For long-running handlers or outbound messages, dispatch jobs instead of doing work inline in the webhook request. This plays well with Laravel queues and avoids Telegram timeouts.
• Event/listener hooks: If the package dispatches update events, subscribe listeners for routing messages to handlers (commands, conversations, fallbacks) instead of hard-coding conditions in one controller.
• Testing: Fake the HTTP client (Http::fake()) and assert outgoing Telegram API calls. For command tests, use Laravel’s command tester and assert the AsCommand name resolves correctly.

Gotchas and Tips

• Symfony 7 is temporarily unsupported. Don’t force symfony/*:^7.0 alongside this release. If Composer resolves Symfony 7 transitively, constrain to ^6.4 until the upstream packages (irazasyed/telegram-bot-sdk, illuminate/support) publish compatible requirements.
• $defaultName is deprecated. Any custom command still using protected static $defaultName should move to #[AsCommand]. Watch for duplicate or missing command registration after the migration, and clear the config/route/command cache (php artisan optimize:clear) when testing.
• Attribute availability: #[AsCommand] requires a modern Symfony console version. On Symfony 6.4 this is fine, but if you support older Laravel/Symfony combinations in the same codebase, verify the attribute is actually read by the console kernel.
• Config caching: Bot tokens and webhook secrets read via env() directly in package config can break under config:cache. Ensure config files use env() only at the config layer and access values via config() elsewhere.
• Webhook security: Always validate the X-Telegram-Bot-Api-Secret-Token header (or your configured secret) and return 200 quickly; retry storms from Telegram are common when handlers are slow or error.
• Rate limits and retries: Telegram enforces per-chat limits. Wrap outbound sends with backoff/retry logic and log 429 responses with retry_after.
• Debugging: Log raw update payloads at debug level, but redact tokens and user identifiers. Use Laravel’s HTTP client events or middleware to inspect outbound API calls.
• Extension points: Prefer decorating the package’s client/manager or binding your own implementation in the container over editing vendor code; this keeps upgrades to future Symfony 7-compatible releases straightforward.