Configuration

tueen/telegram features an immutable configuration architecture paired with an expressive, fluent ConfigBuilder. Every parameter — from networking timeouts and persistent connection pooling to progress event hooks, running modes, and error handling strategies — is strictly typed and discoverable via IDE autocompletion.

---

🛠️ 1. Creating Configuration

You can configure the client using Telegram::create('TOKEN'), Config::builder('TOKEN'), or by instantiating Config directly:

Fluent Builder via Telegram::create()

The recommended and most expressive approach:

use Tueen\Telegram\Telegram;
use Tueen\Telegram\Enums\ErrorHandlingMode;
use Tueen\Telegram\Running\WebhookMode;

$config = Telegram::create('123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11')
    ->withTimeout(30.0)
    ->withConnectTimeout(10.0)
    ->withProxy('http://127.0.0.1:10809')
    ->withRetryCount(3)
    ->withErrorObjectMode()
    ->withRunningMode(new WebhookMode(secretToken: 'my_super_secret_token'))
    ->build();

$bot = new Telegram($config);

Direct Instantiation of Config

For configuration files or dependency injection factories:

use Tueen\Telegram\Config;

$config = new Config(
    botToken: 'YOUR_BOT_TOKEN',
    timeout: 45.0,
    connectTimeout: 5.0,
    retryCount: 5,
    testEnvironment: false
);

$bot = new Telegram($config);

---

🧭 2. Detailed Configuration Reference

Below is the exhaustive catalog of all configuration options available on ConfigBuilder and Config.

🌐 Server & Credentials

withToken(string $token)

→staticdefault: ''

Your Telegram Bot API token obtained from @BotFather.

withApiServer(string $url)

→staticdefault: 'https://api.telegram.org'

Custom or self-hosted Telegram Bot API server base URL. Essential for transferring files up to 2GB, higher throughput, or internal networks.

withTestEnvironment(bool $enabled = true)

→staticdefault: false

Switches the target endpoint to Telegram's dedicated Test Server Environment (/test) for sandbox testing.

---

⚡ HTTP Client, Networking & Transport

withTimeout(float $seconds)

→staticdefault: 30.0

Maximum execution timeout for HTTP requests in seconds. For long-polling or large video uploads, consider increasing to 60.0 or higher.

withConnectTimeout(float $seconds)

→staticdefault: 10.0

Connection timeout for opening TCP/TLS sockets to the Telegram API in seconds.

withProxy(?string $proxy)

→staticdefault: null

HTTP, HTTPS, or SOCKS5 proxy URL (e.g. socks5h://127.0.0.1:9050 or http://proxy.corp.internal:8080).

withVerifySsl(bool|string $verifySsl = true)

→staticdefault: false

Controls SSL certificate verification for HTTP requests (verify in Guzzle / CURLOPT_SSL_VERIFYPEER in cURL). Can be a boolean, or a string specifying the path to a custom CA bundle file (.pem/.crt). Defaults to false.

withHttpClient(?HttpClientInterface $client)

→staticdefault: GuzzleHttpClient

Custom HTTP client implementation implementing HttpClientInterface.

withCurlClient(bool $persistent = true)

→staticdefault: true

High-performance native PHP 8.5 client utilizing persistent cURL share handles (curl_share_init_persistent()). Eliminates repetitive TLS handshakes and DNS lookups.

---

📊 Progress Tracking Callbacks

withUploadProgress(?Closure $callback)

→staticdefault: null

Event callback invoked during file uploads (e.g. sending videos, documents, or photo albums).

withDownloadProgress(?Closure $callback)

→staticdefault: null

Event callback invoked during file downloads via $bot->downloadFile().

Progress Callback Signature

Both progress callbacks receive three informative parameters:

$config = Telegram::create('YOUR_TOKEN')
    ->withUploadProgress(function (int $bytesUploaded, int $totalBytes, float $percentage): void {
        printf("Uploading: %5.1f%% (%d / %d bytes)\r", $percentage, $bytesUploaded, $totalBytes);
    })
    ->withDownloadProgress(function (int $bytesDownloaded, int $totalBytes, float $percentage): void {
        printf("Downloading: %5.1f%% (%d / %d bytes)\r", $percentage, $bytesDownloaded, $totalBytes);
    })
    ->build();

---

🛡️ Error Handling Strategy

withErrorHandlingMode(ErrorHandlingMode $mode)

→staticdefault: EXCEPTION

Switches between traditional exception throwing (EXCEPTION) and typed Error object returns (ERROR_OBJECT).

withErrorObjectMode(array $catchExceptions = [ApiException::class])

default: [ApiException::class]

Activates error object mode and specifies which exception classes should be converted into returned Error objects.

withExceptionMode()

→staticmode: exception

Restores the default exception-throwing behavior for all errors.

withCatchAllErrors()

→staticmode: catch-all

Catches all \Throwable instances (including connection resets, DNS failures, and timeout exceptions) as Error objects.

withConvertExceptions(array $classes)

→staticlist<class-string<Throwable>>

Defines the specific list of exception classes to catch and convert to Error objects.

---

🚀 Running Modes & Resiliency

withRunningMode(?RunningModeInterface $mode)

→staticdefault: WebhookMode

Configures the default bot execution runner: new WebhookMode(...), new PollingMode(...), or new AutoMode(...).

withPollingMode(PollingMode $mode)

→staticPollingMode

Convenience shortcut to configure long-polling mode with custom batch limits, timeout, backoff, and process concurrency.

withWebhookMode(WebhookMode $mode)

→staticWebhookMode

Convenience shortcut to configure webhook mode with secret token verification and non-blocking safe responses.

withAutoMode(?PollingMode $polling = null, ?WebhookMode $webhook = null, bool $autoDeleteWebhook = false, bool $dropPendingUpdatesOnDelete = false, ?callable $detector = null)

→staticAutoMode

Configures adaptive AutoMode to seamlessly switch between CLI Polling and HTTP Webhook execution with optional webhook cleanup and custom environment detection.

withRetryCount(int $count)

→staticdefault: 3

Number of automatic retries on rate limits (429 Too Many Requests with retry_after) or transient network dropouts.

---

🔄 Conversation Flow & Orchestration

withRootFlow(?string $flowClass)

→static?class-string<Flow>

Specifies the root/home Flow class. Automatically redirected to on /start, home navigation actions, or as a graceful recovery fallback.

withDefaultFlow(?string $flowClass)

→staticAlias

👉DX Shorthand: Alias for withRootFlow()

Shorthand alias for withRootFlow().

withFlowAllowedUpdates(array $types)

→staticdefault: [] (all updates)

Sets the global default allowed update types for conversation flows. An empty array permits all updates. Disallowed updates bypass the flow.

---

📋 Logging & Observability

withLogger(?LoggerInterface $logger)

→staticdefault: null

PSR-3 compliant logger (e.g. Monolog) for logging outbound API requests, response payloads, rate limits, and retries.

---

💉 Dependency Injection & Container

withContainer(mixed $container)

→staticPSR-11 / callable

PSR-11 container (or callable resolver) used to instantiate controller classes, handler classes in $bot->run(...), and multi-step Flow classes.

---

⚡ Client Instantiation Shortcuts

client()

→TelegramFactory

Directly constructs and returns an initialized Telegram client instance without having to manually call new Telegram($builder->build()).

make()

→TelegramAlias

👉DX Shorthand: Alias for client()

Shorthand alias for client().

---

🧬 3. Immutability & Modern PHP 8.5 Patterns

The Config class is completely immutable. Every with...() method creates and returns a clean new instance using PHP 8.5's clone with and #[\NoDiscard] attributes:

$baseConfig = Telegram::create('YOUR_TOKEN')
    ->withTimeout(30.0)
    ->build();

// Derive a specialized configuration without modifying $baseConfig:
$fastConfig = $baseConfig
    ->withTimeout(5.0)
    ->withRetryCount(1);

// $baseConfig->timeout remains 30.0
// $fastConfig->timeout is 5.0

---

🌐 4. Standard URI & URL Resolution Properties

Config provides convenient properties powered by PHP 8.4 property hooks to resolve target URLs and standards-compliant Uri\Rfc3986\Uri objects:

public string $baseApiUrl

→stringProperty Hook

Fully qualified Telegram Bot API base URL (e.g. 'https://api.telegram.org/bot<token>').

public string $baseFileUrl

→stringProperty Hook

Fully qualified Telegram File download base URL (e.g. 'https://api.telegram.org/file/bot<token>').

public Uri|string $apiUri

→Uri|stringProperty Hook

RFC 3986 URI object instance for the Bot API base endpoint.

public Uri|string $fileUri

→Uri|stringProperty Hook

RFC 3986 URI object instance for the File download base endpoint.

$config = Telegram::create('123456:ABC')->build();

echo $config->baseApiUrl;
// "https://api.telegram.org/bot123456:ABC"

$uri = $config->apiUri;
echo $uri->getHost(); // "api.telegram.org"
echo $uri->getPath(); // "/bot123456:ABC"

---

💡 5. Real-World Configuration Recipes

Recipe 1: Production Webhook with Persistent cURL & Monolog

use Tueen\Telegram\Telegram;
use Tueen\Telegram\Running\WebhookMode;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('telegram');
$logger->pushHandler(new StreamHandler(storage_path('logs/telegram.log')));

$config = Telegram::create($_ENV['TELEGRAM_BOT_TOKEN'])
    // High-performance persistent cURL handles
    ->withCurlClient(persistent: true)
    ->withTimeout(15.0)
    ->withConnectTimeout(3.0)
    ->withRetryCount(3)
    ->withLogger($logger)
    // Production Webhook mode with secret token verification
    ->withRunningMode(new WebhookMode(secretToken: $_ENV['TELEGRAM_WEBHOOK_SECRET']))
    ->build();

$bot = new Telegram($config);

---

Recipe 2: High-Volume CLI Long-Polling Worker

use Tueen\Telegram\Telegram;
use Tueen\Telegram\Running\PollingMode;

$polling = new PollingMode(
    timeout: 50,             // Long-polling timeout in seconds
    limit: 100,              // Max updates per batch
    errorBackoffSeconds: 5   // Auto-backoff on network interruptions
);

// Enable multi-process concurrency on CLI:
$polling->forkProcess(true);

$config = Telegram::create(getenv('BOT_TOKEN'))
    ->withTimeout(60.0) // Must exceed polling timeout
    ->withRunningMode($polling)
    ->build();

$bot = new Telegram($config);
$bot->run(App\Handlers\UpdateHandler::class);

---

Recipe 3: Tor / SOCKS5 Proxy for Restricted Environments

use Tueen\Telegram\Telegram;

$config = Telegram::create('YOUR_TOKEN')
    ->withProxy('socks5h://127.0.0.1:9050')
    ->withTimeout(60.0)
    ->withConnectTimeout(15.0)
    ->withRetryCount(5)
    ->build();

$bot = new Telegram($config);

---

Recipe 4: Self-Hosted Local Bot API Server (2GB Uploads)

use Tueen\Telegram\Telegram;

$config = Telegram::create('YOUR_TOKEN')
    // Point to your local Telegram Bot API Docker container:
    ->withApiServer('http://telegram-bot-api:8081')
    ->withTimeout(300.0) // 5 minutes for massive files
    ->build();

$bot = new Telegram($config);

---

Recipe 5: Laravel & Symfony PSR-11 Container Integration

use Tueen\Telegram\Telegram;

// In Laravel service provider or Symfony dependency injection:
$config = Telegram::create(config('services.telegram.token'))
    ->withContainer(app()) // Injects Laravel's IoC container
    ->build();

$bot = new Telegram($config);

// Handlers and Flow classes now automatically resolve with full dependency injection!
$bot->run(App\Handlers\OnboardingHandler::class);

---

Recipe 6: Adaptive AutoMode Execution (Unified CLI & HTTP Webhook)

use Tueen\Telegram\Telegram;
use Tueen\Telegram\Running\PollingMode;
use Tueen\Telegram\Running\WebhookMode;

$bot = Telegram::create($_ENV['BOT_TOKEN'])
    ->withPollingMode(new PollingMode(timeout: 45))
    ->withWebhookMode(new WebhookMode(secretToken: $_ENV['WEBHOOK_SECRET']))
    ->withAutoMode(autoDeleteWebhook: true)
    ->client();

// In CLI (php bot.php): executes PollingMode
// In Web Server (POST /webhook): executes WebhookMode
$bot->run(App\Handlers\BotHandler::class);