Botlify PHP and Runtime Handbook

Raw MD
Plain PHP, helper PHP, environment, files and migration.

This handbook explains how plain PHP, Telegram helpers and the hosted Botlify runtime fit together. All examples target the current opt-in runtime. PHP examples are syntax checked locally; that is not a guarantee that every Telegram operation is live-tested.

Choose your starting point

Goal Recommended starting point Loader
A small Telegram bot with less API boilerplate Native helpers tg_all_fun();
Control JSON, cURL and response handling yourself Plain PHP/cURL None
A scheduled database/file task Normal PHP cron None
A hosted scheduled Telegram notification PHP cron plus helpers tg_all_fun();
A direct standalone CLI script Your own initialization and credentials Botlify is not automatically present

Helpers are PHP functions, not another language. They do not make Telegram faster or bypass its permissions. The main differences are convenience, request defaults and who maintains the transport.

What the platform provides

The hosted gateway identifies the bot and loads platform bootstrap. It resolves the bot directory, prepares tracking and error handling, audits code, enters the sandbox and executes the bot entrypoint. Hosted bot code receives the update through php://input.

The sandbox changes the working directory, exports the selected bot's environment, removes selected platform environment values, redirects PHP errors to the bot's error.log and blocks specified system/platform operations. These controls are implementation mechanisms, not a claim that arbitrary untrusted PHP is harmless.

The public tg_* suite is opt-in for hosted bot and isolated child-cron executions. The loader and internal platform transport are still present. Platform administration pages load their own helpers. Calling the loader registers functions once per request; it does not send a request itself. The containing PHP source still needs compilation/cache handling.

Entrypoints and files

File Purpose Guidance
index.php Hosted bot entrypoint Read the update, route it, perform bounded work
.env Bot configuration Keep tokens private; use environment variables in hosted execution
database.db Bot-owned SQLite state Use prepared statements and short transactions
error.log Runtime diagnostics Review fresh timestamps; never deliberately log tokens
cron.php or another target Your scheduled task Schedule the target through Botlify; do not replace the platform master cron
Uploaded media Bot assets Use paths anchored to __DIR__

The platform's MySQL database is separate from a hosted bot's SQLite database. A platform MySQL access-denied error is not fixed by changing a bot's SQLite file. Hosted bots should not call internal platform database functions.

Environment values

The hosted sandbox exports BOT_TOKEN, BOT_USERNAME, ADMIN_CHAT_ID, OWNER_CHAT_ID and BOT_ID when supplied by the bot configuration. Check for missing values rather than assuming a successful read.

Code example
<?php
declare(strict_types=1);
$token = (string) (getenv('BOT_TOKEN') ?: '');
$adminId = (string) (getenv('ADMIN_CHAT_ID') ?: '');
if ($token === '' || $adminId === '') {
    error_log('Bot configuration is incomplete.');
    return;
}
// Keep these values private; do not dump the environment into chat.

For a standalone CLI script, arrange its environment yourself. A file named .env is not automatically interpreted by PHP. Botlify's hosted runners load the bot configuration; plain PHP outside that runtime does not.

Loader placement and migration

Code example
<?php
declare(strict_types=1);
tg_all_fun();
// Native helpers are now available for the rest of this request.

tg_allfun() is a different, undefined name. Place the exact tg_all_fun(); call after declare(strict_types=1) and before the first native helper. An included file that calls helpers needs initialization before that file is executed too.

For existing bots during a coordinated old/new runtime deployment:

Code example
<?php
declare(strict_types=1);
if (function_exists('tg_all_fun')) {
    tg_all_fun();
}
// Existing helper-based application code follows.

This migration guard supports the old eager runtime and the new opt-in runtime. It does not provide helpers to standalone PHP. Update matching runtime files together, migrate all helper-based bot/cron entrypoints, and verify the deployed runtime version.

Normal PHP keeps working

PHP variables, arrays, functions, JSON, PDO and cURL remain normal PHP. Not calling the loader does not disable them. Conversely, calling a tg_* function without loading the suite produces a normal undefined-function error. Custom error-message rewriting is not enabled.

Do not define your own functions with the same names as the native suite and then load that suite. Prefer project-specific names such as mybot_request for plain PHP functions.

Where to go next