Bot State, SQLite, Files and Scheduled Work
A request is not a permanent process
Do not keep a user’s conversation state only in a PHP variable. Separate webhook requests and cron runs need shared persistent storage. Use a bot-local SQLite database or another explicitly configured store. A static variable can cache within a request but does not replace durable storage.
SQLite example
This snippet uses PHP PDO and needs no Telegram loader. chatId must come from a validated update or a configured target. Store chat IDs as text when combining numeric IDs and usernames.
$db = new PDO('sqlite:' . __DIR__ . '/database.db', null, null, [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);
$db->exec('PRAGMA journal_mode = WAL');
$db->exec('PRAGMA busy_timeout = 5000');
$db->exec('CREATE TABLE IF NOT EXISTS user_state (
chat_id TEXT PRIMARY KEY,
state TEXT NOT NULL,
updated_at INTEGER NOT NULL
)');
$stmt = $db->prepare('INSERT INTO user_state(chat_id, state, updated_at)
VALUES (?, ?, ?)
ON CONFLICT(chat_id) DO UPDATE SET state=excluded.state, updated_at=excluded.updated_at');
$stmt->execute([(string)$chatId, 'awaiting_name', time()]);
WAL allows concurrent readers but SQLite still has writer contention. Keep transactions short; do not wait for Telegram/network responses while holding a database write transaction. busy_timeout is a wait limit, not a guarantee against locks. Schedule schema migrations carefully and use prepared statements for user-controlled values.
Replay handling and duplicate work
Use update_id to recognize repeated Telegram deliveries, but do not mark an update permanently complete before its durable work succeeds. For payments, grants and other non-repeatable actions, store an operation key and state transition in a transaction. An outbound timeout can mean the operation completed but the response was lost. Blindly repeating it can duplicate side effects.
File identifiers are different
| Value | Use |
|---|---|
| file_id | Reuse/download through the same bot; preserve the original media type. |
| file_unique_id | Identify/deduplicate a file; not usable for sending or downloading. |
| file_path | Telegram remote path returned by getFile; not a local disk path. |
| local_path | Botlify download helper’s local filesystem result, possibly null. |
| custom_emoji_id | Custom emoji identifier; not interchangeable with a message effect ID. |
Keep file_id with bot identity, original filename and MIME type. An ID from another bot cannot simply be copied into the new bot’s media store. The native download helper returns local_path, direct_tg_url, url and file_name; check local_path before processing. A direct Telegram file URL contains credentials and must not be exposed.
Local uploads and cleanup
Use known paths under the bot workspace for local media. Do not turn user text into arbitrary filesystem paths. Multipart albums use attach:// references to top-level CURLFile values. Clean up only files created for your task; do not delete a shared database or another task’s output. See the media and file recipes for complete examples.
Cron work and locking
A cron task should finish after its bounded work. Avoid an endless loop. Where overlapping runs would duplicate work, use a lock and durable progress records. PHP file locks coordinate cooperating processes; they are not an operation ledger. A normal PHP cron does not need tg_all_fun. Add it only if the cron calls native Telegram helpers.
Configuration scope
Platform MySQL errors concern the platform configuration, while PDO SQLite errors in a bot concern its own database. Never copy platform database passwords into hosted bots. OPcache caches PHP bytecode; Redis/APCu extensions being enabled do not automatically create your application’s persistent state.