Zero-Config App & Web Dashboard
Tueen\Telegram\App is the high-level application bootstrapper and orchestrator for tueen/telegram. It eliminates boilerplate configuration, automatically sets up file-based conversation flow storage, auto-discovers attribute controllers, and provides a built-in Web Setup Wizard and CLI tooling.
🚀 1. The Single-File Entry Point
With App, you can launch a complete, production-ready Telegram bot from a single file:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use Tueen\Telegram\App;
$app = App::create(__DIR__);
$app->run();Flexible Entry Point Naming
While index.php is standard, you can freely name your entry point file whatever you want (such as bot.php, update.php, or webhook.php). App::create(__DIR__) dynamically inspects the executing script and automatically resolves the correct public webhook URL.
⚡ 2. Adaptive Execution Environments
When $app->run() is invoked, it intelligently detects the execution context:
CLI / TerminalHTTP POST (Webhook)HTTP GET (Browser)🌐 3. Web Setup Wizard & Management Console
Opening index.php in a web browser activates the Royal Web Dashboard:
1. First-Time Setup Wizard (When Token is Empty)
If no bot token is configured in config.php:
- Displays a setup form to enter your Bot Token (from
@BotFather). - Automatically detects your public webhook URL (
https://yourdomain.com/index.php). - Includes a button to generate a secure 32-character random
secret_token. - Tests connection with
getMe()and automatically sets the webhook viasetWebhook(). - Automatically writes credentials into
config.php.
2. Live Management Console (When Configured)
Once configured, visiting the URL in a browser displays a real-time status console:
- Bot Profile: Name,
@username, Bot ID, group permissions, and Bot API ping latency. - Webhook Telemetry: Active webhook URL, pending update queue count, SSL certificate type, max connections, and any recent delivery errors from Telegram servers.
- One-Click Actions:
- 🎯 Set / Update Webhook: Sets the webhook to the current URL with optional
drop_pending_updates. - 🗑️ Delete Webhook: Removes the webhook from Telegram servers.
- 🔄 Refresh: Reloads live status from Telegram Bot API.
- 🎯 Set / Update Webhook: Sets the webhook to the current URL with optional
- Storage & Flow Metrics: Displays active flow session files and storage path.
Securing the Dashboard
To protect the web dashboard with a password, specify setup.password in your config.php, or set SETUP_PASSWORD in your .env file:
return [
'token' => '...',
'setup' => [
'enabled' => true,
'password' => 'my-secure-dashboard-password',
],
];Or in .env:
SETUP_PASSWORD=my-secure-dashboard-passwordOnce logged in, an active session is securely maintained. You can click 🔒 Logout in the header at any time to lock the dashboard again.
💾 4. Automatic Flow State Storage (storage/flow)
App automatically configures persistent conversation flow storage:
- By default, it creates
$basePath . '/storage/flow'and attachesFileStateStore. - Protects the directory against direct web browser access with an Apache
.htaccess(Deny from all) and anindex.phpfallback (403 Forbidden). - Multi-step conversational flows (
$bot->startFlow(...)) automatically persist state without any external database or Redis setup.
To customize the flow storage path, configure flow_storage in config.php:
return [
'token' => '...',
'flow_storage' => '/var/data/telegram_flows',
];📁 5. Automatic Controller Discovery
If your bot project has a controllers/ directory in its project root, App automatically scans all PHP files inside it. Any class decorated with routing attributes (#[OnCommand], #[OnCallbackQuery], #[OnMessage], #[OnInlineQuery], #[OnUpdate]) is registered automatically with zero boilerplate!
// controllers/StartController.php
namespace App\Controllers;
use Tueen\Telegram\Routing\Attributes\OnCommand;
use Tueen\Telegram\Types\Update;
use Tueen\Telegram\Telegram;
class StartController
{
#[OnCommand('start')]
public function start(Update $update, Telegram $bot): void
{
$bot->sendMessage(text: "Hello from auto-discovered controller!");
}
}🩺 6. System Diagnostics (doctor)
To troubleshoot webhook issues, SSL certificate mismatches, or file permission errors on shared hosting:
- Run
php index.php doctorin your terminal to see a colored diagnostic status table. - Or open your bot in a browser to inspect the System Diagnostics (Doctor) card in the Web Dashboard.
It verifies:
- PHP version compatibility (PHP 8.4+).
- Required extensions (
curl,json,mbstring,openssl). - Flow storage permissions (
storage/flowwritable). - Telegram Bot API server reachability and latency.
- Webhook URL HTTPS compliance.
🧭 7. App & CLI API Reference
Below is the complete reference of methods and properties available on Tueen\Telegram\App, along with terminal CLI commands.
🏛️ App Class (Tueen\Telegram\App)
App::create(string $basePath, array $config = []): staticApp::boot(string $basePath, array $config = []): staticprivate(set) Telegram $botTelegramAsymmetric Visibilitypublic Router $routerRouterProperty Hookpublic FlowManager $flowManagerFlowManagerProperty Hookprivate(set) string $basePathstringAsymmetric Visibilityprivate(set) string $storagePathstringAsymmetric Visibilityprivate(set) string $flowStoragePathstringAsymmetric Visibilityrun(mixed ...$handlers): mixedreply(string|Text $text, mixed ...$args): mixedcatch(string|callable $exceptionOrHandler, ?callable $handler = null): staticreloadConfig(array $overrides = []): static💻 CLI Administrative Commands
php index.phpphp index.php webhook:set <url> [--drop]php index.php webhook:delete [--drop]php index.php webhook:infophp index.php bot:infophp index.php doctor