Core Laravel Package

Getting Started

Install the package and publish its config:

composer require laraxgram/core
php artisan vendor:publish --tag=laragram-config

Set the bot token in .env (LARAGRAM_BOT_TOKEN=...) and confirm the service provider is auto-discovered. First place to look is config/laragram.php — v4.5.0 adds several new config blocks (AWS, YAML, AI-SDK, API server binary), and the defaults are conservative enough to leave everything but the token disabled.

Your first use case should be a single webhook endpoint that answers /start. Register the route the package exposes (or point Telegram's setWebhook at your own controller that forwards the update into the bot kernel), then add one handler class for the command. Verify the round trip with php artisan laragram:webhook:info (or the equivalent status command) before touching any of the new integrations — get the token, webhook secret, and one reply working first, then layer on AI-SDK or Citadel.

Implementation Patterns

Webhook-first, queue the rest. The request lifecycle is synchronous; anything that calls an external service (AI-SDK completions, S3 uploads via the AWS manager) belongs in a job dispatched from the handler. This keeps Telegram's webhook timeout from biting you and makes retries free.

Handler-per-command. Keep command classes thin: parse the update, validate, dispatch, reply. Shared logic (formatting, keyboard builders, pagination) goes in small services rather than base classes — the bot kernel resolves handlers from the container, so constructor injection works normally.

FileBag for media. With the FileBag fix in this release, inbound documents/photos now populate predictably. Prefer $request->file('photo')-style access over manual message.photo[-1].file_id digging, and always download to a temporary path before handing off to the AWS manager so you're not streaming between two remote APIs.

Citadel for privileged commands. Use Citadel to gate admin/ops commands rather than hand-rolling a Telegram-ID allowlist. Register it as a middleware on the handler and keep the user↔Telegram-ID mapping in your own table, not in config — config changes require a redeploy and a cache clear.

YAML for flow definitions. With the first-party YAML parser, multi-step conversational flows are now reasonable to express declaratively: define states, prompts, and transitions in a YAML file and have a single generic handler walk the state machine. Keep the YAML schema versioned alongside the code and validate it at boot so a typo fails at deploy, not mid-conversation.

API Server Binary config is the switch for self-hosted Bot API servers (larger upload limits, local file access). Wire it into your deployment via environment variables rather than committing paths, and keep the binary outside the release directory so deployments don't clobber it.

AWS manager replaces ad-hoc S3 clients for media persistence; centralise bucket/prefix/CDN config there so handlers never construct credentials themselves.

Gotchas and Tips

• "First-party" means migration risk. The AWS manager, YAML parser, Citadel, and AI-SDK bindings were previously community or bespoke. If you already have your own S3 wrapper or YAML loading, expect class-name and config-key collisions — check for duplicate bindings after upgrading rather than assuming yours still wins.
• FileBag changes affect existing upload tests. The fix alters how files are collected; re-run any handler tests that assert on file presence, and check multi-file messages specifically, since that's where these bugs usually hid.
• Webhook secret and CSRF. The webhook route must be excluded from CSRF and any auth middleware. If you route through your own controller instead, remember Telegram retries failed deliveries — make handlers idempotent on update_id.
• Config caching. php artisan config:cache will freeze the new config blocks; anything you intend to vary per environment must be read through env() in the config file, not at runtime.
• AI-SDK is not a drop-in. It adds latency and cost per turn. Set an explicit timeout, a fallback reply, and a per-chat rate limit before shipping it to users; also store the conversation context yourself — don't rely on the SDK to persist it.
• API server binary path must be executable by the PHP-FPM user, and self-hosted servers require the token to be issued by that server. If webhooks stop working after enabling it, this mismatch is the first thing to check.
• YAML parsing edge cases. Tabs, unquoted on/off/yes booleans, and deeply nested anchors are the usual culprits. Lint flow files in CI and fail the build on schema errors.
• Pin the minor version ("laraxgram/core": "~4.5.0") until you've exercised the new integrations in staging — this release touches request handling and adds four subsystems at once, which is a lot of surface area for a single patch.