# Botlify PHP and Runtime Handbook

> Plain PHP, helper PHP, environment, files and migration.

**Category:** Getting Started  
**URL:** https://docs.botlify.cloud/botlify-php-handbook  
**Platform:** Botlify Cloud (https://botlify.cloud)  

---

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.

```php

```

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

```php

```

`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:

```php

```

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

- Complete helper API reference

- Equivalent complete bots

- Updates, callbacks and state

- Cron, releases and troubleshooting

- Loader migration checklist
