# tueen/telegram - Full Documentation Context
# The Royal Telegram Bot SDK for Modern PHP (PHP 8.4+)
# Official Repository: https://github.com/tueen/telegram/
# Documentation Base URL: https://tueen.github.io/telegram/
#
# Note for AI Models: If any detail, method signature, or edge-case behavior is not
# fully covered in this documentation, consult the official GitHub repository:
# https://github.com/tueen/telegram/



# ==============================================================================
# File: /guide/getting-started
# Section: Getting Started > Getting Started
# ==============================================================================

# Getting Started

## Introduction

> *The Royal Telegram Bot SDK for Modern PHP*

`tueen/telegram` is a modern Telegram Bot API client for PHP. It provides strict typing, full IDE autocompletion, and forward compatibility with the Telegram Bot API specification.

---

## Requirements

- **PHP 8.4+**
- **Composer 2.x**
- Extensions: `json`, `curl` or stream wrappers

---

## Installation

Install the package via Composer:

```bash
composer require tueen/telegram
```

---

## Client Initialization

### Direct Initialization
If you just need standard defaults:

```php
use Tueen\Telegram\Telegram;

$bot = new Telegram('YOUR_BOT_TOKEN');
```

### Fluent ConfigBuilder
For advanced options (proxies, timeouts, error modes, test environment):

```php
use Tueen\Telegram\Telegram;

$config = Telegram::create('YOUR_BOT_TOKEN')
    ->withTimeout(30.0)
    ->withProxy('http://127.0.0.1:10809')
    ->withRetryCount(3)
    ->withErrorObjectMode()
    ->build();

$bot = new Telegram($config);
```

::: tip Building a Standalone Bot with a Web Dashboard?
If you're building a standalone bot from scratch, `tueen/telegram` also includes **`App`** — a zero-config application orchestrator featuring a 3-file project template, automated session storage, CLI tools, and a real-time **Web Setup & Management Dashboard**. See the [Zero-Config App & Web Dashboard Guide](./app).
:::

---

## Supported Bot API Version

You can inspect the supported Telegram Bot API version programmatically at runtime:

```php
use Tueen\Telegram\Telegram;

echo Telegram::BOT_API_VERSION;
```

---

## First API Call: `getMe`

```php
$me = $bot->getMe();

if ($me->ok()) {
    echo "Bot ID: {$me->id}\n";
    echo "Bot Username: @{$me->username}\n";
}
```

---

## Sending a Message

You can call any Telegram Bot API method directly using named arguments:

```php
use Tueen\Telegram\Enums\ParseMode;

$message = $bot->sendMessage(
    chatId: 123456789,
    text: 'Hello from <b>tueen/telegram</b>!',
    parseMode: ParseMode::HTML
);

echo "Message sent with ID: {$message->messageId}\n";
```

::: tip Always Use Named Parameters
In `tueen/telegram`, **always invoke API methods using PHP named parameters** (e.g. `chatId: ...`, `text: ...`, `parseMode: ...`). Named parameters make your code self-documenting, protect against argument reordering in future Bot API updates, and allow you to omit contextual parameters (like `chatId`) seamlessly.
:::

---

## Handling Incoming Updates

Choose between **Webhook Mode** (recommended for production) and **Polling Mode** (ideal for CLI/local testing):

```php
use Tueen\Telegram\Telegram;
use Tueen\Telegram\Types\Update;

// Run the bot using the configured running mode (Webhook or Polling)
$bot->run(function (Update $update, Telegram $bot) {
    $message = $update->findMessage();
    if ($message !== null) {
        $bot->sendMessage(
            chatId: $message->chat->id,
            text: "Received: {$message->findAnyText()}"
        );
    }
});
```

---

## Next Steps

Now that your bot is running, explore the core essentials:

- 💬 **[Calling Methods & Types](./methods-and-types):** Learn how to invoke Bot API methods with named arguments and contextual auto-injection.
- ⌨️ **[Interactive Keyboards](./keyboards):** Build Inline and Reply keyboards with fluent builders.
- 📝 **[Text Formatting & Escaping](./formatting):** Format messages safely using HTML and MarkdownV2 without entity parsing errors.
- 🧭 **[Update Routing & Attributes](./routing):** Organize commands, regex patterns, and callback queries with attributes and controllers.
- 🔄 **[Running Modes](./running-modes):** Dive deeper into Webhook, Polling, and AutoMode configurations.


# ==============================================================================
# File: /guide/telegram-client
# Section: Getting Started > The Telegram Client
# ==============================================================================

# The Telegram Client

The `Tueen\Telegram\Telegram` class (conventionally instantiated as `$bot`) is the primary entry point and client facade of the `tueen/telegram` library. It provides a unified, strictly typed interface for sending Bot API requests, listening for updates, managing multi-step flows, and resolving contextual parameters.

---

## 🚀 1. Instantiation

You can initialize the client either directly with your bot token or via a pre-built `Config` object:

### Basic Instantiation
```php
use Tueen\Telegram\Telegram;

$bot = new Telegram('YOUR_BOT_TOKEN');
```

### Advanced Instantiation with `ConfigBuilder`
For production environments requiring custom timeouts, proxy connections, retry policies, or test servers:
```php
use Tueen\Telegram\Telegram;

$config = Telegram::create('YOUR_BOT_TOKEN')
    ->withTimeout(30.0)
    ->withRetryCount(3)
    ->build();

$bot = new Telegram($config);
```
> For a full list of networking and runtime settings, see the [Configuration Reference](./configuration).

---

## ⚡ 2. The Three Primary Roles of `$bot`

In your application, the `$bot` instance serves three essential purposes:

### 1. Direct Bot API Client
You can invoke all Telegram Bot API methods dynamically with full IDE autocompletion and named arguments:
```php
$bot->sendMessage(
    chatId: 123456789,
    text: 'Hello from tueen/telegram!'
);
```
> Learn more in [Calling Methods & Types](./methods-and-types).

### 2. Update Router & Dispatcher
The client listens for incoming updates and dispatches them to closures, classes, or attribute controllers:
```php
// Register a command route:
$bot->onCommand('start', function (Update $update, Telegram $bot) {
    $bot->sendMessage(text: 'Welcome! How can I assist you today?');
});

// Run the bot via Webhook, Polling, or AutoMode:
$bot->run();
```
> Learn more in [Update Routing & Attributes](./routing) and [Running Modes](./running-modes).

### 3. Contextual Entity Resolver (PHP 8.4 Property Hooks)
During update processing, `$bot` automatically tracks the active update and provides instant shortcuts to chat, user, and message identifiers via modern PHP 8.4 Property Hooks:
```php
$chatId  = $bot->chatId;  // e.g. 123456789
$userId  = $bot->userId;  // e.g. 987654321
$message = $bot->message; // Current ?Message instance
```
> **Tip:** Legacy method calls such as `$bot->chatId()` continue to work with a deprecation notice for full backward compatibility. Learn more in [Update & Message Helpers](./update-and-message-helpers).

---

## 💡 3. Client Best Practices

Here are the recommended patterns to keep in mind when working with the `$bot` instance:

### 1. Always Use PHP Named Arguments
Telegram Bot API methods accept many optional parameters. Named arguments protect your code against parameter order changes and enable **Contextual Auto-Injection** (where repetitive parameters like `chatId` are automatically resolved from the active update):

```php
// ✅ RECOMMENDED: Order-independent, self-documenting, auto-injects chatId:
$bot->sendMessage(
    text: 'Order confirmed successfully.',
    parseMode: ParseMode::HTML
);

// ❌ AVOID: Fragile positional arguments with trailing nulls:
$bot->sendMessage(123456, 'Order confirmed successfully.', null, null, null, null, 'HTML');
```

### 2. Reusing a Single Client Instance
`Telegram` is lightweight and designed to be created once. In modern frameworks (such as Laravel, Symfony, or Slim), register `$bot` as a singleton in your dependency injection container:

```php
// Example: Registering as a singleton in a PSR-11 container:
$container->singleton(Telegram::class, function () {
    return new Telegram(getenv('TELEGRAM_BOT_TOKEN'));
});
```

### 3. Organizing Complex Bots with Controllers
For simple bots, defining routes with closures directly in your script is quick and convenient. As your application grows, organize your commands and actions into dedicated Controller classes:

```php
// Register a dedicated controller class decorated with routing attributes:
$bot->registerController(OrderController::class);
```
> See [Attribute-Driven Controllers](./routing#3-attribute-driven-controllers) for examples of using `#[OnCommand]` and `#[OnCallbackQuery]`.

---

## 🏛️ 4. Architecture & Decoupled Subsystems

Under the hood, `Telegram` is not a monolithic class holding all bot logic. Instead, it uses a **modular composition architecture** that delegates work to single-responsibility components:

```mermaid
flowchart LR
    subgraph InboundTrack ["Inbound Pipeline (Receiving Updates)"]
        direction TB
        TelegramIn[("Telegram Bot API")] -->|Webhook or Polling| Runner["RunningMode"]
        Runner --> Dispatcher["UpdateDispatcher"]
        Dispatcher --> UpdatePipes["Global Middlewares"]
        
        UpdatePipes --> PriorityCheck{"Priority Route?"}
        PriorityCheck -->|Yes| ConsultFlow{"Flow Allows?"}
        ConsultFlow -->|Allowed| PriorityHandler["Priority Handler"]
        
        PriorityCheck -->|No| FlowCheck{"Active Flow?"}
        ConsultFlow -->|Vetoed| FlowCheck
        
        FlowCheck -->|Yes| FlowStep["Execute Flow Step"]
        FlowStep --> FlowDecision{"Step Handled?"}
        FlowDecision -->|Yes| FlowDone["Save Flow State"]
        FlowDecision -->|Pass Through| RouterEngine["Router & Route Groups"]
        
        FlowCheck -->|No| RouterEngine
        RouterEngine -->|Matched Route| RoutePipes["Route Middlewares"]
        RoutePipes --> AutoWire["Auto-Wiring & Type Casting"]
        AutoWire --> RouteHandlers["Route Handlers"]
        RouterEngine -->|Unmatched| Fallback["Fallback Handler"]
    end

    subgraph OutboundTrack ["Outbound Pipeline (Sending Requests)"]
        direction TB
        Context["ContextResolver (Auto-Inject)"]
        Context --> HttpPipes["HTTP Middlewares (Retry, RateLimit)"]
        HttpPipes --> Client["TelegramClient (PSR-18)"]
        Client --> Pool["Persistent cURL Connection Pool"]
        Pool --> TelegramOut[("Telegram Bot API")]
    end

    %% Handlers send API requests back through Outbound Pipeline
    PriorityHandler -->|Reply or Send| Context
    FlowStep -->|Reply or Send| Context
    RouteHandlers -->|Reply or Send| Context
    Fallback -.->|Optional Reply| Context
    DirectCall["Queue Worker or Scoped Worker"] -.-> Context
```

### When to Access Subsystems Directly:
Most of the time, you interact exclusively with the `$bot` facade. However, you can access underlying subsystems when building low-level extensions, worker queues, persistent daemons, or custom integrations:

```php
use Tueen\Telegram\Telegram;
use Tueen\Telegram\Client\CurlHttpClient;

$bot = new Telegram('YOUR_BOT_TOKEN');

// 1. Pure HTTP client (useful for worker queue jobs that only call API methods without processing updates):
$client = $bot->client;
$me = $client->getMe();

// 2. Underlying router instance (inspect or manipulate route collections directly):
$router = $bot->router;

// 3. Flow state manager (for custom state stores or manual session manipulation):
$flowManager = $bot->flowManager;

// 4. Context parameter resolver (manual default binding or contextual entity inspection):
$context = $bot->context;
$activeChatId = $context->chatId;

// 5. Scoped Client for Persistent Worker Engines (FrankenPHP, RoadRunner, Swoole, Laravel Octane):
// Clones the client into a thread-safe, isolated instance with dedicated context per update:
$scopedBot = $bot->scoped($incomingUpdate);

// 6. PSR-11 Dependency Injection Container:
// Connect an external DI container (e.g. Laravel Container, PHP-DI, Symfony DI) for controller auto-wiring:
$bot->container = $myContainer;

// 7. Persistent HTTP Connection Pool Management:
// Check cached TCP/TLS keep-alive handles or flush them during worker maintenance:
$poolCount = CurlHttpClient::getPoolCount();
CurlHttpClient::closeAllHandles();
```

---

## 🧭 5. Complete Method & Property Reference

Below is the comprehensive catalog of all constants, properties, and methods provided on the `Telegram` class, grouped by architectural responsibility. Every item features syntax-highlighted signatures, parameter types, default values, and status badges.

### 🏛️ Class Constants & Public Properties

<ApiGroup description="Core version identifiers and subsystem properties protected by PHP 8.4 asymmetric visibility and property hooks.">
  <ApiCard
    type="constant"
    sig="public const string BOT_API_VERSION"
    returns="string"
    badge="Constant"
    desc="Canonical Telegram Bot API version currently supported and validated against."
  />
  <ApiCard
    type="constant"
    sig="public const string API_VERSION = self::BOT_API_VERSION"
    returns="string"
    badge="Alias"
    aliasFor="Telegram::BOT_API_VERSION"
    desc="Shorthand alias for BOT_API_VERSION for cleaner references."
  />
  <ApiCard
    type="property"
    sig="public ?Update $update = null"
    returns="?Update"
    badge="Property Hook"
    desc="Current resolved Update instance for the active request lifecycle. Defaults to null until resolved by WebhookMode or PollingMode."
  />
  <ApiCard
    type="property"
    sig="private(set) ContextResolver $context"
    returns="ContextResolver"
    badge="Asymmetric Visibility"
    desc="Contextual parameter resolver instance automatically bound to $update for argument auto-injection."
  />
  <ApiCard
    type="property"
    sig="private(set) TelegramClient $client"
    returns="TelegramClient"
    badge="Asymmetric Visibility"
    desc="Underlying pure HTTP transport client handling serialization, multipart uploads, and PSR-18 communication."
  />
  <ApiCard
    type="property"
    sig="private(set) UpdateDispatcher $dispatcher"
    returns="UpdateDispatcher"
    badge="Asymmetric Visibility"
    desc="Incoming update dispatcher managing the middleware pipeline, route execution, and exception catchers."
  />
  <ApiCard
    type="property"
    sig="private(set) Config $config"
    returns="Config"
    badge="Asymmetric Visibility"
    desc="Immutable client configuration driving timeouts, tokens, and networking."
  />
  <ApiCard
    type="property"
    sig="public RunningModeInterface $runningMode"
    returns="RunningModeInterface"
    badge="Property Hook"
    desc="Active running mode instance (e.g. WebhookMode, PollingMode, or AutoMode)."
  />
  <ApiCard
    type="property"
    sig="public mixed $container"
    returns="mixed"
    badge="Property Hook"
    desc="Configured PSR-11 dependency injection container or callable resolver."
  />
  <ApiCard
    type="property"
    sig="public FlowManager $flowManager"
    returns="FlowManager"
    badge="Property Hook"
    desc="Multi-step conversational flow manager and state orchestrator."
  />
  <ApiCard
    type="property"
    sig="public Router $router"
    returns="Router"
    badge="Property Hook"
    desc="Incoming update router and controller registry."
  />
</ApiGroup>

---

### A. Initialization & Testing Factory

<ApiGroup description="Instantiation shortcuts, immutable configuration loading, and testing fakes.">
  <ApiCard
    sig="Telegram::create(string $botToken)"
    returns="ConfigBuilder"
    badge="Factory"
    desc="Initializes a fluent ConfigBuilder for configuring network timeouts, persistent cURL handles, proxies, retries, and running modes."
  />
  <ApiCard
    sig="Telegram::fake(array $responses = [], string $botToken = 'FAKE_BOT_TOKEN')"
    returns="TelegramFake"
    badge="Testing"
    desc="Creates an in-memory testing fake client with recording capabilities and assertion helpers (assertSent, assertSentCount, assertNotSent)."
  />
  <ApiCard
    sig="new Telegram(string|Config $tokenOrConfig)"
    returns="Telegram"
    badge="Constructor"
    desc="Instantiates the primary Telegram client directly using either a plain bot token string or a pre-built immutable Config object."
  />
</ApiGroup>

---

### B. Execution & Running Modes

<ApiGroup description="Primary bot runtime execution, long-polling streams, and adaptive CLI/HTTP orchestration.">
  <ApiCard
    sig="run(mixed ...$handlers)"
    returns="mixed"
    badge="Canonical"
    desc="Executes update ingestion using the configured running mode (WebhookMode or PollingMode), dispatching updates through middlewares and routes."
  />
  <ApiCard
    sig="autoRun(mixed ...$handlers)"
    returns="mixed"
    badge="Adaptive"
    desc="Zero-config adaptive runner: automatically selects PollingMode in CLI environments and WebhookMode under HTTP server processes."
  />
  <ApiCard
    sig="useAutoMode(?PollingMode $polling = null, ?WebhookMode $webhook = null, bool $autoDeleteWebhook = false, bool $dropPendingUpdatesOnDelete = false, ?callable $detector = null)"
    returns="static"
    desc="Explicitly configures AutoMode with custom runner instances, automated webhook cleanup on shutdown, and optional environment detection overrides."
  />
  <ApiCard
    sig="setRunningMode(RunningModeInterface $mode)"
    returns="static"
    desc="Sets an explicit running mode instance (e.g. custom WebhookMode, PollingMode, or user-defined runner)."
  />
  <ApiCard
    sig="poll(int $timeout = 30, int $limit = 100, ?array $allowedUpdates = null)"
    returns="Generator<int, Update>"
    badge="Streaming"
    desc="Returns a lazy PHP generator yielding incoming Update objects via continuous long-polling with automatic offset tracking."
  />
</ApiGroup>

---

### C. Update Pipeline & Middleware

<ApiGroup description="Global incoming update middleware, outbound HTTP pipeline, and granular lifecycle hooks.">
  <ApiCard
    sig="middleware(callable $middleware)"
    returns="static"
    badge="Canonical"
    desc="Appends an update middleware to the incoming dispatch pipeline. Receives ($update, $next, $bot)."
  />
  <ApiCard
    sig="use(callable $middleware)"
    returns="static"
    badge="Alias"
    aliasFor="middleware()"
    desc="Developer experience shorthand alias for middleware(), popularized by Telegraf and grammY."
  />
  <ApiCard
    sig="pipe(MiddlewareInterface|Closure $middleware)"
    returns="static"
    badge="Outbound"
    desc="Appends an outbound HTTP request middleware to the client transport pipeline (e.g. RetryMiddleware, RateLimitMiddleware, LoggingMiddleware)."
  />
  <ApiCard
    sig="onBeforeRequest(callable $callback)"
    returns="static"
    badge="Hook"
    desc="Lifecycle hook triggered immediately before sending any outbound HTTP request to Telegram. Receives ($request, $config)."
  />
  <ApiCard
    sig="onAfterRequest(callable $callback)"
    returns="static"
    badge="Hook"
    desc="Lifecycle hook triggered after receiving a raw HTTP response. Receives ($response, $request)."
  />
  <ApiCard
    sig="onError(callable $callback)"
    returns="static"
    badge="Hook"
    desc="Lifecycle hook triggered when a transport error or HTTP exception occurs. Receives ($throwable, $request)."
  />
  <ApiCard
    sig="onResponse(callable $callback)"
    returns="static"
    badge="Hook"
    desc="Lifecycle hook triggered when a final parsed response (Type or Error object) is produced. Receives ($type, $request)."
  />
</ApiGroup>

---

### D. Exception & Error Handling

<ApiGroup description="Typed exception catchers and incoming update error dispatching.">
  <ApiCard
    sig="catch(string|callable $exceptionOrHandler, ?callable $handler = null)"
    returns="static"
    badge="Canonical"
    desc="Registers a typed exception catcher for errors thrown during update processing. Matches exact exception classes or any \Throwable."
  />
  <ApiCard
    sig="onUpdateError(callable $handler)"
    returns="static"
    badge="Alias"
    aliasFor="catch(\Throwable::class, $handler)"
    desc="Convenience shorthand alias registering a universal error catcher for all unhandled update exceptions."
  />
  <ApiCard
    sig="handleUpdateException(\Throwable $e, Update $update)"
    returns="bool"
    badge="Internal"
    desc="Dispatches an uncaught exception through registered error catchers. Returns true if handled by a matching catcher."
  />
</ApiGroup>

---

### E. Update Routing & Controllers

<ApiGroup description="Declarative command matching, callback query regex routes, and attribute controller registration.">
  <ApiCard
    sig="group(array|callable $attributesOrCallback, ?callable $callback = null)"
    returns="static"
    badge="Routing"
    desc="Groups related routes with shared prefixes, middlewares, or chat-type scopes (e.g. $bot->group(['prefix' => 'admin_'], function ($bot) { ... }))."
  />
  <ApiCard
    sig="onCommand(string $command, mixed $handler, bool $priority = false)"
    returns="Route"
    desc="Matches bot commands (e.g. 'start', '/help') with automatic command argument parsing. Returns a Route instance supporting ->middleware(), ->asPrivate(), ->where()."
  />
  <ApiCard
    sig="onCallbackQuery(?string $pattern, mixed $handler, bool $priority = false)"
    returns="Route"
    desc="Matches inline keyboard callback queries against an optional regex or placeholder pattern ('item:{id}'). Returns a fluent Route instance."
  />
  <ApiCard
    sig="onMessage(?string $pattern, mixed $handler, bool $priority = false)"
    returns="Route"
    desc="Matches text messages against an optional regex pattern or exact match. Returns a fluent Route instance."
  />
  <ApiCard
    sig="onText(?string $pattern, mixed $handler, bool $priority = false)"
    returns="Route"
    badge="Alias"
    aliasFor="onMessage()"
    desc="Convenience shorthand alias for onMessage() matching text messages."
  />
  <ApiCard
    sig="onInlineQuery(?string $pattern, mixed $handler, bool $priority = false)"
    returns="Route"
    desc="Matches inline search queries with optional regex filtering. Returns a fluent Route instance."
  />
  <ApiCard
    sig="on(UpdateType|string $type, mixed $handler, bool $priority = false)"
    returns="Route"
    desc="Matches any Telegram update type (e.g. UpdateType::Message, UpdateType::CallbackQuery, or 'chat_member'). Returns a fluent Route instance."
  />
  <ApiCard
    sig="onFallback(mixed $handler)"
    returns="static"
    badge="Fallback"
    desc="Registers a default fallback handler invoked when no route, command, or active conversational flow matches the incoming update."
  />
  <ApiCard
    sig="registerController(string|object $controller)"
    returns="static"
    desc="Scans and registers an attribute-annotated controller class or object instance decorated with #[OnCommand], #[OnCallbackQuery], etc."
  />
  <ApiCard
    sig="router()"
    returns="Router"
    desc="Retrieves or initializes the underlying Router instance for custom route group manipulation."
  />
  <ApiCard
    sig="handle(mixed ...$handlers)"
    returns="static"
    desc="Appends raw update handler callables or invokable handler classes directly to the dispatcher queue."
  />
  <ApiCard
    sig="invokeHandler(mixed $handler, Update $update)"
    returns="mixed"
    badge="Dispatcher"
    desc="Resolves parameter dependencies via the DI container / ContextResolver and executes a single update handler."
  />
</ApiGroup>

---

### F. Multi-Step Conversational Flows

<ApiGroup description="Finite state machines, persistent multi-step forms, conversational navigation, and step stacks.">
  <ApiCard
    sig="flow(int|string|null $chatId = null, ?int $userId = null, ?Update $update = null)"
    returns="FlowSession"
    desc="Retrieves a fluent FlowSession for interacting with the active conversation, setting step state, or retrieving stored session data."
  />
  <ApiCard
    sig="startFlow(string $flowClass, ?Update $update = null, string $initialStep = 'start', array $initialData = [])"
    returns="Flow"
    desc="Initiates a multi-step conversation flow for the resolved chat and user, transitioning immediately to $initialStep."
  />
  <ApiCard
    sig="hasActiveFlow(int|string|null $chatId = null, ?int $userId = null, ?Update $update = null)"
    returns="bool"
    desc="Checks whether the chat/user currently has an active, unfinished conversation flow in persistent storage."
  />
  <ApiCard
    sig="getActiveFlow(int|string|null $chatId = null, ?int $userId = null, ?Update $update = null)"
    returns="?Flow"
    desc="Instantiates and returns the active Flow object populated with current state, or null if no flow is active."
  />
  <ApiCard
    sig="getActiveFlowClass(int|string|null $chatId = null, ?int $userId = null, ?Update $update = null)"
    returns="?string"
    desc="Returns the fully-qualified class string of the active flow without instantiating it."
  />
  <ApiCard
    sig="flowBack(int|string|null $chatId = null, ?int $userId = null, ?string $replyMessage = null, ?Update $update = null)"
    returns="bool"
    desc="Navigates the conversation back one step using the internal flow history stack, optionally sending a reply message."
  />
  <ApiCard
    sig="cancelFlow(int|string|null $chatId = null, ?int $userId = null, ?string $replyMessage = 'Operation cancelled.', ?Update $update = null)"
    returns="bool"
    desc="Cancels the active conversation, triggers onCancel() hooks, and wipes state from storage."
  />
  <ApiCard
    sig="finishFlow(int|string|null $chatId = null, ?int $userId = null, ?Update $update = null)"
    returns="bool"
    desc="Marks the active conversation as successfully completed and cleans up persistent storage."
  />
  <ApiCard
    sig="flowManager()"
    returns="FlowManager"
    desc="Returns the underlying FlowManager state orchestrator managing storage drivers and transition hooks."
  />
  <ApiCard
    sig="setFlowStore(StateStoreInterface $store)"
    returns="static"
    desc="Replaces the state driver with a custom implementation (e.g. MemoryStateStore, FileStateStore, Redis, or database)."
  />
  <ApiCard
    sig="setRootFlow(?string $flowClass)"
    returns="static"
    desc="Configures a default/root Flow class to automatically launch when an idle user sends a message or on /start."
  />
</ApiGroup>

---

### G. Contextual Accessors & Property Hooks

<ApiGroup description="Automatic resolution of active chat, user, thread, and message entities from the incoming update via PHP 8.4 Property Hooks.">
  <ApiCard
    type="property"
    sig="$bot->chatId"
    returns="?int"
    badge="Property Hook"
    desc="Resolves the active chat ID (extracted from message->chat->id, callback_query->message->chat->id, etc.)."
  />
  <ApiCard
    type="property"
    sig="$bot->userId"
    returns="?int"
    badge="Property Hook"
    desc="Resolves the active user ID from the current update (from->id)."
  />
  <ApiCard
    type="property"
    sig="$bot->messageId"
    returns="?int"
    badge="Property Hook"
    desc="Resolves the active message ID from the current update (message->message_id)."
  />
  <ApiCard
    type="property"
    sig="$bot->businessConnectionId"
    returns="?string"
    badge="Property Hook"
    desc="Resolves the active Telegram Business connection ID for enterprise bots."
  />
  <ApiCard
    type="property"
    sig="$bot->messageThreadId"
    returns="?int"
    badge="Property Hook"
    desc="Resolves the active forum topic thread ID for supergroups."
  />
  <ApiCard
    type="property"
    sig="$bot->inlineMessageId"
    returns="?string"
    badge="Property Hook"
    desc="Resolves the inline message identifier for updates initiated via inline queries."
  />
  <ApiCard
    type="property"
    sig="$bot->callbackQueryId"
    returns="?string"
    badge="Property Hook"
    desc="Resolves the active callback query ID from an inline button interaction."
  />
  <ApiCard
    type="property"
    sig="$bot->inlineQueryId"
    returns="?string"
    badge="Property Hook"
    desc="Resolves the active inline query ID."
  />
  <ApiCard
    type="property"
    sig="$bot->shippingQueryId"
    returns="?string"
    badge="Property Hook"
    desc="Resolves the active shipping query ID for e-commerce checkout flows."
  />
  <ApiCard
    type="property"
    sig="$bot->preCheckoutQueryId"
    returns="?string"
    badge="Property Hook"
    desc="Resolves the active pre-checkout query ID before payment finalization."
  />
  <ApiCard
    type="property"
    sig="$bot->directMessagesTopicId"
    returns="?int"
    badge="Property Hook"
    desc="Resolves the direct messages forum topic ID in Telegram Business."
  />
  <ApiCard
    type="property"
    sig="$bot->guestQueryId"
    returns="?string"
    badge="Property Hook"
    desc="Resolves the guest query ID for anonymous web interactions."
  />
  <ApiCard
    type="property"
    sig="$bot->chat"
    returns="?Chat"
    badge="Property Hook"
    desc="Extracts and returns the primary Chat type object from the current update."
  />
  <ApiCard
    type="property"
    sig="$bot->user"
    returns="?User"
    badge="Property Hook"
    desc="Extracts and returns the primary User type object from the current update."
  />
  <ApiCard
    type="property"
    sig="$bot->message"
    returns="?Message"
    badge="Property Hook"
    desc="Extracts and returns the primary Message type object from the current update."
  />
  <ApiCard
    sig="reply(string|Text $text, mixed ...$args)"
    returns="mixed"
    badge="Shortcut"
    desc="Direct convenience shortcut to send a text message to the active chat in context without specifying chatId manually."
  />
  <ApiCard
    sig="replyChunked(string|Text $text, int $chunkSize = 4096, mixed ...$args)"
    returns="list<mixed>"
    badge="Chunking"
    desc="Replies with a long text or Text builder instance, splitting messages intelligently at sentence and newline boundaries to respect the 4096 character limit."
  />
  <ApiCard
    sig="sendMessageChunked(string|Text $text, int $chunkSize = 4096, int|string|null $chatId = null, mixed ...$args)"
    returns="list<mixed>"
    badge="Chunking"
    desc="Splits long text into multiple sequential messages sent to the target chat without breaking words or mangling newlines."
  />
  <ApiCard
    sig="bindDefault(string $param, callable $resolver)"
    returns="static"
    desc="Binds a custom contextual resolver for any Bot API method parameter (e.g. auto-injecting custom tenant or business connection IDs)."
  />
</ApiGroup>

---

### H. Bot API Method Calls & File Operations

<ApiGroup description="Direct Bot API calls, explicit Method execution, file downloads, and payload parsing.">
  <ApiCard
    sig="$bot->sendMessage(mixed ...$args)"
    returns="mixed"
    badge="Dynamic"
    desc="All Telegram Bot API methods are callable dynamically with full named argument support and automatic contextual parameter injection."
  />
  <ApiCard
    sig="send(Method $method, ?Closure $uploadProgress = null, ?Closure $downloadProgress = null, ?RequestOptions $options = null)"
    returns="mixed"
    desc="Executes an explicit Method instance with optional progress callbacks and per-request timeout/proxy options."
  />
  <ApiCard
    sig="downloadFile(mixed $file, mixed $destination, ?callable $progress = null)"
    returns="BooleanResult|Error"
    desc="Downloads a file from Telegram servers (by file_id, File object, or path) directly to disk or stream with download progress tracking."
  />
  <ApiCard
    sig="parseUpdate(string|array $payload)"
    returns="Update"
    desc="Parses a raw webhook JSON payload string or decoded array into a fully typed Update object."
  />
</ApiGroup>

---

### I. Underlying Subsystems & Dependency Injection

<ApiGroup description="Direct access to decoupled client subsystems and PSR-11 container integration via PHP 8.4 property hooks.">
  <ApiCard
    type="property"
    sig="$bot->client"
    returns="TelegramClient"
    badge="Property"
    desc="Returns the pure TelegramClient instance to execute Bot API requests directly, bypassing update processing."
  />
  <ApiCard
    type="property"
    sig="$bot->dispatcher"
    returns="UpdateDispatcher"
    badge="Property"
    desc="Returns the underlying UpdateDispatcher instance managing handlers and catchers."
  />
  <ApiCard
    type="property"
    sig="$bot->context"
    returns="ContextResolver"
    badge="Property"
    desc="Returns the ContextResolver instance for registering or inspecting contextual defaults."
  />
  <ApiCard
    sig="setContainer(mixed $container)"
    returns="static"
    desc="Configures a PSR-11 container or callable resolver used for dependency injection in controllers, handlers, and flows."
  />
  <ApiCard
    type="property"
    sig="$bot->container"
    returns="mixed"
    badge="Property Hook"
    desc="Returns the configured PSR-11 dependency injection container or container resolver."
  />
  <ApiCard
    type="property"
    sig="$bot->flowManager"
    returns="FlowManager"
    badge="Property Hook"
    desc="Returns the underlying FlowManager state orchestrator managing storage drivers and transition hooks."
  />
  <ApiCard
    type="property"
    sig="$bot->router"
    returns="Router"
    badge="Property Hook"
    desc="Returns the underlying Router instance for custom route group manipulation."
  />
  <ApiCard
    sig="scoped(?Update $update = null)"
    returns="static"
    badge="Concurrency"
    desc="Spawns an isolated, thread-safe clone of the Telegram bot client with dedicated context for persistent worker engines (FrankenPHP, RoadRunner, Swoole, Octane)."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/configuration
# Section: Getting Started > Configuration
# ==============================================================================

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

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

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

<ApiGroup description="Endpoints, bot tokens, and sandbox testing server flags.">
  <ApiCard
    sig="withToken(string $token)"
    returns="static"
    badge="default: ''"
    desc="Your Telegram Bot API token obtained from @BotFather."
  />
  <ApiCard
    sig="withApiServer(string $url)"
    returns="static"
    badge="default: 'https://api.telegram.org'"
    desc="Custom or self-hosted Telegram Bot API server base URL. Essential for transferring files up to 2GB, higher throughput, or internal networks."
  />
  <ApiCard
    sig="withTestEnvironment(bool $enabled = true)"
    returns="static"
    badge="default: false"
    desc="Switches the target endpoint to Telegram's dedicated Test Server Environment (/test) for sandbox testing."
  />
</ApiGroup>

---

### ⚡ HTTP Client, Networking & Transport

<ApiGroup description="Timeouts, proxies, custom HTTP clients, and persistent connection pooling.">
  <ApiCard
    sig="withTimeout(float $seconds)"
    returns="static"
    badge="default: 30.0"
    desc="Maximum execution timeout for HTTP requests in seconds. For long-polling or large video uploads, consider increasing to 60.0 or higher."
  />
  <ApiCard
    sig="withConnectTimeout(float $seconds)"
    returns="static"
    badge="default: 10.0"
    desc="Connection timeout for opening TCP/TLS sockets to the Telegram API in seconds."
  />
  <ApiCard
    sig="withProxy(?string $proxy)"
    returns="static"
    badge="default: null"
    desc="HTTP, HTTPS, or SOCKS5 proxy URL (e.g. socks5h://127.0.0.1:9050 or http://proxy.corp.internal:8080)."
  />
  <ApiCard
    sig="withVerifySsl(bool|string $verifySsl = true)"
    returns="static"
    badge="default: false"
    desc="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."
  />
  <ApiCard
    sig="withHttpClient(?HttpClientInterface $client)"
    returns="static"
    badge="default: GuzzleHttpClient"
    desc="Custom HTTP client implementation implementing HttpClientInterface."
  />
  <ApiCard
    sig="withCurlClient(bool $persistent = true)"
    returns="static"
    badge="default: true"
    desc="High-performance native PHP 8.5 client utilizing persistent cURL share handles (curl_share_init_persistent()). Eliminates repetitive TLS handshakes and DNS lookups."
  />
</ApiGroup>

---

### 📊 Progress Tracking Callbacks

<ApiGroup description="Granular upload and download event listeners for media and documents.">
  <ApiCard
    sig="withUploadProgress(?Closure $callback)"
    returns="static"
    badge="default: null"
    desc="Event callback invoked during file uploads (e.g. sending videos, documents, or photo albums)."
  />
  <ApiCard
    sig="withDownloadProgress(?Closure $callback)"
    returns="static"
    badge="default: null"
    desc="Event callback invoked during file downloads via $bot->downloadFile()."
  />
</ApiGroup>

#### Progress Callback Signature
Both progress callbacks receive three informative parameters:

```php
$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

<ApiGroup description="Dual error modes: traditional exceptions vs. typed Error objects.">
  <ApiCard
    sig="withErrorHandlingMode(ErrorHandlingMode $mode)"
    returns="static"
    badge="default: EXCEPTION"
    desc="Switches between traditional exception throwing (EXCEPTION) and typed Error object returns (ERROR_OBJECT)."
  />
  <ApiCard
    sig="withErrorObjectMode(array $catchExceptions = [ApiException::class])"
    returns="static"
    badge="default: [ApiException::class]"
    desc="Activates error object mode and specifies which exception classes should be converted into returned Error objects."
  />
  <ApiCard
    sig="withExceptionMode()"
    returns="static"
    badge="mode: exception"
    desc="Restores the default exception-throwing behavior for all errors."
  />
  <ApiCard
    sig="withCatchAllErrors()"
    returns="static"
    badge="mode: catch-all"
    desc="Catches all \Throwable instances (including connection resets, DNS failures, and timeout exceptions) as Error objects."
  />
  <ApiCard
    sig="withConvertExceptions(array $classes)"
    returns="static"
    badge="list<class-string<Throwable>>"
    desc="Defines the specific list of exception classes to catch and convert to Error objects."
  />
</ApiGroup>

---

### 🚀 Running Modes & Resiliency

<ApiGroup description="Default bot runner selection, long-polling parameters, webhook security, and retry policies.">
  <ApiCard
    sig="withRunningMode(?RunningModeInterface $mode)"
    returns="static"
    badge="default: WebhookMode"
    desc="Configures the default bot execution runner: new WebhookMode(...), new PollingMode(...), or new AutoMode(...)."
  />
  <ApiCard
    sig="withPollingMode(PollingMode $mode)"
    returns="static"
    badge="PollingMode"
    desc="Convenience shortcut to configure long-polling mode with custom batch limits, timeout, backoff, and process concurrency."
  />
  <ApiCard
    sig="withWebhookMode(WebhookMode $mode)"
    returns="static"
    badge="WebhookMode"
    desc="Convenience shortcut to configure webhook mode with secret token verification and non-blocking safe responses."
  />
  <ApiCard
    sig="withAutoMode(?PollingMode $polling = null, ?WebhookMode $webhook = null, bool $autoDeleteWebhook = false, bool $dropPendingUpdatesOnDelete = false, ?callable $detector = null)"
    returns="static"
    badge="AutoMode"
    desc="Configures adaptive AutoMode to seamlessly switch between CLI Polling and HTTP Webhook execution with optional webhook cleanup and custom environment detection."
  />
  <ApiCard
    sig="withRetryCount(int $count)"
    returns="static"
    badge="default: 3"
    desc="Number of automatic retries on rate limits (429 Too Many Requests with retry_after) or transient network dropouts."
  />
</ApiGroup>

---

### 🔄 Conversation Flow & Orchestration

<ApiGroup description="Root/home flow defaults and update filtering for multi-step flows.">
  <ApiCard
    sig="withRootFlow(?string $flowClass)"
    returns="static"
    badge="?class-string<Flow>"
    desc="Specifies the root/home Flow class. Automatically redirected to on /start, home navigation actions, or as a graceful recovery fallback."
  />
  <ApiCard
    sig="withDefaultFlow(?string $flowClass)"
    returns="static"
    badge="Alias"
    aliasFor="withRootFlow()"
    desc="Shorthand alias for withRootFlow()."
  />
  <ApiCard
    sig="withFlowAllowedUpdates(array $types)"
    returns="static"
    badge="default: [] (all updates)"
    desc="Sets the global default allowed update types for conversation flows. An empty array permits all updates. Disallowed updates bypass the flow."
  />
</ApiGroup>

---

### 📋 Logging & Observability

<ApiGroup description="PSR-3 logger integration for HTTP diagnostics, telemetry, and debugging.">
  <ApiCard
    sig="withLogger(?LoggerInterface $logger)"
    returns="static"
    badge="default: null"
    desc="PSR-3 compliant logger (e.g. Monolog) for logging outbound API requests, response payloads, rate limits, and retries."
  />
</ApiGroup>

---

### 💉 Dependency Injection & Container

<ApiGroup description="PSR-11 container integration for automatic dependency injection.">
  <ApiCard
    sig="withContainer(mixed $container)"
    returns="static"
    badge="PSR-11 / callable"
    desc="PSR-11 container (or callable resolver) used to instantiate controller classes, handler classes in $bot->run(...), and multi-step Flow classes."
  />
</ApiGroup>

---

### ⚡ Client Instantiation Shortcuts

<ApiGroup description="Direct construction shortcuts from the builder.">
  <ApiCard
    sig="client()"
    returns="Telegram"
    badge="Factory"
    desc="Directly constructs and returns an initialized Telegram client instance without having to manually call new Telegram($builder->build())."
  />
  <ApiCard
    sig="make()"
    returns="Telegram"
    badge="Alias"
    aliasFor="client()"
    desc="Shorthand alias for client()."
  />
</ApiGroup>

---

## 🧬 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:

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

<ApiGroup description="Computed URL and RFC 3986 URI properties available on Config instances.">
  <ApiCard
    type="property"
    sig="public string $baseApiUrl"
    returns="string"
    badge="Property Hook"
    desc="Fully qualified Telegram Bot API base URL (e.g. 'https://api.telegram.org/bot<token>')."
  />
  <ApiCard
    type="property"
    sig="public string $baseFileUrl"
    returns="string"
    badge="Property Hook"
    desc="Fully qualified Telegram File download base URL (e.g. 'https://api.telegram.org/file/bot<token>')."
  />
  <ApiCard
    type="property"
    sig="public Uri|string $apiUri"
    returns="Uri|string"
    badge="Property Hook"
    desc="RFC 3986 URI object instance for the Bot API base endpoint."
  />
  <ApiCard
    type="property"
    sig="public Uri|string $fileUri"
    returns="Uri|string"
    badge="Property Hook"
    desc="RFC 3986 URI object instance for the File download base endpoint."
  />
</ApiGroup>

```php
$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

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

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

```php
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)

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

```php
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)

```php
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);
```


# ==============================================================================
# File: /guide/methods-and-types
# Section: Core Essentials > Calling Methods & Types
# ==============================================================================

# Calling Methods & Types

`tueen/telegram` provides native, strictly typed support for Telegram Bot API methods and types with full IDE autocompletion, enums, computed property hooks, and forward-compatible fallbacks.

---

## 🚀 1. Method Invocations

You can invoke API methods either dynamically or via dedicated Method classes:

### Dynamic Method Calls (Recommended)

Call any Telegram method directly using camelCase and named arguments:

```php
use Tueen\Telegram\Enums\ParseMode;

$message = $bot->sendMessage(
    chatId: 12345678,
    text: "Hello from <b>Tueen</b>!",
    parseMode: ParseMode::HTML // Direct Enum instance
);
```

::: tip Recommended: Use PHP Named Arguments
In `tueen/telegram`, **always invoke API methods using PHP named arguments** (`paramName: $value`).

```php
// ✅ RECOMMENDED: Explicit, readable, and order-independent
$bot->sendMessage(
    text: "Welcome to our bot!",
    parseMode: ParseMode::HTML
);

// ❌ AVOID: Fragile positional arguments
$bot->sendMessage(123456, "Hello", null, null, null, null, 'HTML');
```

#### Why Named Arguments Are Recommended:
1. **Contextual Auto-Injection:** Because parameters like `chatId`, `businessConnectionId`, and query IDs are automatically inferred from the active update, named arguments allow you to supply only the parameters you need (e.g. `text: "..."`) without worrying about parameter position.
2. **No Trailing Nulls:** Telegram Bot API methods accept dozens of optional parameters. Named arguments eliminate the need for long lists of `null` placeholders.
3. **Forward-Compatibility:** When Telegram adds new parameters to Bot API methods, named arguments prevent positional shift bugs.
4. **Self-Documenting:** Code is clear and easy to read during code review.
:::

Full IDE autocompletion and parameter docblocks are provided via the `@mixin \Tueen\Telegram\Contracts\TelegramMethods` contract.

### Method Objects (For Custom Pipelines & Architecture)

Every Telegram Bot API method has a dedicated class in `Tueen\Telegram\Methods`:

```php
use Tueen\Telegram\Methods\SendMessage;

$method = new SendMessage(
    chatId: 12345678,
    text: "Hello from Tueen!"
);

$message = $bot->send($method);
```

### Forward-Compatible Unknown / New Parameters

If Telegram introduces a new parameter before the library updates, you can pass it immediately as a named parameter or via variadic `$extra`:

```php
// If Telegram adds 'new_feature_flag' tomorrow:
$message = $bot->sendMessage(
    chatId: 12345678,
    text: "Testing new feature",
    newFeatureFlag: true // Seamlessly passed to the API
);
```

### Passing Complex & Nested Types (Objects or Arrays)

Methods that accept complex structures (such as `reply_markup`, `link_preview_options`, or `reply_parameters`) accept both **strongly-typed Type objects** and **associative arrays**:

#### A. Using Strongly-Typed Type Objects
```php
use Tueen\Telegram\Types\InlineKeyboardMarkup;
use Tueen\Telegram\Types\InlineKeyboardButton;
use Tueen\Telegram\Types\LinkPreviewOptions;

$bot->sendMessage(
    chatId: 123456,
    text: "Check out Tueen:",
    replyMarkup: new InlineKeyboardMarkup(
        inlineKeyboard: [
            [
                new InlineKeyboardButton(text: '🌐 Website', url: 'https://tueen.dev'),
                new InlineKeyboardButton(text: '⭐ GitHub', url: 'https://github.com/tueen/telegram'),
            ]
        ]
    ),
    linkPreviewOptions: new LinkPreviewOptions(isDisabled: true)
);
```

#### B. Using Structured Arrays
You can also pass arrays; the library automatically normalizes, converts nested objects/enums, and serializes them:
```php
$bot->sendMessage(
    chatId: 123456,
    text: "Choose an option:",
    replyMarkup: [
        'inline_keyboard' => [
            [
                ['text' => 'Option 1', 'callback_data' => 'opt_1'],
                ['text' => 'Option 2', 'callback_data' => 'opt_2'],
            ]
        ]
    ]
);
```

---

## 🏛️ 2. The Universal Base `Type` Class

All Telegram Bot API response models (over 400 types such as `Message`, `User`, `Chat`, `Update`) extend the base class `Tueen\Telegram\Types\Type`.

### Core Features of `Type`:
1. **Universal `ok(): bool` and `isOk(): bool`:** Every response object guarantees a boolean success check. Real response types always return `true`, while `Tueen\Telegram\Types\Error` objects return `false`.
2. **Dual Property Access:** Access properties using camelCase (`$message->messageId`) or snake_case (`$message->message_id`).
3. **`ArrayAccess` Support:** Access properties using bracket syntax (`$message['chat']['id']`).
4. **`JsonSerializable` & Stringable:** Passing any type to `json_encode($type)` or `(string)$type` produces clean, unescaped JSON.
5. **Array Transformation:** Call `toArray()` or `toJson()` to recursively convert the type and all nested objects into primitive arrays or JSON strings.
6. **Bulletproof Forward-Compatibility:** If Telegram introduces new fields in the future, they are preserved inside `$extra` and accessible dynamically. If Telegram returns an entirely new, unmapped object type, Tueen falls back gracefully to the base `Type` class without crashing.

---

## ⚙️ 3. The Base `Method` Class

Every Telegram Bot API method is represented by a class extending `Tueen\Telegram\Methods\Method`.

### Core Responsibilities of `Method`:
1. **Endpoint Resolution:** Defines the API method name (e.g. `'sendMessage'`).
2. **Payload Serialization:** Prepares and filters parameters, converting nested `Type` objects, Enums, and JSON-encoded fields.
3. **Multipart & File Upload Detection:** Inspects parameters for `InputFile` instances. If any file is present, `isMultipart()` returns `true` and the HTTP client uploads via `multipart/form-data`.
4. **Typed Return Resolution:** Defines `returnType()` so the HTTP client automatically instantiates and deserializes the response into the appropriate concrete `Type` (e.g. `Message::class`, `BooleanResult::class`).

---

## 🧩 4. Concerns & Computed Helpers

Rather than bloating generated classes, helper methods and computed properties are organized into reusable traits inside `Tueen\Telegram\Types\Concerns\`:

<ApiGroup description="Reusable traits enhancing generated Telegram Bot API types with computed property hooks and helpers.">
  <ApiCard
    sig="HasUpdateHelpers"
    returns="Trait on Update"
    badge="Concern Trait"
    desc="Equips Update with $type, $chatId, $userId, $messageId, $fileId, findMessage(), findUser(), findChat(), and isType()."
  />
  <ApiCard
    sig="HasMessageHelpers"
    returns="Trait on Message"
    badge="Concern Trait"
    desc="Equips Message with $isCommand, $command, $args, $textOrCaption, $fileId, $largestPhoto, isRepliedToMessage(), and findAnyText()."
  />
  <ApiCard
    sig="HasChatHelpers"
    returns="Trait on Chat"
    badge="Concern Trait"
    desc="Equips Chat with computed $fullName, $isPrivate, $isGroup, $isSupergroup, and $isChannel."
  />
  <ApiCard
    sig="HasUserHelpers"
    returns="Trait on User"
    badge="Concern Trait"
    desc="Equips User with computed $fullName and HTML $mention."
  />
  <ApiCard
    sig="HasInlineKeyboardHelpers"
    returns="Trait on InlineKeyboardMarkup"
    badge="Concern Trait"
    desc="Equips InlineKeyboardMarkup with button query and row inspection helpers."
  />
  <ApiCard
    sig="HasReplyKeyboardHelpers"
    returns="Trait on ReplyKeyboardMarkup"
    badge="Concern Trait"
    desc="Equips ReplyKeyboardMarkup with button grid inspection helpers."
  />
</ApiGroup>

> For a complete guide and code examples of these helpers, see [Update & Message Helpers](./update-and-message-helpers).

---

## 📦 5. Custom Result Wrapper Types

When Telegram Bot API methods return primitives (such as boolean values, integer counts, or plain strings), Tueen wraps them in dedicated classes inside `Tueen\Telegram\Types\Custom\` so you can always check `$result->ok()`:

- **`BooleanResult`** (e.g. from `setWebhook`, `deleteMessage`, `pinChatMessage`): Wraps a `bool $value`.
- **`IntegerResult`** (e.g. from `getChatMemberCount`): Wraps an `int $value`.
- **`StringResult`** (e.g. from `exportChatInviteLink`, `createInvoiceLink`): Wraps a `string $value`.
- **`ArrayResult<T>`** (e.g. from `getUpdates`, `forwardMessages`): An iterable collection wrapping arrays of typed objects.
- **`InputFile`**: Universal multipart file wrapper for uploads (`fromPath`, `fromResource`, `fromString`, `fromStream`).

---

## 🧭 6. Methods & Types API Reference

Below is the comprehensive catalog of core methods and properties across the Base `Type`, Base `Method`, Contextual Auto-Injection, and Custom Wrapper types.

### 🏛️ Base `Type` Class (`Tueen\Telegram\Types\Type`)

<ApiGroup description="Universal base class for all 400 Telegram Bot API response types with dual error handling, serialization, and ArrayAccess.">
  <ApiCard
    sig="ok(): bool"
    returns="bool"
    badge="Universal Check"
    desc="Determines whether the API response succeeded. Always returns true for valid Type instances and false for Error objects."
  />
  <ApiCard
    sig="isOk(): bool"
    returns="bool"
    badge="Alias"
    aliasFor="ok()"
    desc="Shorthand alias for ok() adhering to standard boolean accessor naming."
  />
  <ApiCard
    type="property"
    sig="public array $rawData"
    returns="array"
    badge="Property Hook"
    desc="Virtual property returning the original raw payload array received from Telegram API."
  />
  <ApiCard
    type="property"
    sig="protected(set) array $raw"
    returns="array"
    badge="Asymmetric Visibility"
    desc="Internal raw array populated during type construction."
  />
  <ApiCard
    sig="toArray(): array"
    returns="array"
    badge="Serialization"
    desc="Recursively converts the type instance and all nested Type objects and Enums into a clean associative array."
  />
  <ApiCard
    sig="toJson(int $flags = JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT): string"
    returns="string"
    badge="Serialization"
    desc="Serializes the type instance into formatted JSON."
  />
  <ApiCard
    sig="offsetGet(mixed $offset): mixed"
    returns="mixed"
    badge="ArrayAccess"
    desc="ArrayAccess getter supporting snake_case field access (e.g. $message['chat']['id'])."
  />
  <ApiCard
    sig="offsetExists(mixed $offset): bool"
    returns="bool"
    badge="ArrayAccess"
    desc="ArrayAccess isset check for verifying whether a property exists."
  />
  <ApiCard
    sig="offsetSet(mixed $offset, mixed $value): void"
    returns="void"
    badge="ArrayAccess"
    desc="ArrayAccess setter for modifying or injecting dynamic fields."
  />
  <ApiCard
    sig="offsetUnset(mixed $offset): void"
    returns="void"
    badge="ArrayAccess"
    desc="ArrayAccess unsetter for clearing fields."
  />
</ApiGroup>

---

### ⚙️ Base `Method` Class (`Tueen\Telegram\Methods\Method`)

<ApiGroup description="Base request class for all 150 Telegram Bot API methods handling multipart encoding and serialization.">
  <ApiCard
    sig="endpoint(): string"
    returns="string"
    badge="Contract"
    desc="Returns the Telegram Bot API endpoint method name (e.g. 'sendMessage', 'sendPhoto')."
  />
  <ApiCard
    sig="getPayload(): array"
    returns="array"
    badge="Contract"
    desc="Prepares and serializes method parameters into a normalized array ready for JSON or multipart transmission."
  />
  <ApiCard
    sig="hasUploads(): bool"
    returns="bool"
    badge="Multipart"
    desc="Detects whether any parameter contains an InputFile or file stream requiring multipart/form-data encoding."
  />
  <ApiCard
    sig="isMultipart(): bool"
    returns="bool"
    badge="Alias"
    aliasFor="hasUploads()"
    desc="Convenience alias to check if request must be dispatched using multipart encoding."
  />
  <ApiCard
    sig="returnType(): string"
    returns="class-string"
    badge="Contract"
    desc="Returns the concrete Type class name to deserialize the response into (e.g. Message::class, BooleanResult::class)."
  />
</ApiGroup>

---

### 🎯 Contextual Parameter Auto-Injection

<ApiGroup description="Repetitive parameters automatically resolved and injected from the active Update when omitted from method calls.">
  <ApiCard
    sig="chat_id"
    returns="int|string"
    badge="Contextual"
    desc="Inferred from active message, callback query, business message, channel post, or reaction."
  />
  <ApiCard
    sig="business_connection_id"
    returns="string"
    badge="Contextual"
    desc="Inferred from incoming business connection or business message update."
  />
  <ApiCard
    sig="message_thread_id"
    returns="int"
    badge="Contextual"
    desc="Inferred from forum topic thread ID on incoming message."
  />
  <ApiCard
    sig="user_id"
    returns="int"
    badge="Contextual"
    desc="Inferred from acting user (for getUserProfilePhotos, getUserGifts, etc.)."
  />
  <ApiCard
    sig="message_id"
    returns="int"
    badge="Contextual"
    desc="Inferred from primary message (for deleteMessage, pinChatMessage, etc.)."
  />
  <ApiCard
    sig="inline_message_id"
    returns="string"
    badge="Contextual"
    desc="Inferred from inline callback queries for editMessageText, editMessageReplyMarkup, etc."
  />
  <ApiCard
    sig="callback_query_id"
    returns="string"
    badge="Contextual"
    desc="Inferred query ID for answerCallbackQuery(text: 'Done!')."
  />
  <ApiCard
    sig="inline_query_id"
    returns="string"
    badge="Contextual"
    desc="Inferred query ID for answerInlineQuery(results: [...])."
  />
  <ApiCard
    sig="shipping_query_id"
    returns="string"
    badge="Contextual"
    desc="Inferred query ID for answerShippingQuery(ok: true)."
  />
  <ApiCard
    sig="pre_checkout_query_id"
    returns="string"
    badge="Contextual"
    desc="Inferred query ID for answerPreCheckoutQuery(ok: true)."
  />
</ApiGroup>

---

### 📦 Custom Wrapper Types (`Tueen\Telegram\Types\Custom\`)

<ApiGroup description="Typed wrappers for primitive results and multipart file transfers.">
  <ApiCard
    type="property"
    sig="public readonly bool $value"
    returns="bool"
    badge="BooleanResult"
    desc="Underlying boolean outcome for methods like deleteMessage, setWebhook, or pinChatMessage."
  />
  <ApiCard
    type="property"
    sig="public readonly int $value"
    returns="int"
    badge="IntegerResult"
    desc="Underlying integer counter for methods like getChatMemberCount."
  />
  <ApiCard
    type="property"
    sig="public readonly string $value"
    returns="string"
    badge="StringResult"
    desc="Underlying string for methods like exportChatInviteLink or createInvoiceLink."
  />
  <ApiCard
    sig="InputFile::fromPath(string $path, ?string $filename = null, ?string $contentType = null): self"
    returns="InputFile"
    badge="InputFile Factory"
    desc="Creates a multipart file upload wrapper from a local filesystem path."
  />
  <ApiCard
    sig="InputFile::fromResource(resource $resource, string $filename, ?string $contentType = null): self"
    returns="InputFile"
    badge="InputFile Factory"
    desc="Creates a multipart file upload wrapper from an open PHP stream resource (e.g. fopen)."
  />
  <ApiCard
    sig="InputFile::fromString(string $contents, string $filename, ?string $contentType = null): self"
    returns="InputFile"
    badge="InputFile Factory"
    desc="Creates an in-memory multipart file upload wrapper from raw string contents."
  />
  <ApiCard
    sig="InputFile::fromStream(StreamInterface $stream, string $filename, ?string $contentType = null): self"
    returns="InputFile"
    badge="InputFile Factory"
    desc="Creates a multipart file upload wrapper from any PSR-7 StreamInterface instance."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/keyboards
# Section: Core Essentials > Fluent Keyboard Builders
# ==============================================================================

# Fluent Keyboard Builders

`tueen/telegram` provides modern, fluent builders for creating both **Inline Keyboards** (`InlineKeyboardMarkup`) and **Reply Keyboards** (`ReplyKeyboardMarkup` / `ReplyKeyboardRemove`).

---

## 🔘 1. Inline Keyboards (`InlineKeyboard`)

Inline keyboards appear directly attached to a specific message. Buttons trigger actions such as callback queries, opening URLs, launching Telegram Web Apps, or initiating payments.

### Basic Usage

Use `InlineKeyboard::make()` followed by rows and buttons:

```php
use Tueen\Telegram\Keyboards\InlineKeyboard;

$keyboard = InlineKeyboard::make()
    ->row()
        ->callback('👍 Like', 'action:like')
        ->callback('👎 Dislike', 'action:dislike')
    ->row()
        ->url('🌐 Visit Website', 'https://tueen.org')
    ->build();

$bot->sendMessage(
    chatId: $chatId,
    text: 'Please cast your vote:',
    replyMarkup: $keyboard
);
```

### Supported Button Types

`InlineKeyboard` supports all Telegram Bot API inline button types:

```php
$keyboard = InlineKeyboard::make()
    // Callback data button
    ->callback('Confirm', 'order:confirm')

    // External URL button
    ->url('Documentation', 'https://tueen.org/docs')

    // Telegram Mini App (Web App)
    ->webApp('Open App', 'https://webapp.tueen.org')

    // Seamless Telegram Login URL
    ->loginUrl('Login with Telegram', 'https://example.com/auth/telegram')

    // Copy text to clipboard on tap
    ->copyText('Copy Promo Code', 'TUEEN-VIP-2026')

    // Telegram Payments Pay button
    ->pay('💳 Pay Now')

    // Prompt user to select a chat and paste inline query
    ->switchInlineQuery('Share with friends', 'check out this bot!')

    // Insert inline query into current chat
    ->switchInlineQueryCurrentChat('Search here', 'query')

    // Prompt user to select a specific type of chat (channel, group, etc.)
    ->switchInlineQueryChosenChat('Send to Channel', $chosenChatConfig)

    ->build();
```

### Auto-Chunking Buttons (`chunk`)

Instead of manually breaking rows with `->row()`, you can add all buttons and let `chunk($size)` automatically arrange them into neat rows:

```php
$builder = InlineKeyboard::make();

for ($i = 1; $i <= 9; $i++) {
    $builder->callback((string) $i, "num:{$i}");
}

// Automatically divides into 3 rows of 3 buttons:
$grid = $builder->chunk(3)->build();
```

---

## ⌨️ 2. Reply Keyboards (`ReplyKeyboard`)

Reply keyboards replace the user's regular keyboard with custom option buttons.

### Basic Usage

```php
use Tueen\Telegram\Keyboards\ReplyKeyboard;

$keyboard = ReplyKeyboard::make()
    ->resize() // Automatically fit buttons neatly
    ->placeholder('Select an option...')
    ->row()
        ->text('📦 My Orders')
        ->text('⚙️ Settings')
    ->row()
        ->requestContact('📱 Share Phone Number')
        ->requestLocation('📍 Share Location')
    ->build();

$bot->sendMessage(
    chatId: $chatId,
    text: 'Main Menu:',
    replyMarkup: $keyboard
);
```

### Supported Features & Button Types

```php
$keyboard = ReplyKeyboard::make()
    // Keyboard behaviors:
    ->resize(true)                  // Scale keyboard vertically to button count
    ->oneTime(true)                 // Hide keyboard after first button press
    ->persistent(true)              // Keep keyboard visible even when soft keyboard is closed
    ->selective(true)               // Show only to specific target users (e.g. in groups)
    ->placeholder('Type message...')// Placeholder text in input bar

    // Button types:
    ->text('Plain Text')
    ->requestContact('Send Contact')
    ->requestLocation('Send Location')
    ->requestPoll('Create a Quiz', type: 'quiz')
    ->requestUsers('Select Friends', requestId: 1, userIsBot: false, maxQuantity: 5)
    ->requestChat('Select Channel', requestId: 2, chatIsChannel: true)
    ->webApp('Open Mini App', 'https://webapp.tueen.org')

    ->build();
```

### Dismissing Keyboards (`ReplyKeyboard::remove`)

To hide an active reply keyboard from the user's interface:

```php
$bot->sendMessage(
    chatId: $chatId,
    text: 'Keyboard dismissed.',
    replyMarkup: ReplyKeyboard::remove()
);
```

---

## 🧭 3. Keyboard Builders API Reference

Below is the complete reference of methods available on `InlineKeyboard` and `ReplyKeyboard`.

### 🔘 `InlineKeyboard` Builder (`Tueen\Telegram\Keyboards\InlineKeyboard`)

<ApiGroup description="Fluent builder for constructing Telegram InlineKeyboardMarkup payloads.">
  <ApiCard
    sig="InlineKeyboard::make(): self"
    returns="InlineKeyboard"
    badge="Factory"
    desc="Initializes a new inline keyboard builder instance."
  />
  <ApiCard
    sig="row(): self"
    returns="self"
    badge="Layout"
    desc="Starts a new button row in the inline keyboard."
  />
  <ApiCard
    sig="callback(string $text, string $callbackData): self"
    returns="self"
    badge="Button"
    desc="Appends an inline button that sends callback_data back to the bot when clicked."
  />
  <ApiCard
    sig="url(string $text, string $url): self"
    returns="self"
    badge="Button"
    desc="Appends an inline button that opens an external HTTP/HTTPS URL in the user's browser."
  />
  <ApiCard
    sig="webApp(string $text, string $url): self"
    returns="self"
    badge="Button"
    desc="Appends an inline button that launches a Telegram Mini App (Web App) modal."
  />
  <ApiCard
    sig="loginUrl(string $text, string|LoginUrl $loginUrl): self"
    returns="self"
    badge="Button"
    desc="Appends an inline button that authorizes the user via Telegram Login Widget."
  />
  <ApiCard
    sig="copyText(string $text, string $copyText): self"
    returns="self"
    badge="Button"
    desc="Appends an inline button that copies the specified text to clipboard on tap."
  />
  <ApiCard
    sig="pay(string $text): self"
    returns="self"
    badge="Button"
    desc="Appends a Telegram Payments invoice payment button (must be the first button in first row)."
  />
  <ApiCard
    sig="switchInlineQuery(string $text, string $query = ''): self"
    returns="self"
    badge="Button"
    desc="Prompts user to select a chat and inserts '@bot query' into the chat input bar."
  />
  <ApiCard
    sig="switchInlineQueryCurrentChat(string $text, string $query = ''): self"
    returns="self"
    badge="Button"
    desc="Inserts '@bot query' directly into the current chat's input bar."
  />
  <ApiCard
    sig="chunk(int $size): self"
    returns="self"
    badge="Layout"
    desc="Automatically groups all queued buttons into uniform rows of the specified size."
  />
  <ApiCard
    sig="build(): InlineKeyboardMarkup"
    returns="InlineKeyboardMarkup"
    badge="Terminal"
    desc="Compiles and returns the finalized InlineKeyboardMarkup type instance."
  />
</ApiGroup>

---

### ⌨️ `ReplyKeyboard` Builder (`Tueen\Telegram\Keyboards\ReplyKeyboard`)

<ApiGroup description="Fluent builder for constructing Telegram ReplyKeyboardMarkup and ReplyKeyboardRemove payloads.">
  <ApiCard
    sig="ReplyKeyboard::make(): self"
    returns="ReplyKeyboard"
    badge="Factory"
    desc="Initializes a new reply keyboard builder instance."
  />
  <ApiCard
    sig="row(): self"
    returns="self"
    badge="Layout"
    desc="Starts a new button row in the reply keyboard."
  />
  <ApiCard
    sig="text(string $text): self"
    returns="self"
    badge="Button"
    desc="Appends a regular text button that sends the button text as a user message."
  />
  <ApiCard
    sig="requestContact(string $text): self"
    returns="self"
    badge="Button"
    desc="Appends a button prompting the user to share their verified phone number."
  />
  <ApiCard
    sig="requestLocation(string $text): self"
    returns="self"
    badge="Button"
    desc="Appends a button prompting the user to share their current GPS location."
  />
  <ApiCard
    sig="requestPoll(string $text, ?string $type = null): self"
    returns="self"
    badge="Button"
    desc="Appends a button allowing the user to create and send a regular poll or quiz."
  />
  <ApiCard
    sig="resize(bool $resize = true): self"
    returns="self"
    badge="Modifier"
    desc="Scales the reply keyboard vertically to fit the button rows neatly."
  />
  <ApiCard
    sig="oneTime(bool $oneTime = true): self"
    returns="self"
    badge="Modifier"
    desc="Hides the reply keyboard automatically as soon as any button is tapped."
  />
  <ApiCard
    sig="persistent(bool $persistent = true): self"
    returns="self"
    badge="Modifier"
    desc="Keeps the reply keyboard visible even when the regular software keyboard is opened or closed."
  />
  <ApiCard
    sig="placeholder(string $placeholder): self"
    returns="self"
    badge="Modifier"
    desc="Sets custom placeholder text inside the chat input bar when this keyboard is active."
  />
  <ApiCard
    sig="build(): ReplyKeyboardMarkup"
    returns="ReplyKeyboardMarkup"
    badge="Terminal"
    desc="Compiles and returns the finalized ReplyKeyboardMarkup type instance."
  />
  <ApiCard
    sig="ReplyKeyboard::remove(bool $selective = false): ReplyKeyboardRemove"
    returns="ReplyKeyboardRemove"
    badge="Removal"
    desc="Creates a ReplyKeyboardRemove instance to dismiss active reply keyboards."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/formatting
# Section: Core Essentials > Text Formatting & Escaping
# ==============================================================================

# Text Formatting & Escaping

Telegram supports rich text formatting via **HTML**, **MarkdownV2**, and legacy **Markdown**. However, unescaped characters (such as `_`, `*`, `[`, `<`, `>`, `&`) frequently cause Telegram API errors like `400 Bad Request: can't parse entities`.

`tueen/telegram` provides two complementary utilities strictly adhering to the [Telegram Bot API Formatting Options specification](https://core.telegram.org/bots/api#formatting-options):
1. **`Text` Builder**: A safe, fluent, nesting-capable builder for constructing styled messages.
2. **`Escape` Helper**: Low-level escaping functions for user-generated strings.

---

## 🎨 1. Fluent `Text` Builder

The `Text` builder lets you chain formatting methods while automatically escaping any dynamic or user-supplied variables.

### Direct API Integration

You can pass `Text` instances directly into Telegram methods like `$bot->sendMessage()` or `$bot->sendPhoto(caption: ...)`. Tueen **automatically casts the text to a string** and **auto-sets `parseMode`** to the builder's mode:

```php
use Tueen\Telegram\Formatting\Text;

// No need to manually cast (string) or specify parseMode:
$bot->sendMessage(
    chatId: $chatId,
    text: Text::html()
        ->bold('Invoice #100')->line()
        ->plain('Total: $50.00')
);
```

### HTML Formatting (`Text::html`)

```php
$message = Text::html()
    ->bold('Order Confirmation')->line()
    ->line()
    ->plain('User: ')->userMention($user->name, $user->id)->line()
    ->plain('Item: ')->bold($item->name)->line()
    ->plain('Price: ')->code("$" . number_format($item->price, 2))->line()
    ->line()
    ->blockquote('Thank you for shopping with us!')
    ->line()
    ->link('Track Package', 'https://track.example.com/12345');
```

### MarkdownV2 Formatting (`Text::markdownV2`)

You can generate MarkdownV2 without manually escaping the 18 reserved Telegram characters:

```php
$message = Text::markdownV2()
    ->bold('System Alert!')->line()
    ->spoiler('Secret token inside')->line()
    ->expandableBlockquote("Log line 1: OK\nLog line 2: WARNING\nLog line 3: SUCCESS")
    ->line()
    ->pre("<?php\necho 'Hello World!';", language: 'php');
```

---

## 🔗 2. Nested Formatting Styles

Telegram allows entities to be nested (e.g. bold italic text or links with bold labels). `Text` supports nesting using **Closures**, sub-`Text` instances, or strings:

```php
// Bold italic text: <b><i>Bold and Italic</i></b>
$text = Text::html()->bold(fn(Text $t) => $t->italic('Bold and Italic'));

// Bold spoiler in MarkdownV2: *||Secret||*
$text = Text::markdownV2()->bold(fn(Text $t) => $t->spoiler('Secret'));

// Hyperlink with bold label
$link = Text::html()->link(fn(Text $t) => $t->bold('Click Here'), 'https://example.com');
```

---

## 🛡️ 3. Low-Level Escaping with `Escape`

When constructing strings manually or templating with Blade/Twig, use `Tueen\Telegram\Formatting\Escape`:

```php
use Tueen\Telegram\Formatting\Escape;

// 1. Escaping for HTML
$safeHtml = Escape::html("<script>alert('xss');</script> & Bob");
// Returns: &lt;script&gt;alert('xss');&lt;/script&gt; &amp; Bob

// 2. Escaping for MarkdownV2 (escapes 18 reserved Telegram characters)
$safeMarkdown = Escape::markdownV2("Price is [10.00$] *special*");
// Returns: Price is \[10\.00\$\] \*special\*

// 3. Escaping URL query components
$safeUrl = Escape::urlParam("https://example.com?query=hello world");
```

---

## 🧭 4. Formatting API Catalog

Below is the complete reference of methods available on the `Text` builder and `Escape` helper.

### 🎨 `Text` Builder (`Tueen\Telegram\Formatting\Text`)

<ApiGroup description="Fluent builder for safe HTML and MarkdownV2 styled messages.">
  <ApiCard
    sig="bold(string|callable|Text $content): self"
    returns="self"
    badge="Formatting"
    desc="Wraps content in bold weight text."
  />
  <ApiCard
    sig="italic(string|callable|Text $content): self"
    returns="self"
    badge="Formatting"
    desc="Wraps content in italicized text."
  />
  <ApiCard
    sig="underline(string|callable|Text $content): self"
    returns="self"
    badge="Formatting"
    desc="Wraps content in underlined text."
  />
  <ApiCard
    sig="strikethrough(string|callable|Text $content): self"
    returns="self"
    badge="Formatting"
    desc="Wraps content in strikethrough text."
  />
  <ApiCard
    sig="spoiler(string|callable|Text $content): self"
    returns="self"
    badge="Formatting"
    desc="Wraps content in hidden spoiler tags."
  />
  <ApiCard
    sig="blockquote(string|callable|Text $content): self"
    returns="self"
    badge="Block"
    desc="Renders a block quote quotation."
  />
  <ApiCard
    sig="expandableBlockquote(string|callable|Text $content): self"
    returns="self"
    badge="Block"
    desc="Renders a collapsible expandable block quote."
  />
  <ApiCard
    sig="code(string $code): self"
    returns="self"
    badge="Inline"
    desc="Renders inline monospace code."
  />
  <ApiCard
    sig="pre(string $code, ?string $language = null): self"
    returns="self"
    badge="Block"
    desc="Renders a pre-formatted syntax code block with optional language highlighting."
  />
  <ApiCard
    sig="link(string|callable|Text $content, string $url): self"
    returns="self"
    badge="Inline"
    desc="Renders an inline hyperlink with clickable label text."
  />
  <ApiCard
    sig="userMention(string|callable|Text $content, int $userId): self"
    returns="self"
    badge="Inline"
    desc="Renders a direct user mention link targeting a Telegram user ID."
  />
  <ApiCard
    sig="customEmoji(string $emoji, string $customEmojiId): self"
    returns="self"
    badge="Inline"
    desc="Renders an animated custom Telegram emoji with its unique custom emoji ID."
  />
  <ApiCard
    sig="plain(string $text): self"
    returns="self"
    badge="Content"
    desc="Appends plain text, automatically escaping any reserved formatting characters."
  />
  <ApiCard
    sig="raw(string $string): self"
    returns="self"
    badge="Content"
    desc="Appends raw text without escaping (use only with pre-sanitized strings)."
  />
  <ApiCard
    sig="line(string|callable|Text|null $content = null): self"
    returns="self"
    badge="Layout"
    desc="Appends content followed by a newline."
  />
  <ApiCard
    sig="br(int $count = 1): self"
    returns="self"
    badge="Layout"
    desc="Appends one or more blank line breaks."
  />
  <ApiCard
    sig="hr(int $length = 25): self"
    returns="self"
    badge="Layout"
    desc="Appends a horizontal rule divider line."
  />
</ApiGroup>

---

### 🛡️ `Escape` Helper (`Tueen\Telegram\Formatting\Escape`)

<ApiGroup description="Low-level escaping routines adhering to the Telegram Bot API specification.">
  <ApiCard
    sig="Escape::html(string $text): string"
    returns="string"
    badge="Escaping"
    desc="Escapes HTML special characters (&amp;, &lt;, &gt;, &quot;) for Telegram HTML parse mode."
  />
  <ApiCard
    sig="Escape::markdownV2(string $text): string"
    returns="string"
    badge="Escaping"
    desc="Escapes all 18 reserved characters for MarkdownV2."
  />
  <ApiCard
    sig="Escape::markdown(string $text): string"
    returns="string"
    badge="Escaping"
    desc="Escapes legacy Markdown characters."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/file-upload-download
# Section: Core Essentials > File Upload & Download
# ==============================================================================

# File Upload & Download

`tueen/telegram` makes file transfers seamless using the `InputFile` wrapper, streaming HTTP transports, and real-time upload/download progress callbacks.

---

## 📤 1. File Uploads with `InputFile`

`InputFile` can wrap local files, streams, raw strings, or PSR-7 streams:

### From Local File Path
```php
use Tueen\Telegram\Types\Custom\InputFile;

$photo = InputFile::fromPath('/path/to/cat.jpg');

$bot->sendPhoto(
    chatId: 123456,
    photo: $photo,
    caption: 'My cute cat!'
);
```

### From Stream Resource
```php
$fp = fopen('https://example.com/audio.mp3', 'rb');
$audio = InputFile::fromResource($fp, 'audio.mp3');

$bot->sendAudio(
    chatId: 123456,
    audio: $audio
);
```

### From Raw In-Memory String
```php
$csv = InputFile::fromString("id,name\n1,Alice\n2,Bob", 'report.csv', 'text/csv');

$bot->sendDocument(
    chatId: 123456,
    document: $csv
);
```

---

## 🖼️ 2. Sending Media Groups (Albums)

To send multiple photos or videos as an album in a single message:

```php
$bot->sendMediaGroup(
    chatId: 123456,
    media: [
        [
            'type' => 'photo',
            'media' => 'https://example.com/photo1.jpg',
            'caption' => 'Holiday album'
        ],
        [
            'type' => 'photo',
            'media' => 'https://example.com/photo2.jpg',
        ]
    ]
);
```

---

## ⚡ 3. Real-Time Upload Progress

You can track upload progress per-request:

```php
use Tueen\Telegram\Methods\SendDocument;
use Tueen\Telegram\Types\Custom\InputFile;

$bot->send(
    new SendDocument(
        chatId: 123456,
        document: InputFile::fromPath('/path/to/large_video.mp4')
    ),
    uploadProgress: function (int $bytesUploaded, int $totalBytes, float $percentage) {
        printf("Upload: %d / %d bytes (%.2f%%)\r", $bytesUploaded, $totalBytes, $percentage);
    }
);
```

---

## 📥 4. Streaming File Downloads with Progress

Telegram allows downloading files up to 20MB (or up to 2GB when using a self-hosted Bot API server).

`$bot->downloadFile` downloads directly to a local file or stream without loading the entire payload into RAM:

```php
$bot->downloadFile(
    file: 'photos/file_0.jpg', // or File object / file_id
    destination: '/local/path/saved.jpg',
    progress: function (int $bytesDownloaded, int $totalBytes, float $percentage) {
        printf("Downloading: %.2f%%\r", $percentage);
    }
);
```

---

## 🧭 5. File Transfer API Catalog

Below is the complete reference of file transfer methods and factory functions.

### 📦 `InputFile` Wrapper (`Tueen\Telegram\Types\Custom\InputFile`)

<ApiGroup description="Universal multipart file wrapper supporting local paths, PHP streams, raw strings, and PSR-7.">
  <ApiCard
    sig="InputFile::fromPath(string $path, ?string $filename = null, ?string $contentType = null): self"
    returns="InputFile"
    badge="Factory"
    desc="Wraps a local filesystem file path. Infers filename and MIME content type automatically if omitted."
  />
  <ApiCard
    sig="InputFile::fromResource(resource $resource, string $filename, ?string $contentType = null): self"
    returns="InputFile"
    badge="Factory"
    desc="Wraps an active PHP stream resource (e.g. from fopen, php://temp) for memory-efficient streaming."
  />
  <ApiCard
    sig="InputFile::fromString(string $contents, string $filename, ?string $contentType = null): self"
    returns="InputFile"
    badge="Factory"
    desc="Wraps raw in-memory string data (e.g. generated CSV, PDF bytes, or image blobs)."
  />
  <ApiCard
    sig="InputFile::fromStream(StreamInterface $stream, string $filename, ?string $contentType = null): self"
    returns="InputFile"
    badge="Factory"
    desc="Wraps any PSR-7 StreamInterface instance for integration with Guzzle or Nyholm streams."
  />
</ApiGroup>

---

### 📥 Client Download APIs (`Telegram`)

<ApiGroup description="Streaming download methods available on the Telegram client facade.">
  <ApiCard
    sig="downloadFile(mixed $file, mixed $destination, ?callable $progress = null): BooleanResult|Error"
    returns="BooleanResult|Error"
    badge="Streaming"
    desc="Downloads a file by file_id, file path, or File object directly to local disk with optional progress tracking."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/running-modes
# Section: Updates & Routing > Running Modes
# ==============================================================================

# Running Modes

`tueen/telegram` features an elegant execution strategy separating how updates are received from how they are processed.

You can switch between **Webhook Mode** and **Long-Polling Mode** seamlessly. In all modes, incoming updates are resolved, stored in the `$bot->update` property, and dispatched to your handler(s) with full type-safety.

```mermaid
flowchart TD
    subgraph PollingComparison ["🔄 Long-Polling Mode (CLI / Development / Daemons)"]
        direction TB
        CLI["💻 PHP CLI Daemon<br/><code>php bot.php</code>"] -->|1. getUpdates timeout 30s| TG1[("☁️ Telegram Bot API")]
        TG1 -.->|2. Holds HTTP connection until update occurs| CLI
        CLI -->|3. Dispatches update to handlers & updates offset| CLI
    end

    subgraph WebhookComparison ["⚡ Webhook Mode (Production / Web Servers)"]
        direction TB
        TG2[("☁️ Telegram Bot API")] -->|1. HTTPS POST /webhook<br/><i>Header: X-Telegram-Bot-Api-Secret-Token</i>| WebServer["🌐 Web Server (Nginx / PHP-FPM / Caddy)"]
        WebServer -->|2. Validates secret & payload| TueenWeb["👑 Tueen WebhookMode"]
        TueenWeb -->|3. Dispatches Update & returns 200 OK| WebServer
    end

    subgraph AutoSelection ["🪄 AutoMode (Adaptive Execution)"]
        direction LR
        Detect{"Detect Environment"}
        Detect -->|CLI SAPI detected| PollingComparison
        Detect -->|Web SAPI detected| WebhookComparison
    end
```

---

## 🚀 Unified Execution with `$bot->run()`

The `$bot->run()` method is the central entry point for executing your bot. It inspects the configured `RunningMode` and dispatches incoming updates to your handlers.

### 1. Handler Signature
Handlers receive two parameters:
1. `Update $update` — The incoming update instance.
2. `Telegram $bot` — The `Telegram` client instance.

```php
use Tueen\Telegram\Telegram;
use Tueen\Telegram\Types\Update;

$bot = new Telegram('YOUR_BOT_TOKEN');

$bot->run(function (Update $update, Telegram $bot) {
    if ($update->message !== null) {
        $bot->sendMessage(
            chatId: $update->findChat()->id,
            text: "Hello! You said: {$update->message->findAnyText()}"
        );
    }
});
```

### 2. Invokable Handler Classes
Instead of inline closures, you can organize your logic into dedicated classes that implement `__invoke(Update $update, Telegram $bot)`:

```php
namespace App\Handlers;

use Tueen\Telegram\Telegram;
use Tueen\Telegram\Types\Update;

class CommandHandler
{
    public function __invoke(Update $update, Telegram $bot): void
    {
        $message = $update->findMessage();
        if ($message?->isCommand && $message->command === 'start') {
            $bot->sendMessage(
                chatId: $update->findChat()->id,
                text: 'Welcome to Tueen!'
            );
        }
    }
}
```

Pass the class name string directly to `run()`:

```php
$bot->run(CommandHandler::class);
```

If a PSR-11 container (or callable resolver) is configured via `$bot->setContainer($container)` or `ConfigBuilder::withContainer($container)`, Tueen will resolve handler dependencies through your container automatically.

### 3. Multiple Handlers & Middleware Chains
You can pass multiple handlers as variadic arguments or as an array. Handlers run in sequential order:

```php
$bot->run(
    AuthMiddleware::class,
    CommandHandler::class,
    function (Update $update, Telegram $bot) {
        // Fallback logger
    }
);

// Or using an array:
$bot->run([AuthMiddleware::class, CommandHandler::class]);
```

You can also pre-register handlers using the fluent `$bot->handle(...)` method:

```php
$bot
    ->handle(AuthMiddleware::class)
    ->handle(CommandHandler::class)
    ->run();
```

> [!TIP]
> If any handler explicitly returns `false`, execution of subsequent handlers in the chain will stop immediately for that update.

---

## 📦 The `$bot->update` Property

The `Telegram` client maintains an internal `$update` property that defaults to `null`:

```php
private(set) ?Update $update = null;
```

- When `run()` executes under **Webhook Mode**, the incoming update is resolved from the HTTP request and assigned to `$bot->update`.
- When `run()` executes under **Long-Polling Mode**, each received update is assigned to `$bot->update` before being passed to handlers.

```php
// In a webhook controller:
$bot->run();

// Access the resolved update directly:
$chatId = $bot->update?->findChat()?->id;
```

---

## 1. Webhook Mode (`WebhookMode`)

In production environments (Nginx, Apache, Caddy, FrankenPHP, Laravel, Symfony), bots receive updates as incoming HTTP POST requests sent by Telegram.

### Basic Setup
```php
use Tueen\Telegram\Telegram;
use Tueen\Telegram\Running\WebhookMode;
use Tueen\Telegram\Types\Update;

$bot = new Telegram('YOUR_BOT_TOKEN');

// Configure Webhook mode with optional secret token
$bot->setRunningMode(new WebhookMode(secretToken: 'your-secret-token'));

// Run and dispatch
$bot->run(function (Update $update, Telegram $bot) {
    if ($update->message) {
        $bot->sendMessage(
            chatId: $update->message->chat->id,
            text: 'Message received via Webhook!'
        );
    }
});
```

### Secret Token Verification
Telegram allows specifying a `secret_token` when setting your webhook (`setWebhook`). On every request, Telegram sends this token in the `X-Telegram-Bot-Api-Secret-Token` header.

`WebhookMode` automatically verifies this header:
```php
$mode = new WebhookMode(secretToken: 'my_super_secure_token');
$bot->setRunningMode($mode);

// If the header is missing or doesn't match, a TelegramException is thrown immediately,
// protecting your server from forged requests.
$bot->run(MyHandler::class);
```

### Fast Response (`safeResponse`)
Telegram expects your webhook endpoint to answer with an `HTTP 200 OK` within a few seconds. If your logic performs heavy tasks, call `safeResponse()` to immediately send HTTP 200 and detach the connection via `fastcgi_finish_request()`:

```php
$mode = new WebhookMode();
$mode->safeResponse(); // Sends HTTP 200, Content-Type: application/json, closes connection

// Continue heavy processing in the background:
// e.g. generate AI images, process database transactions, etc.
$bot->run(HeavyProcessingHandler::class);
```

### Integration with Frameworks (Laravel, Symfony, PSR-7)
```php
// In a Laravel Controller:
public function webhook(Request $request, Telegram $bot)
{
    $mode = new WebhookMode(
        secretToken: config('services.telegram.secret'),
        rawInput: $request->getContent(),
        headers: $request->headers->all()
    );

    $bot->setRunningMode($mode);

    $bot->run(function (Update $update, Telegram $bot) {
        // Handle update
    });

    return response()->json(['ok' => true]);
}
```

---

## 2. Long-Polling Mode (`PollingMode`)

During local development or for CLI background workers, Long-Polling continuously queries Telegram for new updates in an infinite loop.

### Continuous Listening
```php
use Tueen\Telegram\Telegram;
use Tueen\Telegram\Running\PollingMode;
use Tueen\Telegram\Types\Update;

$bot = new Telegram('YOUR_BOT_TOKEN');

// Set Polling mode
$polling = new PollingMode(
    timeout: 30,             // Long-polling timeout in seconds
    limit: 100,              // Updates per batch
    allowedUpdates: ['message', 'callback_query']
);

$bot->setRunningMode($polling);

// Starts infinite worker loop in CLI:
echo "Bot started polling...\n";
$bot->run(function (Update $update, Telegram $bot) {
    echo "Received update #{$update->updateId}\n";

    if ($update->message?->text === '/ping') {
        $bot->sendMessage(
            chatId: $update->message->chat->id,
            text: 'Pong!'
        );
    }
});
```

### Multi-Process Concurrency (`forkProcess`)
In high-throughput environments, you can process each incoming update in a separate forked process:

```php
$polling = new PollingMode(timeout: 30);

// Enable process forking (requires pcntl extension on CLI):
$polling->forkProcess(true);

$bot->setRunningMode($polling);
$bot->run(MyUpdateHandler::class);
```

When enabled, `PollingMode` forks a dedicated child process for each update (and automatically reaps completed children to avoid zombie processes). On environments where `pcntl_fork` is unavailable (e.g. Windows), it gracefully executes synchronously without crashing.

### Custom Process Dispatcher
You can customize how updates are dispatched to background processes (e.g. using worker pools, message queues, ReactPHP, Amp, or Swoole):

```php
$polling->setProcessDispatcher(function (Update $update, Telegram $bot, callable $next) {
    // E.g., dispatch to an async queue or background pool
    $next();
});
```

### Features of `PollingMode`:
1. **Automatic Offset Advancement:** Tracks `update_id + 1` automatically so updates are never processed twice.
2. **Per-Update Isolation & Resilience:** If a single update in a batch throws an uncaught exception, `PollingMode` logs the error, safely advances the offset, and continues processing remaining updates in the batch without crashing the long-polling daemon (configurable via `stopOnError(bool)`).
3. **Resilience & Backoff:** Automatically handles transient network interruptions with a configurable cooldown (`errorBackoffSeconds`).
4. **Graceful Shutdown:** You can call `$polling->stop()` from a signal handler (e.g. `SIGINT` / `SIGTERM`) to cleanly exit the polling loop.

### Manual Generator Iteration
If you prefer standard PHP `foreach` iteration:

```php
foreach ($bot->poll(timeout: 30) as $update) {
    // Process $update
}
```

---

## Native Telegram Bot API Method: `getUpdates`

The official Telegram Bot API method to fetch updates is `getUpdates` (plural). You can call it directly at any time:

```php
// Direct Telegram Bot API call:
$updatesResult = $bot->getUpdates(offset: 0, limit: 10);

if ($updatesResult->ok()) {
    foreach ($updatesResult->items as $update) {
        echo "Update ID: {$update->updateId}\n";
    }
}
```

---

## Setting Running Mode via Config

You can also define the default running mode directly within the configuration:

```php
$config = Telegram::create('YOUR_BOT_TOKEN')
    ->withRunningMode(new WebhookMode(secretToken: 'my_secret'))
    ->build();

$bot = new Telegram($config);
$bot->run(MyHandler::class);
```

---

## ⚡ AutoMode: Adaptive Execution (CLI Polling & HTTP Webhook)

`AutoMode` is an intelligent, multi-vector execution strategy that eliminates the need to maintain separate entry points for CLI development and production webhooks. It dynamically detects whether the bot is running inside a command-line terminal (`PollingMode`) or responding to an HTTP web request (`WebhookMode`).

### Key Features of `AutoMode`:
1. **Multi-Vector Environment Detection:**
   - Detects incoming HTTP requests (`$_SERVER['REQUEST_METHOD'] === 'POST'`, Telegram secret headers) even within CLI-based web workers such as **RoadRunner**, **Swoole**, or **FrankenPHP**.
   - Detects standard terminal environments (`PHP_SAPI === 'cli'`) when no HTTP request is present.
2. **Telegram Conflict Prevention (`autoDeleteWebhook`):**
   - Automatically deletes any active webhook before starting `PollingMode` to prevent Telegram's notorious `409 Conflict: can't use getUpdates method while webhook is active`.
3. **Observability & Hooks:**
   - Emits structured logs to your configured PSR-3 logger detailing which mode was selected and why.
   - Provides an `onModeResolved(fn($mode, $type, $bot) => ...)` hook for custom lifecycle logic.
4. **Convenient Fluent API:**
   - Use `Telegram::create()->withAutoMode(...)` or `$bot->autoRun()`.

### Example 1: Fluent Builder Configuration

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

$bot = Telegram::create($_ENV['TELEGRAM_BOT_TOKEN'])
    ->withPollingMode(new PollingMode(timeout: 45))
    ->withWebhookMode(new WebhookMode(secretToken: $_ENV['TELEGRAM_WEBHOOK_SECRET']))
    ->withAutoMode(autoDeleteWebhook: true) // Prevents 409 Conflict in local CLI
    ->client();

$bot->onCommand('start', function (Update $update, Telegram $bot) {
    $bot->sendMessage(text: 'Hello from AutoMode!');
});

// Single unified entry point:
// • In terminal (php bot.php): Runs continuous Long-Polling
// • Via Web Server (Nginx / Caddy / FrankenPHP): Handles incoming Webhook
$bot->run();
```

### Example 2: Quick `$bot->autoRun()` Execution

```php
use Tueen\Telegram\Telegram;

$bot = new Telegram($_ENV['TELEGRAM_BOT_TOKEN']);

$bot->onCommand('ping', fn(Update $u, Telegram $b) => $b->sendMessage(text: 'pong!'));

// Automatically configures AutoMode and executes:
$bot->autoRun();
```

---

## 🔀 PHP 8.5 Pipe Operator (`|>`) Pipelines

PHP 8.5 introduces the native **Pipe Operator (`|>`)**, enabling functional, left-to-right expression composition. In traditional PHP, processing an incoming Telegram update often results in either deeply nested function calls:

```php
// Traditional nested approach (hard to read from inside out):
respond(dispatch(authenticate(filter(parseUpdate(file_get_contents('php://input'))))));
```

or excessive intermediate temporary variables:

```php
// Traditional intermediate variables approach:
$rawPayload = file_get_contents('php://input');
$update = $bot->parseUpdate($rawPayload);
$filtered = $guard->check($update);
$response = $router->dispatch($filtered);
```

With PHP 8.5 and `tueen/telegram`'s callable-friendly design, data flows naturally as a readable, linear pipeline.

---

### 1. Fundamental Syntax & First-Class Callables

The pipe operator passes the result of the left-hand expression as the first argument to the right-hand callable. You can combine it with first-class callables (`$bot->parseUpdate(...)`) and parenthesized closures `(fn($x) => ...)`:

```php
use Tueen\Telegram\Telegram;
use Tueen\Telegram\Types\Update;

$bot = new Telegram('YOUR_BOT_TOKEN');

// Linear left-to-right transformation:
$message = file_get_contents('php://input')
    |> $bot->parseUpdate(...)
    |> (fn(Update $update) => $update->findMessage())
    |> (fn($msg) => $msg?->findAnyText());
```

---

### 2. Production Webhook Ingestion Pipeline

In a webhook controller, you can pipe raw input directly from the HTTP stream into security validation, update parsing, flow handling, and routing without intermediate state:

```php
namespace App\Controllers;

use Tueen\Telegram\Telegram;
use Tueen\Telegram\Types\Update;
use Tueen\Telegram\Exceptions\TelegramException;

class TelegramWebhookController
{
    public function __invoke(Telegram $bot): void
    {
        file_get_contents('php://input')
            // Step 1: Parse JSON into a typed Update instance (#[\NoDiscard] safe)
            |> $bot->parseUpdate(...)
            // Step 2: Set current update on client for contextual auto-fill
            |> (function (Update $update) use ($bot): Update {
                $bot->setUpdate($update);
                return $update;
            })
            // Step 3: Prioritize active conversation flows
            |> (function (Update $update) use ($bot): ?Update {
                if ($bot->flowManager->handle($update, $bot)) {
                    return null; // Flow consumed the update, halt pipeline
                }
                return $update;
            })
            // Step 4: Dispatch to attribute router if not consumed by a flow
            |> (function (?Update $update) use ($bot): void {
                if ($update !== null) {
                    $bot->router->dispatch($update);
                }
            });
    }
}
```

---

### 3. Multi-Stage Filter & Guard Pipeline

Pipelines are particularly powerful for composing modular security guards, spam filters, and bot filters:

```php
use Tueen\Telegram\Types\Update;

// Dedicated pure or callable guard functions:
$rejectBannedUsers = function (Update $update): ?Update {
    $userId = $update->findUser()?->id;
    if ($userId !== null && in_array($userId, [/* banned user IDs */], true)) {
        return null; // Halt processing for banned users
    }
    return $update;
};

$rejectOldUpdates = function (?Update $update): ?Update {
    if ($update === null) return null;
    $date = $update->findMessage()?->date;
    // Drop updates older than 2 minutes:
    if ($date !== null && (time() - $date) > 120) {
        return null;
    }
    return $update;
};

$logAudit = function (?Update $update): ?Update {
    if ($update !== null) {
        error_log("Processing Update #{$update->updateId} for Chat {$update->findChat()?->id}");
    }
    return $update;
};

// Execute complete guard pipeline:
$payload
    |> $bot->parseUpdate(...)
    |> $rejectBannedUsers
    |> $rejectOldUpdates
    |> $logAudit
    |> (fn(?Update $update) => $update ? $bot->handleUpdate($update) : null);
```

---

### 4. Direct Action & Response Pipelines

You can transform an incoming update straight into an outbound API action using PHP 8.5 pipes:

```php
use Tueen\Telegram\Types\Update;
use Tueen\Telegram\Enums\ParseMode;

file_get_contents('php://input')
    |> $bot->parseUpdate(...)
    |> (fn(Update $update) => match (true) {
        $update->message?->text === '/ping' => $bot->sendMessage(
            chatId: $update->findChat()->id,
            text: '🏓 <b>Pong!</b>',
            parseMode: ParseMode::HTML
        ),
        $update->message?->text === '/help' => $bot->sendMessage(
            chatId: $update->findChat()->id,
            text: '💡 Send me any text to echo.'
        ),
        default => null,
    });
```

---

### 5. Architectural Benefits in Tueen

1. **Zero Intermediate State:** Eliminates redundant local variables (`$raw`, `$json`, `$obj`) that pollute scope and waste memory.
2. **Left-to-Right Readability:** Reading code mirrors the natural direction of data flow: from network stream, through domain filters, to Telegram API response.
3. **Callable & Hook Synergy:** Seamlessly integrates with Tueen's first-class callable methods (`$bot->parseUpdate(...)`, `$bot->sendMessage(...)`) and property hooks.
4. **Graceful Early Exits:** Steps can return `null` or specialized result types to short-circuit subsequent stages without deeply nested `if/else` checks.

---

## 🧭 6. Running Modes API Catalog

Below is the complete reference of running mode runners and client execution methods.

### 🌐 `WebhookMode` Runner (`Tueen\Telegram\Running\WebhookMode`)

<ApiGroup description="Handles incoming HTTP webhook payloads with secret token validation and safe response rendering.">
  <ApiCard
    sig="__construct(?string $secretToken = null, bool $ipCheck = false, bool $safeResponse = true)"
    returns="WebhookMode"
    badge="Constructor"
    desc="Initializes Webhook runner. Configures Telegram X-Telegram-Bot-Api-Secret-Token validation and 200 OK output buffering."
  />
  <ApiCard
    sig="processUpdate(Telegram $bot, ?callable $handler = null): mixed"
    returns="mixed"
    badge="Execution"
    desc="Reads php://input, validates headers, parses Update, dispatches handler, and emits safe 200 OK HTTP response."
  />
</ApiGroup>

---

### 🔄 `PollingMode` Runner (`Tueen\Telegram\Running\PollingMode`)

<ApiGroup description="Continuous long-polling runner with automatic offset tracking, exponential backoff, and generator streaming.">
  <ApiCard
    sig="__construct(int $timeout = 30, int $limit = 100, ?array $allowedUpdates = null, bool $autoBackoff = true, bool $dropPendingUpdates = false, bool $forkProcess = false)"
    returns="PollingMode"
    badge="Constructor"
    desc="Configures long-polling parameters, auto-backoff on connection errors, and optional process forking."
  />
  <ApiCard
    sig="processUpdate(Telegram $bot, ?callable $handler = null): void"
    returns="void"
    badge="Execution"
    desc="Starts continuous update ingestion loop, fetching updates from Telegram and dispatching to handlers."
  />
  <ApiCard
    sig="getUpdatesGenerator(Telegram $bot): Generator<int, Update>"
    returns="Generator<int, Update>"
    badge="Streaming"
    desc="Returns a lazy PHP Generator yielding incoming Update instances one by one via long-polling."
  />
</ApiGroup>

---

### 🔀 `AutoMode` Runner (`Tueen\Telegram\Running\AutoMode`)

<ApiGroup description="Adaptive runner that automatically toggles between PollingMode in CLI and WebhookMode in HTTP.">
  <ApiCard
    sig="__construct(?PollingMode $pollingMode = null, ?WebhookMode $webhookMode = null, bool $autoDeleteWebhook = false, bool $dropPendingUpdatesOnDelete = false, ?callable $detector = null)"
    returns="AutoMode"
    badge="Constructor"
    desc="Initializes adaptive runner with optional custom child runners and webhook cleanup on CLI start."
  />
  <ApiCard
    sig="processUpdate(Telegram $bot, ?callable $handler = null): mixed"
    returns="mixed"
    badge="Execution"
    desc="Detects execution environment (CLI vs Web) and delegates execution to the appropriate child runner."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/routing
# Section: Updates & Routing > Update Routing & Attributes
# ==============================================================================

# Update Routing & Attributes

Instead of writing monolithic `switch` or `if/else` ladders inside your update handlers, `tueen/telegram` features an expressive, type-safe **Update Router**.

The router supports both **Fluent Route Definitions** and **Attribute-Driven Controllers** (via PHP 8 Attributes).

```mermaid
flowchart TD
    Update["📥 Incoming Telegram Update"] --> Router["🧭 Tueen Update Router"]

    subgraph MatchPipeline ["Matching Pipeline (Sequential Evaluation)"]
        direction TB
        M1{"1. Is Bot Command?<br/><i>/start, /help, etc.</i>"}
        M2{"2. Is Callback Query?<br/><i>inline button data</i>"}
        M3{"3. Is Regex / Text Match?<br/><i>custom patterns</i>"}
        M4{"4. Matches Specific Type?<br/><i>photos, documents, chat joins</i>"}
        
        M1 -->|No| M2
        M2 -->|No| M3
        M3 -->|No| M4
    end

    Router --> M1

    subgraph Handlers ["Target Dispatch"]
        direction TB
        H1["⚡ Command Route / #[OnCommand]"]
        H2["🔘 Callback Route / #[OnCallbackQuery]<br/><i>(Extracts parameters like {id})</i>"]
        H3["💬 Message Route / #[OnMessage]"]
        H4["📎 Type Route / #[OnUpdate]"]
        Fallback["🛡️ Fallback Handler / Next Middleware"]
    end

    M1 -->|Yes| H1
    M2 -->|Yes| H2
    M3 -->|Yes| H3
    M4 -->|Yes| H4
    M4 -->|No Match| Fallback
```

---

## ⚡ 1. Fluent Routing

You can register routes directly on your `Telegram` client instance.

```php
use Tueen\Telegram\Telegram;
use Tueen\Telegram\Types\Update;

$bot = new Telegram('YOUR_BOT_TOKEN');

// 1. Handle bot commands (/start, /help, etc.)
// Bot username (@my_bot) is stripped automatically:
$bot->onCommand('start', function (Update $update, Telegram $bot) {
    $bot->sendMessage(
        chatId: $update->findChat()->id,
        text: 'Welcome! How can I assist you today?'
    );
});

// 2. Handle callback queries with parameterized patterns
$bot->onCallbackQuery('item:{id}:details', function (Update $update, Telegram $bot, string $id) {
    $bot->answerCallbackQuery(callbackQueryId: $update->callbackQuery->id);
    $bot->sendMessage(
        chatId: $update->findChat()->id,
        text: "Viewing details for item #{$id}"
    );
});

// 3. Handle messages matching a regex pattern
$bot->onMessage('/^contact support$/i', function (Update $update, Telegram $bot) {
    $bot->sendMessage(
        chatId: $update->findChat()->id,
        text: 'A support agent will reach out shortly.'
    );
});

// 4. Handle inline queries
$bot->onInlineQuery(function (Update $update, Telegram $bot) {
    $query = $update->inlineQuery->query;
    // Answer inline query...
});

// 5. Catch-all fallback route
$bot->onFallback(function (Update $update, Telegram $bot) {
    $bot->sendMessage(
        chatId: $update->findChat()?->id,
        text: 'Sorry, I did not understand that command.'
    );
});

// Execute the bot (automatically triggers router dispatch)
$bot->run();
```

---

## 🎯 2. Parameter Extraction in Routes

The router provides first-class support for parameterized patterns using `{paramName}`:

```php
$bot->onCallbackQuery('cart:add:{productId}:{quantity}', function (
    Update $update,
    Telegram $bot,
    string $productId,
    string $quantity
) {
    // Parameters are automatically injected into the handler arguments!
});
```

You can also use full regular expressions:

```php
$bot->onCallbackQuery('/^order_(?P<action>approve|reject)_(?P<id>\d+)$/', function (
    Update $update,
    Telegram $bot,
    string $action,
    string $id
) {
    // Named regex capture groups are passed as parameters
});
```

---

## 🏛️ 3. Attribute-Driven Controllers

For medium to large applications, you can organize your routes into dedicated Controller classes decorated with PHP 8 Attributes:

### Example Controller

```php
namespace App\Controllers;

use Tueen\Telegram\Telegram;
use Tueen\Telegram\Types\Update;
use Tueen\Telegram\Routing\Attributes\OnCommand;
use Tueen\Telegram\Routing\Attributes\OnCallbackQuery;
use Tueen\Telegram\Routing\Attributes\OnMessage;
use Tueen\Telegram\Routing\Attributes\OnInlineQuery;

class ShopController
{
    #[OnCommand('shop')]
    public function openShop(Update $update, Telegram $bot): void
    {
        $bot->sendMessage(
            chatId: $update->findChat()->id,
            text: 'Welcome to our shop!'
        );
    }

    #[OnCallbackQuery('product:{id}')]
    public function showProduct(Update $update, Telegram $bot, string $id): void
    {
        $bot->answerCallbackQuery($update->callbackQuery->id);
        $bot->sendMessage(
            chatId: $update->findChat()->id,
            text: "Loading product #{$id}..."
        );
    }

    #[OnMessage('/^\$([0-9\.]+)$/')]
    public function handleTip(Update $update, Telegram $bot, string $amount): void
    {
        $bot->sendMessage(
            chatId: $update->findChat()->id,
            text: "Received tip: \${$amount}"
        );
    }

    #[OnInlineQuery]
    public function search(Update $update, Telegram $bot): void
    {
        // Handle inline query
    }
}
```

### Registering Controllers

Register controllers with `$bot->registerController(...)`:

```php
$bot->registerController(ShopController::class);
$bot->registerController(UserController::class);

$bot->run();
```

If a PSR-11 container is configured (`$bot->setContainer($container)`), controller instances and their constructor dependencies will be resolved automatically.

---

## 🧭 4. Routing API Catalog

Below is the complete reference of routing attributes and router configuration methods.

### 🏷️ Routing Attributes (`Tueen\Telegram\Routing\Attributes\`)

<ApiGroup description="Declarative attributes for decorating controller methods.">
  <ApiCard
    sig="#[OnCommand(string $command)]"
    returns="Attribute"
    badge="Attribute"
    desc="Matches Telegram bot commands (e.g. /start, /help). Bot username suffix (@bot) is handled automatically."
  />
  <ApiCard
    sig="#[OnCallbackQuery(?string $pattern = null)]"
    returns="Attribute"
    badge="Attribute"
    desc="Matches inline keyboard callback queries against an exact string, parameterized pattern ('item:{id}'), or regex."
  />
  <ApiCard
    sig="#[OnMessage(?string $pattern = null)]"
    returns="Attribute"
    badge="Attribute"
    desc="Matches text messages against an exact string, regex (/pattern/i), or matches all messages if pattern is null."
  />
  <ApiCard
    sig="#[OnInlineQuery(?string $pattern = null)]"
    returns="Attribute"
    badge="Attribute"
    desc="Matches incoming Telegram inline queries matching an optional query string pattern."
  />
  <ApiCard
    sig="#[OnUpdate(UpdateType|string $type)]"
    returns="Attribute"
    badge="Attribute"
    desc="Matches specific Telegram update types (e.g. UpdateType::CHANNEL_POST, 'chat_member', etc.)."
  />
  <ApiCard
    sig="#[Fallback]"
    returns="Attribute"
    badge="Attribute"
    desc="Marks a method as the default fallback handler when no other routes or active conversational flows match."
  />
</ApiGroup>

---

## 🚨 4. Priority Routes (Overriding Active Flows)

By default, an active conversational `Flow` session takes precedence over standard routes in `Router` to keep the user immersed in multi-step dialogues.

However, certain commands (such as `/help`, `/support`, `/cancel`, `/emergency`, or admin overrides) need to execute **even when a user is in the middle of a Flow**.

### Registering Priority Routes
Pass `priority: true` to fluent route methods or routing attributes:

```php
// 1. Fluent Priority Route:
$bot->onCommand('help', function (Update $update, Telegram $bot) {
    $bot->sendMessage(chatId: $bot->chatId, text: 'Need assistance? Contact @support.');
}, priority: true);

// 2. Attribute-Driven Priority Route:
class SupportController
{
    #[OnCommand('emergency', priority: true)]
    public function emergency(Update $update, Telegram $bot): void
    {
        $bot->sendMessage(chatId: $bot->chatId, text: 'Emergency operator notified!');
    }
}
```

### Flow Customization & Interception
When a priority route matches, Tueen offers the active Flow complete control through two lifecycle hooks:

1. **`allowsPriorityRoute(Route $route, Update $update): bool`** — Return `false` to intercept and veto the priority route, keeping execution entirely inside the Flow.
2. **`onPriorityRoute(Route $route, Update $update): void`** — Executed when the priority route is permitted to run, allowing the Flow to pause itself, clean up UI screens, or record that a global command occurred.

---

### 🛣️ `Router` Methods (`Tueen\Telegram\Routing\Router`)

<ApiGroup description="Methods on the Router instance (also proxied directly on the Telegram client facade).">
  <ApiCard
    sig="onCommand(string $command, mixed $handler, bool $priority = false): static"
    returns="static"
    badge="Registration"
    desc="Registers a route for a bot command name (e.g. 'start', '/help'). Set priority: true to allow overriding active Flows."
  />
  <ApiCard
    sig="onCallbackQuery(?string $pattern, mixed $handler, bool $priority = false): static"
    returns="static"
    badge="Registration"
    desc="Registers a route for callback queries matching an optional pattern or regex."
  />
  <ApiCard
    sig="onMessage(?string $pattern, mixed $handler, bool $priority = false): static"
    returns="static"
    badge="Registration"
    desc="Registers a route for messages matching an optional pattern or regex."
  />
  <ApiCard
    sig="onInlineQuery(?string $pattern, mixed $handler, bool $priority = false): static"
    returns="static"
    badge="Registration"
    desc="Registers a route for inline queries matching an optional pattern."
  />
  <ApiCard
    sig="on(UpdateType|string $type, mixed $handler, bool $priority = false): static"
    returns="static"
    badge="Registration"
    desc="Registers a route targeting a specific UpdateType enum or string."
  />
  <ApiCard
    sig="onFallback(mixed $handler): static"
    returns="static"
    badge="Registration"
    desc="Registers a fallback handler when no other routes or active conversational flows match."
  />
  <ApiCard
    sig="registerController(string|object $controller): static"
    returns="static"
    badge="Registration"
    desc="Registers an attribute-decorated controller class name or object instance."
  />
  <ApiCard
    sig="dispatch(Update $update, ?Telegram $bot = null): bool"
    returns="bool"
    badge="Execution"
    desc="Dispatches an incoming update to the first matching route. Returns true if handled."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/update-and-message-helpers
# Section: Updates & Routing > Update & Message Helpers
# ==============================================================================

# Update & Message Helpers

`tueen/telegram` provides helper methods and computed properties on `Update`, `Message`, `Chat`, and `User` objects to simplify event processing and eliminate boilerplate null checks.

---

## ⚡ 1. Update Helpers (`Update`)

### Checking Update Types (`isType`)
The `Update` object exposes a `$type` property and a variadic `isType` method that accepts multiple enums or string names:

```php
use Tueen\Telegram\Enums\UpdateType;

// Check single type:
if ($update->type === UpdateType::MESSAGE) {
    // Normal user message
}

// Check against multiple types at once:
if ($update->isType(UpdateType::MESSAGE, UpdateType::EDITED_MESSAGE)) {
    // Message or edited message
}

// Check by string values:
if ($update->isType('callback_query', 'message')) {
    // Matches callback_query or message
}
```

### Smart In-Memory Model Finders
Unlike direct properties (such as `$update->message` which is only set on standard messages), smart finders search across all branches of the incoming update payload (including edited messages, channel posts, callback queries, and business messages):

```php
// 1. Find the primary Message:
$message = $update->findMessage();

// 2. Find the acting User:
$user = $update->findUser();
echo "User: {$user?->fullName} (@{$user?->username})\n";

// 3. Find the target Chat:
$chat = $update->findChat();
echo "Chat: {$chat?->fullName} (ID: {$chat?->id})\n";
```

### ID & File Shortcut Finders
Quickly extract IDs directly from the update without chaining null-safe calls:

```php
$userId    = $update->findUserId();    // Returns ?int
$chatId    = $update->findChatId();    // Returns ?int
$messageId = $update->findMessageId(); // Returns ?int
$fileId    = $update->findFileId();    // Returns ?string (or $update->fileId)
$bizConnId = $update->findBusinessConnectionId(); // Returns ?string
$threadId  = $update->findMessageThreadId();      // Returns ?int
```

### Modern PHP 8.4 Property Hooks
Using PHP 8.4 property hooks, you can access these values directly as properties without invoking methods:

```php
$chatId    = $update->chatId;
$userId    = $update->userId;
$messageId = $update->messageId;
$bizId     = $update->businessConnectionId;
$threadId  = $update->messageThreadId;
$cbQueryId = $update->callbackQueryId;
$inlineId  = $update->inlineMessageId;
```

---

## 🌐 2. Client-Level Contextual Shortcuts (`Telegram` & `Context`)

The `Telegram` client facade and `Context` instance expose modern PHP 8.4 Property Hooks that proxy the active update without empty parentheses:

```php
// Active Contextual ID Properties
$chatId = $bot->chatId;
$userId = $bot->userId;
$msgId  = $bot->messageId;
$bizId  = $bot->businessConnectionId;

// Model objects
$user    = $bot->user;    // ?User
$chat    = $bot->chat;    // ?Chat
$message = $bot->message; // ?Message
```

---

## 💬 3. Message Helpers (`Message`)

### Checking Message Types (`isType` & `isMessage`)
Check message contents using property hooks or the variadic `isType` / `isMessage` helpers:

```php
use Tueen\Telegram\Enums\MessageType;

// Direct property:
if ($message->type === MessageType::TEXT) {
    // Plain text
}

// Variadic check for multiple message types:
if ($message->isMessage(MessageType::TEXT, MessageType::PHOTO, MessageType::DOCUMENT)) {
    // Message has text, photo, or document
}

// Check by string names:
if ($message->isType('photo', 'video')) {
    // Media message
}
```

### Checking Replies (`isRepliedToMessage`)
Determine whether a message is a reply to another message, or specifically a reply to a particular message ID or object:

```php
// Check if message is a reply to any message:
if ($message->isRepliedToMessage()) {
    echo "This is a reply to message #{$message->replyToMessage?->messageId}\n";
}

// Check if message is a reply to a specific message ID:
if ($message->isRepliedToMessage(12345)) {
    echo "User replied specifically to message #12345\n";
}

// Check if message is a reply to a specific Message object:
if ($message->isRepliedToMessage($promptMessage)) {
    echo "User replied to the prompt message\n";
}
```

### Extracting Any Text, Caption, or Rich Text (`findAnyText`)
Text content in Telegram can reside in several places:
- Standard messages use `text`
- Media messages (photos, videos, documents) use `caption`
- Formatted rich messages use `rich_message` with structured blocks

Use `$message->findAnyText()` (or `$message->findText()`) to retrieve whatever text content is present:

```php
// Returns text, caption, or recursively extracted text from rich message blocks (or null)
$text = $message->findAnyText();
```

### Media & File ID Extraction (`findFileId` & `findLargestPhoto`)
Telegram media messages attach files across different properties (`photo`, `video`, `document`, `audio`, `voice`, `animation`, `sticker`, `paidMedia`, etc.).

Use `$message->findFileId()` (or `$message->fileId`) to immediately obtain the active `file_id`:

```php
// Automatically inspects photo, video, document, audio, voice, animation, sticker, etc.
$fileId = $message->findFileId(); // or $message->fileId

// For photos with multiple resolutions, findFileId() automatically resolves the highest resolution:
if ($message->isType(MessageType::PHOTO)) {
    $largeFileId = $message->findFileId();
    
    // You can also retrieve the largest PhotoSize object directly:
    $largestPhoto = $message->findLargestPhoto(); // or $message->largestPhoto
    echo "Dimensions: {$largestPhoto->width}x{$largestPhoto->height}\n";
}
```

### Bot Command Parsing
Extract commands and their arguments with built-in property hooks:

```php
if ($message->isCommand()) {
    // Extract clean command name (strips slash and @botusername) via property hook
    // E.g. '/ban@my_bot 123 spam' -> 'ban'
    $command = $message->command;

    // Extract command arguments as array of strings via property hook
    // E.g. ['123', 'spam']
    $args = $message->args;

    switch ($command) {
        case 'start':
            $bot->sendMessage(chatId: $message->chat->id, text: 'Welcome!');
            break;

        case 'ban':
            $targetUserId = (int)($args[0] ?? 0);
            $reason = $args[1] ?? 'None';
            // execute ban...
            break;
    }
}
```

---

## 👤 4. Chat & User Helpers

### Automatic `fullName`
`Chat` and `User` models provide an automatic `$fullName` property:

```php
// On Chat: Returns title for groups/channels, or "first_name last_name" for private chats
echo $chat->fullName;

// On User: Returns "first_name last_name" (or just first_name)
echo $user->fullName;
```

---

## 🧭 5. Complete Helpers API Catalog

Below is the complete reference of all computed property hooks and helper methods provided by the `HasUpdateHelpers`, `HasMessageHelpers`, `HasChatHelpers`, and `HasUserHelpers` traits.

### ⚡ `Update` Helpers (`HasUpdateHelpers`)

<ApiGroup description="Computed property hooks and multi-branch finders available on every Update instance.">
  <ApiCard
    type="property"
    sig="public ?UpdateType $type"
    returns="?UpdateType"
    badge="Property Hook"
    desc="Active update type classified into an UpdateType backed enum."
  />
  <ApiCard
    type="property"
    sig="public ?int $chatId"
    returns="?int"
    badge="Property Hook"
    desc="Resolved Telegram Chat ID extracted across all update payload branches."
  />
  <ApiCard
    type="property"
    sig="public ?int $userId"
    returns="?int"
    badge="Property Hook"
    desc="Resolved acting Telegram User ID extracted across all update payload branches."
  />
  <ApiCard
    type="property"
    sig="public ?int $messageId"
    returns="?int"
    badge="Property Hook"
    desc="Resolved primary message ID extracted across all update payload branches."
  />
  <ApiCard
    type="property"
    sig="public ?string $fileId"
    returns="?string"
    badge="Property Hook"
    desc="Resolved media file ID attached to incoming message or callback payload."
  />
  <ApiCard
    type="property"
    sig="public ?string $businessConnectionId"
    returns="?string"
    badge="Property Hook"
    desc="Resolved business connection identifier for Telegram Business updates."
  />
  <ApiCard
    type="property"
    sig="public ?int $messageThreadId"
    returns="?int"
    badge="Property Hook"
    desc="Resolved forum topic thread ID for supergroup topics."
  />
  <ApiCard
    sig="isType(UpdateType|string ...$types): bool"
    returns="bool"
    badge="Helper"
    desc="Checks whether the update matches any of the specified UpdateType enums or string names."
  />
  <ApiCard
    sig="findMessage(): ?Message"
    returns="?Message"
    badge="Smart Finder"
    desc="Inspects all update branches (message, edited_message, channel_post, callback_query->message, business_message) to find the active Message."
  />
  <ApiCard
    sig="findUser(): ?User"
    returns="?User"
    badge="Smart Finder"
    desc="Finds the acting User across messages, callbacks, inline queries, chat members, or reactions."
  />
  <ApiCard
    sig="findChat(): ?Chat"
    returns="?Chat"
    badge="Smart Finder"
    desc="Finds the target Chat across messages, channel posts, callbacks, chat join requests, or boosts."
  />
</ApiGroup>

---

### 💬 `Message` Helpers (`HasMessageHelpers`)

<ApiGroup description="Computed property hooks and payload inspection methods on Message instances.">
  <ApiCard
    type="property"
    sig="public ?MessageType $type"
    returns="?MessageType"
    badge="Property Hook"
    desc="Classifies message payload into a MessageType backed enum (TEXT, PHOTO, VIDEO, DOCUMENT, etc.)."
  />
  <ApiCard
    type="property"
    sig="public bool $isCommand"
    returns="bool"
    badge="Property Hook"
    desc="Returns true if the message begins with a Telegram bot command (/command)."
  />
  <ApiCard
    type="property"
    sig="public ?string $command"
    returns="?string"
    badge="Property Hook"
    desc="Extracted bot command name, stripped of leading slash and @botusername suffix (e.g. 'start')."
  />
  <ApiCard
    type="property"
    sig="public array $args"
    returns="array<int, string>"
    badge="Property Hook"
    desc="Extracted command arguments split by whitespace into a clean list of strings."
  />
  <ApiCard
    type="property"
    sig="public ?string $textOrCaption"
    returns="?string"
    badge="Property Hook"
    desc="Normalized text content: returns message text, media caption, or recursively extracted text from rich blocks."
  />
  <ApiCard
    type="property"
    sig="public ?string $fileId"
    returns="?string"
    badge="Property Hook"
    desc="Highest-resolution file ID extracted from photo, video, document, audio, voice, sticker, animation, or video note."
  />
  <ApiCard
    type="property"
    sig="public ?PhotoSize $largestPhoto"
    returns="?PhotoSize"
    badge="Property Hook"
    desc="Returns the highest-resolution PhotoSize instance if the message contains a photo array."
  />
  <ApiCard
    sig="isType(MessageType|string ...$types): bool"
    returns="bool"
    badge="Helper"
    desc="Checks whether the message content matches any of the given MessageType enums or string names."
  />
  <ApiCard
    sig="isRepliedToMessage(int|Message|null $target = null): bool"
    returns="bool"
    badge="Helper"
    desc="Checks whether the message is a reply to any message, or matches a specific target message ID or Message instance."
  />
  <ApiCard
    sig="findAnyText(): ?string"
    returns="?string"
    badge="Helper"
    desc="Recursively extracts text from text, caption, or rich message structured blocks."
  />
</ApiGroup>

---

### 👤 `Chat` & `User` Helpers (`HasChatHelpers` & `HasUserHelpers`)

<ApiGroup description="Computed identity and chat type property hooks on Chat and User objects.">
  <ApiCard
    type="property"
    sig="public string $fullName"
    returns="string"
    badge="Property Hook"
    desc="On User: 'First Last' or 'First'. On Chat: chat title for groups/channels, or user full name for private chats."
  />
  <ApiCard
    type="property"
    sig="public bool $isPrivate"
    returns="bool"
    badge="Property Hook"
    desc="Returns true if chat type is 'private'."
  />
  <ApiCard
    type="property"
    sig="public bool $isGroup"
    returns="bool"
    badge="Property Hook"
    desc="Returns true if chat type is 'group'."
  />
  <ApiCard
    type="property"
    sig="public bool $isSupergroup"
    returns="bool"
    badge="Property Hook"
    desc="Returns true if chat type is 'supergroup'."
  />
  <ApiCard
    type="property"
    sig="public bool $isChannel"
    returns="bool"
    badge="Property Hook"
    desc="Returns true if chat type is 'channel'."
  />
  <ApiCard
    type="property"
    sig="public ?string $mention"
    returns="?string"
    badge="Property Hook"
    desc="Returns '@username' if present, or an HTML mention link 'tg://user?id=...' otherwise."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/flow/
# Section: Conversational Flows > Flow & Interactive Screen Ecosystem
# ==============================================================================

# Flow & Interactive Screen Ecosystem

Multi-step dialogues and interactive bot screens (such as user onboarding wizards, settings panels, catalogs, e-commerce checkouts, surveys, and support ticket flows) are notoriously difficult to maintain when managed through scattered database flags, nested `if/else` statements, or naive polling handlers.

`tueen/telegram` provides a unified, two-tier architecture for conversational and interactive bot applications:
1. **[`Flow`](./conversational-flows.md):** A linear, step-by-step state machine designed for text questionnaires, registration wizards, and multi-prompt dialogues.
2. **[`InteractiveFlow`](./interactive-screens.md):** A screen-oriented, component-based engine featuring in-place message editing (zero-flicker UI updates), comprehensive lifecycle hooks, hierarchical navigation stacks (`push`/`pop`), and declarative action routing (`#[Action]`).

---

## 🏛️ Two-Tier Architecture Comparison

| Feature | Standard `Flow` | `InteractiveFlow` |
| :--- | :--- | :--- |
| **Primary Paradigm** | Linear Step-by-Step | Screen & Menu Component |
| **Message Updates** | Sends new messages on each step | Edits existing message in-place (`editMessageText`) |
| **Flicker-Free UI** | No (new messages each turn) | Yes (zero-flicker in-place transitions) |
| **Button Handling** | Manual step matching | Declarative `#[Action('pattern')]` attributes |
| **Navigation Bar** | Custom reply buttons | Built-in language-neutral buttons (`🔙` Back, `🏠` Home) |
| **Navigation Model** | Linear History Stack | Hierarchical Stack (`push` child flow / `pop` with results) |
| **Lifecycle Hooks** | `onExit` | `onCreate`, `onStart`, `onResume`, `onPause`, `beforeRender`, `afterRender`, `onUnhandled` |
| **Global Interruption** | Checked via `exitCommands` | Intercepted via `canInterrupt($update)` |

---

## 🧭 Flow Documentation Sitemap

Explore each section of the Flow ecosystem in detail:

- **[Conversational Flows (Linear Forms)](./conversational-flows.md):** Multi-step questionnaires, step navigation (`to`, `stay`, `back`), validation loops, and session data.
- **[Interactive Screens & Zero-Flicker](./interactive-screens.md):** In-place message rendering, `Screen` builder, zero-flicker transitions across flows, and error recovery.
- **[Lifecycle Hooks Reference](./lifecycle-hooks.md):** Deep-dive into `onCreate`, `onStart`, `onResume`, `onPause`, `beforeRender`, `afterRender`, and `canInterrupt`.
- **[Keyboards & Action Binding](./keyboards-and-actions.md):** Declarative `#[Action]` attributes, parameterized patterns (`item_{id}`), `#[Input]`, and keyboard switching.
- **[Navigation Stack & Root Flow](./navigation-and-stack.md):** Hierarchical flow stack (`push`/`pop`), `🔙` Back and `🏠` Home buttons, and configuring `rootFlow` with `/start`.
- **[State Storage & Drivers](./state-storage.md):** Zero-config session persistence using Memory, File, Redis, and PSR-16 cache drivers.

---

## ⚡ Quickstart: Interactive Menu

```php
use Tueen\Telegram\Flow\InteractiveFlow;
use Tueen\Telegram\Flow\Screen;
use Tueen\Telegram\Flow\Attributes\Action;
use Tueen\Telegram\Keyboards\InlineKeyboard;

class DashboardFlow extends InteractiveFlow
{
    public function render(): Screen
    {
        $status = $this->get('status', 'Active');

        return Screen::make("📊 User Dashboard\n\nCurrent Status: {$status}")
            ->inline(fn (InlineKeyboard $k) => $k
                ->action('Toggle Status', 'toggle')
                ->action('Open Settings', 'settings')
            )
            ->withNavigation(back: true, home: true);
    }

    #[Action('toggle')]
    public function toggleStatus(): void
    {
        $next = $this->get('status', 'Active') === 'Active' ? 'Paused' : 'Active';
        $this->set('status', $next);
        $this->refresh();
    }

    #[Action('settings')]
    public function openSettings(): void
    {
        $this->push(SettingsFlow::class);
    }
}
```


# ==============================================================================
# File: /guide/flow/conversational-flows
# Section: Conversational Flows > Conversational Flows (Linear Forms)
# ==============================================================================

# Conversational Flows (Linear Forms)

The base `Tueen\Telegram\Flow\Flow` class provides a linear state machine for multi-step textual dialogues, surveys, registration forms, and multi-prompt wizards.

```mermaid
flowchart TD
    Trigger(["User triggers /register or $bot->startFlow()"]) --> StepStart

    subgraph StepStart ["Step 1: start()"]
        PromptName["🤖 Bot: 'Welcome! What is your full name?'"]
    end

    StepStart --> UserEntersName[/"👤 User sends Name"/] --> StepEmail

    subgraph StepEmail ["Step 2: askEmail()"]
        CheckName{"Name length >= 2?"}
        CheckName -->|No| RepromptName["⚠️ $this->stay()<br/>'Name too short, please re-enter'"]
        RepromptName -.-> UserEntersName
        CheckName -->|Yes| PromptEmail["🤖 Bot: 'Great! What is your email address?'"]
    end

    StepEmail --> UserEntersEmail[/"👤 User sends Email"/] --> StepConfirm

    subgraph StepConfirm ["Step 3: confirm()"]
        CheckEmail{"Valid Email Regex?"}
        CheckEmail -->|No| RepromptEmail["⚠️ $this->stay()<br/>'Invalid email format, try again'"]
        RepromptEmail -.-> UserEntersEmail
        CheckEmail -->|Yes| PromptConfirm["🤖 Bot: 'Confirm details? (yes/no)'"]
        
        Decision{"User Response"}
        PromptConfirm --> Decision
        Decision -->|User sends /cancel| CancelFlow["🚫 $this->cancel()<br/><i>Triggers onExit('cancelled')</i>"]
        Decision -->|User sends 'yes'| FinishFlow["✅ $this->finish()<br/><i>Persists record & finishes</i>"]
    end
```

---

## 🏛️ Anatomy of a Conversational Flow

Every step in a `Flow` is a public method that receives the incoming Telegram `Update`:

```php
namespace App\Flows;

use Tueen\Telegram\Flow\Flow;
use Tueen\Telegram\Types\Update;

class RegistrationFlow extends Flow
{
    public function start(Update $update): void
    {
        $this->bot->sendMessage(chatId: $this->chatId, text: 'Welcome! What is your full name?');
        $this->to('askEmail');
    }

    public function askEmail(Update $update): void
    {
        $name = trim($update->findAnyText() ?? '');

        if (strlen($name) < 2) {
            $this->stay('Name must be at least 2 characters. Please try again:');
            return;
        }

        $this->set('name', $name);
        $this->bot->sendMessage(chatId: $this->chatId, text: "Nice to meet you, {$name}! What is your email?");
        $this->to('confirm');
    }

    public function confirm(Update $update): void
    {
        $email = trim($update->findAnyText() ?? '');

        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            $this->stay('Invalid email format. Please enter a valid email:');
            return;
        }

        $this->set('email', $email);
        $name = $this->get('name');

        $this->bot->sendMessage(
            chatId: $this->chatId,
            text: "✅ Registration complete for {$name} ({$email})!"
        );

        $this->finish();
    }
}
```

---

## 🧭 Step Navigation Methods

### `$this->to(string $stepMethod, array $data = []): static`
Moves the user to the specified step method on their next incoming update.
- Records the previous step in `$state->history` for back-navigation.
- Merges optional key-value `$data` into session storage.
- Automatically saves state and refreshes session TTL.

### `$this->stay(?string $replyMessage = null, mixed $keyboard = null): static`
Retains the user on the current step without appending to history.
- Sends an optional validation error prompt.
- Optionally displays a keyboard.

### `$this->back(?string $replyMessage = null): static`
Navigates to the previous step in history, or completes the flow if history is empty.

### `$this->finish(): void`
Completes the flow, removes session state from storage, and executes `onExit($update, 'finished')`.

### `$this->cancel(?string $replyMessage = 'Operation cancelled.'): void`
Cancels the flow, purges stored state, sends the optional cancellation message, and triggers `onExit($update, 'cancelled')`.

---

## 🎯 Filtering Allowed Updates (`allowedUpdates` & `#[AllowedUpdates]`)

By default, an active Flow intercepts all incoming updates for that user/chat. However, you can restrict which update types enter a Flow using either property, attribute, or global configuration:

### Using the `#[AllowedUpdates]` Attribute
```php
use Tueen\Telegram\Flow\Flow;
use Tueen\Telegram\Flow\Attributes\AllowedUpdates;
use Tueen\Telegram\Enums\UpdateType;

#[AllowedUpdates('message', 'callback_query')]
// Or with enums: #[AllowedUpdates(UpdateType::MESSAGE, UpdateType::CALLBACK_QUERY)]
class SurveyFlow extends Flow
{
    public function start(Update $update): void
    {
        // ...
    }
}
```

### Using the `$allowedUpdates` Property or Method
```php
class CustomFlow extends Flow
{
    protected array $allowedUpdates = ['message'];

    // Or dynamic check:
    public function allowsUpdate(Update $update): bool
    {
        return $update->isMessage();
    }
}
```

### Global Default via Configuration
```php
$config = Telegram::create('TOKEN')
    ->withFlowAllowedUpdates(['message', 'callback_query'])
    ->build();
```

> [!TIP]
> When an update type is not allowed for an active flow (for example, a `chat_join_request` or `inline_query`), the flow **leaves the user's active session intact** and allows the update to pass through to your regular bot routes and attribute controllers!

---

## 🕹️ External Flow Inspection & Control (`$bot->flow()`)

You can inspect and control active conversation flows from anywhere outside the flow — such as inside command handlers, route controllers, update middlewares, or background jobs.

### The Fluent `FlowSession` Interface
Call `$bot->flow()` (which automatically resolves `chatId` and `userId` from the current update), or pass explicit IDs:

```php
$bot->onCommand('status', function (Update $update, Telegram $bot) {
    $session = $bot->flow();

    if ($session->isActive) {
        $flowClass = $session->class; // e.g. App\Flows\OrderFlow
        $step = $session->step;       // e.g. 'askQuantity'
        $data = $session->data;       // ['item_id' => 42]

        $bot->sendMessage(
            chatId: $update->chat->id,
            text: "You are currently in {$flowClass} on step: {$step}"
        );
    }
});
```

### Controlling Flows from Outside
You can programmatically navigate, modify, or terminate flows:

```php
$session = $bot->flow();

// Navigate back to previous step:
$session->back('Returning to previous question...');

// Jump directly to another step:
$session->to('confirm', ['reviewed' => true]);

// Transition seamlessly to a different flow:
$session->jumpTo(HelpFlow::class);

// Reset flow back to start step and clear data:
$session->reset();

// Cancel or finish the active flow:
$session->cancel('Flow was cancelled.');
$session->finish();

// Directly mutate state data:
$session->set('discount_code', 'SUMMER2026');
$code = $session->get('discount_code');
```

### Direct Facade Shortcuts on `$bot` & `$app`
For quick checks, convenient one-line helpers are available directly on `$bot` and `$app`:

```php
if ($bot->hasActiveFlow()) {
    $activeClass = $bot->getActiveFlowClass();
    $bot->flowBack();   // Navigate back
    $bot->cancelFlow(); // Cancel active flow
    $bot->finishFlow(); // Finish active flow
}
```


# ==============================================================================
# File: /guide/flow/interactive-screens
# Section: Conversational Flows > Interactive Screens & Zero-Flicker Transitions
# ==============================================================================

# Interactive Screens & Zero-Flicker Transitions

While standard `Flow` classes handle linear textual forms, **`InteractiveFlow`** is built for rich, menu-driven bots, dashboards, e-commerce product catalogs, and interactive control panels.

---

## ⚡ Zero-Flicker In-Place Editing

Unlike other frameworks that repeatedly delete and resend messages—causing visible UI flickering and consuming redundant Telegram API calls—`InteractiveFlow` automatically tracks the active message ID (`$this->messageId`) and updates messages in-place using `editMessageText` and `editMessageReplyMarkup`.

```mermaid
sequenceDiagram
    autonumber
    actor User as 👤 Telegram User
    participant App as 📱 Telegram App
    participant TG as ☁️ Telegram Cloud API
    participant Bot as 👑 Tueen (InteractiveFlow)

    User->>App: Taps Inline Button [💳 Checkout]
    App->>TG: Send Callback Query (data: "checkout", msg_id: 420)
    TG->>Bot: Deliver Update via Webhook or Polling
    
    Note over Bot: ⚡ Zero-Flicker Transition<br/>Reuses active message ID: 420
    Bot->>TG: answerCallbackQuery(callback_query_id)
    Bot->>TG: editMessageText(chat_id, message_id: 420, newScreen)

    TG-->>App: Push Updated Content & Keyboards
    App-->>User: 🪄 Instant UI Refresh (No flicker, same message)
```

### Automatic Fallback Recovery
If in-place editing is not possible (e.g. the message was deleted by the user, the 48-hour Telegram edit window elapsed, or the screen switched from an inline keyboard to a native reply keyboard), `InteractiveFlow` gracefully falls back to sending a new message with `sendMessage`, automatically updating `$this->messageId`.

---

## 🖥️ The `Screen` Builder

The `Screen` object defines the content, formatting, keyboard markup, and navigation options for the active step:

```php
use Tueen\Telegram\Enums\ParseMode;
use Tueen\Telegram\Flow\Screen;
use Tueen\Telegram\Keyboards\InlineKeyboard;

public function render(): Screen
{
    return Screen::make("📦 *Product Catalog*\n\nChoose an item below:")
        ->parseMode(ParseMode::MARKDOWN_V2)
        ->inline(fn (InlineKeyboard $k) => $k
            ->row()
                ->action('Item 1 ($10)', 'item_1')
                ->action('Item 2 ($20)', 'item_2')
            ->row()
                ->url('Official Store', 'https://example.com')
        )
        ->withNavigation(back: true, home: true);
}
```

### Screen Builder Methods

<ApiGroup description="Methods on the Screen builder for constructing zero-flicker conversational displays.">
  <ApiCard
    sig="text(string $text): static"
    returns="static"
    badge="Content"
    desc="Sets the message body text."
  />
  <ApiCard
    sig="parseMode(ParseMode|string $mode): static"
    returns="static"
    badge="Formatting"
    desc="Sets HTML or MarkdownV2 formatting mode."
  />
  <ApiCard
    sig="inline(callable|InlineKeyboard $keyboard): static"
    returns="static"
    badge="Keyboard"
    desc="Attaches an inline keyboard with callback actions."
  />
  <ApiCard
    sig="reply(callable|ReplyKeyboard $keyboard): static"
    returns="static"
    badge="Keyboard"
    desc="Switches to native Telegram reply keyboard buttons."
  />
  <ApiCard
    sig="removeKeyboard(bool $selective = false): static"
    returns="static"
    badge="Keyboard"
    desc="Dispatches a ReplyKeyboardRemove markup."
  />
  <ApiCard
    sig="withNavigation(bool $back = true, bool $home = true): static"
    returns="static"
    badge="Navigation"
    desc="Appends language-neutral navigation buttons (🔙 Back, 🏠 Home)."
  />
  <ApiCard
    sig="editIfPossible(bool $edit = true): static"
    returns="static"
    badge="Modifier"
    desc="Enables or disables in-place message editing."
  />
</ApiGroup>

---

## 🔄 Refreshing Screens In-Place

To re-render the screen when state changes (e.g., toggling a switch or updating a counter), call `$this->refresh()`:

```php
#[Action('toggle_notify')]
public function toggleNotify(): void
{
    $current = $this->get('notify', true);
    $this->set('notify', !$current);
    
    // Immediately re-renders the screen in-place with updated state
    $this->refresh();
}
```

---

## 🔔 Native Telegram Alerts & Toasts

Instead of updating the screen text, you can display native Telegram popups in response to button clicks:

```php
#[Action('like')]
public function handleLike(): void
{
    $this->likes++;
    
    // Shows a subtle toast notification at the bottom of the user's screen:
    $this->toast('❤️ Added to favorites!');

    // Or show a modal dialog box with an OK button:
    // $this->alert('⚠️ Warning: Action requires confirmation.');

    $this->refresh();
}
```

---

## 📌 Sticky Screen / Pin to Bottom (`resendAtBottom`)

When an interactive flow accepts free-form text input from users, incoming messages push the interactive menu upward in the chat history.

Use `$this->resendAtBottom()` to delete the old message and send a fresh screen at the very bottom of the chat:

```php
#[Input]
public function handleSearchQuery(Update $update): void
{
    $query = trim($update->findAnyText() ?? '');
    $this->set('searchQuery', $query);

    // Deletes the older menu message and posts a new one at the bottom:
    $this->resendAtBottom(deleteOld: true);
}
```

---

## 🖼️ Media Screens (Photos, Videos, Animations)

`Screen` supports rich media with automatic caption editing:

```php
public function render(): Screen
{
    return Screen::make()
        ->photo('https://example.com/banner.jpg', caption: '✨ Special Offer: 50% Off!')
        ->inline(fn (InlineKeyboard $k) => $k->action('Claim Coupon', 'claim'))
        ->withNavigation(back: true, home: true);
}
```

---

## ⚠️ Confirmation Dialogs

For destructive or critical operations, invoke `$this->confirm(...)` to display an in-place confirmation prompt:

```php
#[Action('delete_item')]
public function confirmDeletion(): void
{
    $this->confirm(
        prompt: 'Are you sure you want to delete this item?',
        onConfirmedAction: 'performDeletion',
        confirmLabel: '✅ Yes, Delete',
        cancelLabel: '❌ Cancel'
    );
}

#[Action('performDeletion')]
public function performDeletion(): void
{
    $this->toast('🗑️ Item deleted successfully.');
    $this->pop();
}
```

---

## ☑️ Multi-Select Checklist Grid (`withChecklist`)

Interactive flows often need multi-select toggles (e.g. notifications settings, category filters, or item selection). `Screen::withChecklist()` builds interactive toggle button grids with automatic checkmark icons:

```php
public function render(): Screen
{
    $selected = $this->get('selected_interests', ['news', 'tech']);

    $options = [
        'news'   => 'World News',
        'tech'   => 'Technology',
        'crypto' => 'Cryptocurrency',
        'sports' => 'Sports & Fitness',
    ];

    return Screen::make("Choose your favorite topics:")
        ->withChecklist(
            options: $options,
            selectedKeys: $selected,
            actionPattern: 'toggle_interest_{key}',
            columns: 2,
            checkedIcon: '✅ ',
            uncheckedIcon: '⬜ '
        )
        ->inline(fn (InlineKeyboard $k) => $k->row()->action('Continue ➡️', 'proceed'))
        ->withNavigation(back: true, home: true);
}
```

### Toggling Checklist Items
Use `$this->toggleChecklist()` to add or remove an item key from the state array:

```php
#[Action('toggle_interest_{key}')]
public function toggleInterest(string $key): void
{
    $this->toggleChecklist('selected_interests', $key);
    $this->refresh();
}
```

---

## 🪜 Step Wizard & Progress Stepper (`withStepper`)

For multi-step onboarding, registration, or checkout forms, `Screen::withStepper()` injects a visual progress bar directly into the screen header:

```php
public function render(): Screen
{
    return Screen::make("Please enter your shipping address:")
        ->withStepper(currentStep: 2, totalSteps: 4, style: 'blocks')
        ->inline(...)
        ->withNavigation(back: true, home: false);
}
```

This prefixes your screen text with:
```text
[Step 2 of 4] 🟩🟩⬜⬜

Please enter your shipping address:
```

### Supported Stepper Styles

| Style | Pattern | Visual Output (Step 2 of 4) |
| :--- | :--- | :--- |
| `'blocks'` | `🟩` / `⬜` | `[Step 2 of 4] 🟩🟩⬜⬜` |
| `'dots'` | `●` / `○` | `[Step 2 of 4] ●●○○` |
| `'circles'` | `🟢` / `⚪` | `[Step 2 of 4] 🟢🟢⚪⚪` |
| `'numbers'` | `(X/Y)` | `[Step 2 of 4]` |

---

## 📺 Single-Screen Support & `replaceFlow()`

In interactive Telegram bots, users frequently type commands like `/start`, `/tasks`, or `/settings` while already viewing an active screen. In traditional bots, spinning up a new flow leaves redundant menu messages behind in the chat history, cluttering the conversation and breaking the single-screen paradigm.

Tueen provides first-class architectural support for **Single-Screen flows** and a dedicated `$bot->replaceFlow()` API to cleanly terminate previous screens.

### The `#[SingleScreen]` Attribute

Decorate an `InteractiveFlow` with `#[SingleScreen]` to automatically delete the previous active screen message whenever the flow starts:

```php
use Tueen\Telegram\Flow\Attributes\SingleScreen;
use Tueen\Telegram\Flow\InteractiveFlow;
use Tueen\Telegram\Flow\Screen;

#[SingleScreen]
class DashboardFlow extends InteractiveFlow
{
    public function render(): Screen
    {
        return Screen::make("👑 *Main Dashboard*")
            ->inline(...);
    }
}
```

Whenever `$bot->startFlow(DashboardFlow::class)` is invoked, Tueen inspects the current session. If a previous screen message was active, it is safely deleted with `deleteMessage(chatId, messageId)` before rendering the new screen. Any deletion failures (such as the message already being removed by the user or the 48-hour window expiring) are silently suppressed.

You can also control this behavior via the protected property or the attribute argument:

```php
// Via attribute argument
#[SingleScreen(clearPrevious: false)]
class ModalFlow extends InteractiveFlow { ... }

// Or via protected property
class CustomDashboardFlow extends InteractiveFlow
{
    protected bool $clearPreviousScreen = true;
}
```

### Dedicated `$bot->replaceFlow()` API

In command handlers (e.g. `#[OnCommand('start')]`), use `$bot->replaceFlow()` to terminate the existing flow session, delete its active screen, and start a fresh flow in a single atomic call:

```php
use Tueen\Telegram\Routing\Attributes\OnCommand;
use Tueen\Telegram\Telegram;

#[OnCommand('start')]
public function handleStart(Telegram $bot): void
{
    // Safely deletes the old screen and launches DashboardFlow
    $bot->replaceFlow(DashboardFlow::class);
}
```

If you wish to retain the previous screen message in chat history while resetting the session state, pass `deletePreviousScreen: false`:

```php
$bot->replaceFlow(DashboardFlow::class, deletePreviousScreen: false);
```

### Overriding at Runtime via `startFlow()`

You can also explicitly override screen clearing at call-time by passing `clearPreviousScreen`:

```php
// Force-clear previous screen even if the flow is not decorated with #[SingleScreen]
$bot->startFlow(SettingsFlow::class, clearPreviousScreen: true);

// Preserve previous screen even if the flow has #[SingleScreen]
$bot->startFlow(DashboardFlow::class, clearPreviousScreen: false);
```


# ==============================================================================
# File: /guide/flow/lifecycle-hooks
# Section: Conversational Flows > Lifecycle Hooks
# ==============================================================================

# Lifecycle Hooks

`InteractiveFlow` provides a predictable, component-based lifecycle. You can hook into each phase to load data, persist state, intercept exits, or update screens.

```mermaid
stateDiagram-v2
    direction TB

    [*] --> Initializing
    Initializing --> RenderingScreen: onCreate() ➔ onStart()

    state RenderingScreen {
        [*] --> PrepareScreen: beforeRender()
        PrepareScreen --> CommitTelegram: editMessageText / sendMessage
        CommitTelegram --> ScreenMounted: afterRender()
    }

    RenderingScreen --> AwaitingUserInput: Screen presented to user

    AwaitingUserInput --> SuspendedInStack: push(ChildFlow) [triggers onPause]
    SuspendedInStack --> RenderingScreen: pop(result) [triggers onResume]

    AwaitingUserInput --> RenderingScreen: Valid User Action [to / stay]
    AwaitingUserInput --> RenderingScreen: Unmatched Update [triggers onUnhandled]

    AwaitingUserInput --> Terminated: finish() / cancel() [triggers onExit]
    Terminated --> [*]
```

---

## 🪝 Lifecycle Reference

### `onCreate(): void`
Executed once when the flow instance is instantiated.
- **Use Case:** Load user profile, fetch records from a database, or initialize complex defaults.

### `onStart(): void`
Executed when entering the flow's entry point (`start`).
- **Use Case:** Reset step indicators or prepare initial parameters.

### `onResume(mixed $result = null): void`
Executed when the user returns to this flow after a child flow was popped off the stack via `$this->pop($result)`.
- **Use Case:** Process selection or return data from a sub-menu (e.g., chosen payment method or selected address) and re-render.

```php
public function onResume(mixed $result = null): void
{
    if ($result !== null) {
        $this->set('chosenAddress', $result);
    }
}
```

### `onPause(): void`
Executed immediately before this flow is suspended and a child flow is pushed onto the stack via `$this->push(...)`.
- **Use Case:** Persist transient form inputs or sync drafts.

### `beforeRender(Screen $screen): void`
Executed right before the `Screen` is rendered or edited in Telegram.
- **Use Case:** Dynamically inject badges, breadcrumbs, or user notification banners into the screen text or markup.

### `afterRender(mixed $sentMessage): void`
Executed immediately after a message is successfully sent or edited.
- **Use Case:** Audit logging or triggering secondary asynchronous tasks.

### `onUnhandled(Update $update): void`
Invoked when an incoming update does not match any registered `#[Action]`, `#[Input]`, or step method.
- **Default Behavior:** Calls `$this->refresh()` to re-render the screen in-place and keep the bot UI intact.

### `canInterrupt(Update $update): bool`
Invoked when `/start` or a cancellation command is received while the flow is active.
- **Return Value:**
  - `true` (default): Permits the user to exit or redirect to `rootFlow`.
  - `false`: Blocks the exit and keeps the user inside the flow.
- **Use Case:** Lock users into critical flows such as checkout, payment processing, or security verification.


# ==============================================================================
# File: /guide/flow/keyboards-and-actions
# Section: Conversational Flows > Keyboards & Action Binding
# ==============================================================================

# Keyboards & Action Binding

`InteractiveFlow` decouples callback routing from tedious manual string checking using modern PHP 8 attributes: `#[Action]` and `#[Input]`.

---

## 🎯 The `#[Action]` Attribute

Methods annotated with `#[Action('pattern')]` are automatically executed when the user clicks an inline keyboard button matching the specified pattern.

### 1. Literal Action Patterns
```php
use Tueen\Telegram\Flow\InteractiveFlow;
use Tueen\Telegram\Flow\Screen;
use Tueen\Telegram\Flow\Attributes\Action;
use Tueen\Telegram\Keyboards\InlineKeyboard;

class SettingsFlow extends InteractiveFlow
{
    public function render(): Screen
    {
        return Screen::make('Settings Menu')
            ->inline(fn (InlineKeyboard $k) => $k
                ->action('Toggle Dark Mode', 'toggle_dark')
                ->action('Language', 'language')
            );
    }

    #[Action('toggle_dark')]
    public function toggleDarkMode(): void
    {
        $current = $this->get('dark', false);
        $this->set('dark', !$current);
        $this->refresh();
    }
}
```

### 2. Parameterized Action Patterns
You can capture dynamic URL-style parameters in callback data using `{param}` placeholders:

```php
public function render(): Screen
{
    return Screen::make('Select an Item:')
        ->inline(fn (InlineKeyboard $k) => $k
            ->action('Item 10', 'item_10')
            ->action('Item 25', 'item_25')
        );
}

#[Action('item_{id}')]
public function selectItem(int $id): void
{
    $this->set('selected_id', $id);
    $this->push(ItemDetailsFlow::class, ['item_id' => $id]);
}
```
The parameter is automatically converted to the type hinted in the method signature (`int`, `string`, etc.).

---

## ✍️ Free-Text Inputs with `#[Input]`

If a screen needs to accept free-form text from the user while keeping the interactive screen active:

```php
use Tueen\Telegram\Flow\Attributes\Input;
use Tueen\Telegram\Types\Update;

#[Input]
public function handleTextInput(Update $update): void
{
    $query = trim($update->findAnyText() ?? '');
    $this->set('search_query', $query);
    $this->refresh();
}
```

---

## 🎛️ Switching Keyboard Types Seamlessly

`Screen` lets you switch seamlessly between inline keyboards, native reply keyboards, and removing keyboards:

```php
// Switch to a native contact sharing keyboard:
Screen::make('Please share your phone number:')
    ->reply(fn (ReplyKeyboard $k) => $k
        ->requestContact('📱 Share Contact')
        ->resize()
        ->oneTime()
    );

// Remove any existing reply keyboards:
Screen::make('Processing your request...')
    ->removeKeyboard();
```

> [!NOTE]
> Telegram's Bot API does not allow converting an inline message into a native reply keyboard via `editMessage`. When transitioning from an inline keyboard to a `ReplyKeyboard`, `InteractiveFlow` automatically sends a new message with the reply keyboard and tracks the new `$this->messageId`.

---

## 📄 Automatic Pagination Bar

When rendering paginated items or catalogues, add an automatic pagination control row directly using `withPagination()`:

```php
Screen::make("Products (Page {$page} of {$totalPages}):")
    ->inline(...)
    ->withPagination(
        currentPage: $page,
        totalPages: $totalPages,
        actionPattern: 'page_{page}', // Generates [◀️] [2/5] [▶️]
        prevLabel: '◀️',
        nextLabel: '▶️'
    )
    ->withNavigation(back: true, home: true);
```

Then bind the page action with a parameterized `#[Action]`:

```php
#[Action('page_{page}')]
public function changePage(int $page): void
{
    $this->set('currentPage', $page);
    $this->refresh();
}
```

---

## ⏱️ Action Rate-Limiting & Debouncing (`#[Debounce]`)

Users in Telegram often double-tap buttons impulsively, which can cause duplicate orders, race conditions, or duplicate payment requests.

Annotate any `#[Action]` method with `#[Debounce]` to lock rapid button clicks:

```php
use Tueen\Telegram\Flow\Attributes\Action;
use Tueen\Telegram\Flow\Attributes\Debounce;

#[Action('checkout')]
#[Debounce(seconds: 3.0, notice: '⏳ Please wait, processing your payment...', showAlert: false)]
public function handleCheckout(): void
{
    // Executes at most once every 3 seconds per user
    $this->processPayment();
}
```

- **`seconds`**: Debounce window in seconds (supports fractional seconds like `1.5`).
- **`notice`**: The toast notification or alert message shown to the user when throttled.
- **`showAlert`**: If `true`, pops up a modal alert dialog; if `false` (default), shows a non-intrusive toast popup.

---

## 🛡️ Channel Membership Guard (`#[RequireMember]`)

Gate actions or screens behind mandatory Telegram channel or supergroup subscriptions. The `#[RequireMember]` attribute verifies that the user is currently a member, administrator, or creator:

```php
use Tueen\Telegram\Flow\Attributes\Action;
use Tueen\Telegram\Flow\Attributes\RequireMember;

#[Action('claim_bonus')]
#[RequireMember(
    channel: '@tueen_channel',
    fallbackMessage: '🔒 You must join our official channel to claim this daily reward!',
    joinUrl: 'https://t.me/tueen_channel'
)]
public function claimDailyBonus(): void
{
    // Executed ONLY if the user is a member/admin/creator of @tueen_channel
    $this->grantBonus(100);
    $this->toast('🎁 Bonus claimed!');
    $this->refresh();
}
```

### Guard Workflow:
1. `InteractiveFlow` queries Telegram's `getChatMember(chat_id, user_id)`.
2. If member status is `creator`, `administrator`, or `member`, execution proceeds to the action method.
3. If not joined (or `left`, `kicked`, `restricted`), execution is halted. If `joinUrl` is specified, an inline screen with a direct "📢 Join Channel" button and a "🔄 Check Again" refresh button is automatically rendered for the user.


# ==============================================================================
# File: /guide/flow/navigation-and-stack
# Section: Conversational Flows > Navigation Stack & Root Flow
# ==============================================================================

# Navigation Stack & Root Flow

`InteractiveFlow` features a hierarchical navigation stack that models menus and multi-layered screens just like modern UI frameworks.

```mermaid
flowchart TD
    subgraph StackRepresentation ["🥞 Navigation Stack Hierarchy ($state->flowStack)"]
        direction TB
        TopScreen["🔔 NotificationsFlow<br/><b>[Active Screen]</b><br/><i>Rendered on message_id: 420</i>"]
        MidScreen["⚙️ SettingsFlow<br/><b>[Suspended Frame 1]</b><br/><i>Saved state & step memory</i>"]
        RootScreen["🏠 MainMenuFlow<br/><b>[Root Frame 0]</b><br/><i>Application Entry Point</i>"]
        
        TopScreen -->|"$this->pop('result')"| MidScreen
        MidScreen -->|"$this->pop()"| RootScreen
        TopScreen -.->|"Click 🏠 Home (Stack Reset)"| RootScreen
    end

    subgraph Transitions ["Navigation Operations"]
        direction LR
        PushOp["<b>push(Child::class, data)</b><br/>• Suspends current flow<br/>• Pushes state to stack<br/>• Reuses same message_id"]
        PopOp["<b>pop(result)</b><br/>• Drops top frame<br/>• Resumes parent flow<br/>• Calls onResume(result)"]
        HomeOp["<b>home() / 🏠</b><br/>• Purges entire stack<br/>• Restores rootFlow<br/>• Clean state slate"]
    end
```

---

## 🥞 Stack Navigation: `push()` and `pop()`

### `$this->push(string $childFlowClass, array $data = []): void`
Suspends the active flow, pushes its state onto `$state->flowStack`, and opens the child flow on the **exact same message ID** for zero-flicker transitions.

```php
#[Action('open_profile')]
public function openProfile(): void
{
    $this->push(UserProfileFlow::class, ['user_id' => 123]);
}
```

### `$this->pop(mixed $result = null): void`
Pops the active flow off the stack and restores the parent flow on the same message ID, executing the parent's `onResume($result)` hook with any returned data.

```php
#[Action('save_selection')]
public function saveSelection(): void
{
    $this->pop('English (US)');
}
```

---

## 🧭 Navigation Buttons: `🔙` Back and `🏠` Home

`Screen` includes a navigation bar with language-neutral emoji defaults:
- **Back Button:** `🔙` (triggers `$this->pop()`)
- **Home Button:** `🏠` (resets flow stack and jumps to `rootFlow`)

```php
// Enable both Back and Home:
Screen::make('Select an option:')
    ->withNavigation(back: true, home: true);

// Enable only Back:
Screen::make('Select an option:')
    ->withNavigation(back: true, home: false);

// Customizing labels:
Screen::make('Select an option:')
    ->withNavigation(
        back: true,
        home: true,
        backLabel: '🔙 Return',
        homeLabel: '🏠 Main Menu'
    );
```

> [!TIP]
> Navigation buttons work seamlessly on both **Inline Keyboards** (via callback query) and **Reply Keyboards** (via emoji text message `🔙` or `🏠`).

---

## 🏠 Configuring `rootFlow` & Handling `/start`

You can configure a global root flow on the client or FlowManager:

```php
$bot->setRootFlow(MainMenuFlow::class);

// Or through Config builder:
$config = Config::builder()
    ->token('...')
    ->rootFlow(MainMenuFlow::class)
    ->build();
```

### Global `/start` Behavior
When a user issues `/start` while in an active flow:
1. `FlowManager` checks `$activeFlow->canInterrupt($update)`.
2. If `true` (default), the entire flow stack is cleared, and the user is redirected to `rootFlow`.
3. If `false` (e.g. during checkout or an active form), the `/start` command is blocked, and the user remains safely in the active step.

---

## 🍞 Breadcrumbs Trail (`withBreadcrumbs`)

When nesting multi-level menus (e.g. `Catalog` » `Electronics` » `Headphones`), orient the user with an automatic breadcrumbs trail:

```php
use Tueen\Telegram\Flow\Attributes\Breadcrumb;

#[Breadcrumb('Headphones')]
class HeadphoneDetailsFlow extends InteractiveFlow
{
    public function render(): Screen
    {
        return Screen::make("Sony WH-1000XM5 Specs...")
            ->withBreadcrumbs(separator: ' » ')
            ->inline(...)
            ->withNavigation(back: true, home: true);
    }
}
```

This prefixes your screen text with:
```text
Catalog » Electronics » Headphones

Sony WH-1000XM5 Specs...
```

You can also customize the breadcrumb label dynamically via PHP 8.4 property hook:

```php
public string $breadcrumbTitle {
    get => $this->get('product_name', 'Item');
}
```

---

## 🛡️ Resilience & Missing Class Fallback

In long-running or distributed systems, code deployments may remove, rename, or refactor a Flow class while active users still have that Flow recorded in their persistent storage (e.g. `storage/flow/*.json` or Redis/database).

`tueen/telegram` features an intelligent, multi-layered resilience algorithm to ensure your bot never crashes or leaves users stranded:

```mermaid
flowchart TD
    Update(["Incoming User Update"]) --> ValidateClass{"Flow Class Exists<br/>in Codebase?"}

    subgraph HappyPath ["Normal Execution"]
        ValidateClass -->|Yes| ValidateStep{"Step Method<br/>Exists?"}
        ValidateStep -->|Yes| ExecStep["▶️ Execute Flow Step"]
    end

    subgraph ClassRecovery ["Class Missing (Deleted / Renamed in Deploy)"]
        ValidateClass -->|No| HasParent{"Parent Flow<br/>in Stack?"}
        HasParent -->|Yes| UnwindParent["⏪ Pop & Resume Nearest Valid Parent"]
        HasParent -->|No| HasRoot1{"rootFlow<br/>Configured?"}
    end

    subgraph StepRecovery ["Step Missing (Refactored Method)"]
        ValidateStep -->|No| TriggerHook["🔔 Trigger onMissingStep()"]
        TriggerHook --> HasHistory{"History Stack<br/>Available?"}
        HasHistory -->|Yes| StepBack["🔙 Auto Fallback: $this->back()"]
        HasHistory -->|No| HasStart{"start()<br/>Available?"}
        HasStart -->|Yes| StepStart["🔄 Reset to: $this->start()"]
        HasStart -->|No| HasRoot2{"rootFlow<br/>Configured?"}
    end

    subgraph TerminalFallback ["Root Fallback & Cleanup"]
        HasRoot1 -->|Yes| JumpRoot["🏠 Reset to rootFlow"]
        HasRoot2 -->|Yes| JumpRoot
        HasRoot1 -->|No| PurgeState["🧹 Purge Orphaned State<br/>Pass to Bot Router"]
        HasRoot2 -->|No| PurgeState
    end
```

### 1. Unwinding Navigation Stack to Parent Flows
If the user was inside a child flow (pushed via `$this->push(...)`) whose class was removed, `FlowManager` automatically inspects `$state->flowStack` and pops back to the nearest parent Flow that still exists, resuming it smoothly with its original state and `messageId`.

### 2. Fallback to `rootFlow` (Default Flow)
If the stack is empty (or parent classes were also removed), `FlowManager` checks if a `rootFlow` (or `defaultFlow`) is configured in `Config`:

```php
$config = Telegram::create('TOKEN')
    ->withRootFlow(MainMenuFlow::class) // or withDefaultFlow(MainMenuFlow::class)
    ->build();
```

When configured, the user's corrupted state is cleared and they are seamlessly redirected to the entry step of the root flow.

### 3. Missing Step Recovery (`onMissingStep`)
If a Flow class exists, but a specific step method was removed or renamed in code, `Flow::onMissingStep($step, $update)` is automatically invoked:
- It checks `$state->history` and navigates back one step.
- If history is empty, it attempts to return to the `start($update)` method.
- If a custom `$this->fallbackFlow` is set on the flow, it transitions there.
- Or it redirects to `rootFlow`.

You can also customize missing step handling directly on any Flow:

```php
class CustomFlow extends Flow
{
    protected ?string $fallbackFlow = HomeFlow::class;

    public function onMissingStep(string $step, Update $update): void
    {
        $this->bot->sendMessage(
            chatId: $this->chatId,
            text: "This section was recently updated. Taking you back..."
        );
        $this->back();
    }
}
```

### 4. Graceful Router Fallthrough
If no parent flows, root flows, or step recovery paths are available, `FlowManager` purges the orphaned session and returns `false`. This ensures the user's message is not discarded and is immediately handled by your regular command handlers, router attributes, or fallback routes.


# ==============================================================================
# File: /guide/flow/state-storage
# Section: Conversational Flows > State Storage Drivers
# ==============================================================================

# State Storage Drivers

Flow sessions and interactive screen states are persisted between updates using pluggable state storage drivers.

```mermaid
flowchart TD
    subgraph RequestCycle ["Stateful Execution in Stateless PHP"]
        direction TB
        Update["📥 Incoming Telegram Update<br/><i>(chat_id: 100, user_id: 200)</i>"] --> Resolve["🔑 Session Key Resolution<br/><code>100:200</code>"]
        Resolve --> LoadState["📖 1. Load Session<br/><code>$store->get(key)</code>"]
        LoadState --> Hydrate["🧠 Hydrate Flow Instance<br/><i>Restores current step, data & message_id</i>"]
        Hydrate --> Exec["⚙️ 2. Execute Step Method<br/><i>User mutation / step transition</i>"]
        Exec --> SaveState["💾 3. Persist Updated State<br/><code>$store->set(key, state, ttl)</code>"]
    end

    subgraph Drivers ["Pluggable Storage Drivers (StateStoreInterface)"]
        direction TB
        File["📁 FileStateStore<br/><b>Zero-config for Webhooks / FPM</b><br/><i>Atomic file locking (LOCK_EX)</i>"]
        Redis["⚡ RedisStateStore<br/><b>Distributed & Clustered</b><br/><i>High-concurrency microservices</i>"]
        Psr16["🔌 Psr16StateStore<br/><b>Framework Adapters</b><br/><i>Laravel Cache, Symfony, PSR-16</i>"]
        Memory["🧠 MemoryStateStore<br/><b>CLI & Testing</b><br/><i>Ephemeral in-process memory</i>"]
    end

    LoadState <-.-> Drivers
    SaveState -.-> Drivers
```

---

## 💾 Available Storage Drivers

### 1. `FileStateStore` (Default for Webhooks)
Zero-configuration file-based storage for webhook environments (PHP-FPM, Apache). State is safely stored in temporary session files with atomic file locking and automatic expiration.

```php
use Tueen\Telegram\Flow\Storage\FileStateStore;

$bot->setFlowStore(new FileStateStore(directory: sys_get_temp_dir() . '/tueen_flows'));
```

### 2. `MemoryStateStore` (Default for CLI Polling)
In-memory array store. Ultra-fast and optimal for long-running daemon processes or unit test suites.

```php
use Tueen\Telegram\Flow\Storage\MemoryStateStore;

$bot->setFlowStore(new MemoryStateStore());
```

### 3. `RedisStateStore` (High-Concurrency & Distributed)
Native Redis driver supporting Redis clusters, automatic TTL expiration, and cross-server session sharing.

```php
use Tueen\Telegram\Flow\Storage\RedisStateStore;

$redis = new \Redis();
$redis->connect('127.0.0.1', 6379);

$bot->setFlowStore(new RedisStateStore(redis: $redis, prefix: 'tueen:flow:'));
```

### 4. `Psr16StateStore` (Framework Adapters)
Integrates with any PSR-16 compliant cache (Laravel Cache, Symfony Cache, etc.).

```php
use Tueen\Telegram\Flow\Storage\Psr16StateStore;

$bot->setFlowStore(new Psr16StateStore($psr16CachePool));
```


# ==============================================================================
# File: /guide/app
# Section: Application & Production > Zero-Config App & Web Dashboard
# ==============================================================================

# 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
<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use Tueen\Telegram\App;

$app = App::create(__DIR__);
$app->run();
```

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

<ApiGroup description="Automatic runtime detection based on server sapi and request method.">
  <ApiCard
    sig="CLI / Terminal"
    badge="CLI Mode"
    desc="Triggered by 'php index.php'. Runs interactive Long-Polling or CLI helper commands (webhook:set, doctor, etc.)."
  />
  <ApiCard
    sig="HTTP POST (Webhook)"
    badge="Webhook Mode"
    desc="Triggered by incoming Telegram webhook requests. Validates secret_token, dispatches update handlers and flows, and returns 200 OK."
  />
  <ApiCard
    sig="HTTP GET (Browser)"
    badge="Web Dashboard"
    desc="Triggered when index.php is opened in a web browser. Launches the interactive Web Setup Wizard or live Management Console."
  />
</ApiGroup>

---

## 🌐 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 via `setWebhook()`.
- 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.
- **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:

```php
return [
    'token' => '...',
    'setup' => [
        'enabled' => true,
        'password' => 'my-secure-dashboard-password',
    ],
];
```

Or in `.env`:
```env
SETUP_PASSWORD=my-secure-dashboard-password
```

Once 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 attaches `FileStateStore`.
- Protects the directory against direct web browser access with an Apache `.htaccess` (`Deny from all`) and an `index.php` fallback (`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`:

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

```php
// 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 doctor` in 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/flow` writable).
- 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`)

<ApiGroup description="High-level application orchestrator methods and property hooks.">
  <ApiCard
    sig="App::create(string $basePath, array $config = []): static"
    returns="App"
    badge="Factory"
    desc="Initializes and boots the App instance for the given project base root path."
  />
  <ApiCard
    sig="App::boot(string $basePath, array $config = []): static"
    returns="App"
    badge="Alias"
    aliasFor="App::create()"
    desc="Expressive shorthand alias for App::create()."
  />
  <ApiCard
    type="property"
    sig="private(set) Telegram $bot"
    returns="Telegram"
    badge="Asymmetric Visibility"
    desc="Underlying Telegram client facade instance."
  />
  <ApiCard
    type="property"
    sig="public Router $router"
    returns="Router"
    badge="Property Hook"
    desc="Active update Router instance proxied directly from $bot->router."
  />
  <ApiCard
    type="property"
    sig="public FlowManager $flowManager"
    returns="FlowManager"
    badge="Property Hook"
    desc="Active FlowManager state orchestrator proxied directly from $bot->flowManager."
  />
  <ApiCard
    type="property"
    sig="private(set) string $basePath"
    returns="string"
    badge="Asymmetric Visibility"
    desc="Resolved absolute root directory path of the bot project."
  />
  <ApiCard
    type="property"
    sig="private(set) string $storagePath"
    returns="string"
    badge="Asymmetric Visibility"
    desc="Directory path for application storage ($basePath/storage)."
  />
  <ApiCard
    type="property"
    sig="private(set) string $flowStoragePath"
    returns="string"
    badge="Asymmetric Visibility"
    desc="Directory path for persistent conversational flow state files ($basePath/storage/flow)."
  />
  <ApiCard
    sig="run(mixed ...$handlers): mixed"
    returns="mixed"
    badge="Runner"
    desc="Executes the bot using adaptive environment detection (CLI polling, HTTP webhook, or Web dashboard)."
  />
  <ApiCard
    sig="reply(string|Text $text, mixed ...$args): mixed"
    returns="mixed"
    badge="Helper"
    desc="Quick reply helper to send a text message to the active chat in context."
  />
  <ApiCard
    sig="catch(string|callable $exceptionOrHandler, ?callable $handler = null): static"
    returns="static"
    badge="Error Handling"
    desc="Registers a global exception handler for incoming update processing errors."
  />
  <ApiCard
    sig="reloadConfig(array $overrides = []): static"
    returns="static"
    badge="Lifecycle"
    desc="Reloads configuration from config.php and rebuilds client and flow storage instances."
  />
</ApiGroup>

---

### 💻 CLI Administrative Commands

<ApiGroup description="Terminal operations executed via 'php index.php <command>'.">
  <ApiCard
    sig="php index.php"
    badge="CLI Command"
    desc="Starts interactive Long-Polling mode with real-time log output in terminal."
  />
  <ApiCard
    sig="php index.php webhook:set <url> [--drop]"
    badge="CLI Command"
    desc="Sets Telegram webhook URL with optional --drop flag to discard pending updates."
  />
  <ApiCard
    sig="php index.php webhook:delete [--drop]"
    badge="CLI Command"
    desc="Deletes active webhook from Telegram servers."
  />
  <ApiCard
    sig="php index.php webhook:info"
    badge="CLI Command"
    desc="Inspects current webhook status, URL, pending update count, and error telemetry."
  />
  <ApiCard
    sig="php index.php bot:info"
    badge="CLI Command"
    desc="Displays bot profile, username, Bot API ping latency, and group permissions."
  />
  <ApiCard
    sig="php index.php doctor"
    badge="CLI Command"
    desc="Runs complete system self-diagnostics (PHP version, extensions, writable storage, HTTPS)."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/pipeline-middleware
# Section: Application & Production > Pipeline & Middlewares
# ==============================================================================

# Pipeline & Middlewares

Every outbound API request in `tueen/telegram` passes through an extensible onion middleware pipeline before reaching the underlying HTTP transport. This allows you to transparently handle retries, rate limits, request logging, tracing, and metric collection.

```mermaid
flowchart LR
    subgraph ClientExecution ["Client Invocation"]
        Req["💻 Developer Calls<br/><code>$bot->sendMessage(...)</code>"]
    end

    subgraph PipelineLayers ["🧅 Extensible Middleware Onion Pipeline"]
        direction LR
        L1["📝 1. LoggingMiddleware<br/><i>Records start time, method & payload</i>"]
        L2["⏱️ 2. RateLimitMiddleware<br/><i>Token bucket check (30 req/s, 1s/chat)</i>"]
        L3["🔁 3. RetryMiddleware<br/><i>Catches 429 & network drops, auto-retries</i>"]
        
        L1 -->|Pass next| L2
        L2 -->|Pass next| L3
    end

    subgraph TransportLayer ["🌐 HTTP Transport & Cloud"]
        Transport["Client Transport<br/>(Guzzle / cURL / PSR-18)"]
        TelegramCloud[("☁️ Telegram Bot API Server")]
        
        Transport -->|HTTPS POST| TelegramCloud
    end

    Req --> L1
    L3 -->|Final dispatch| Transport
    TelegramCloud -.->|Response / Status 200| L3
    L3 -.->|Bubble response| L2
    L2 -.->|Bubble response| L1
    L1 -.->|Final Typed Result| Ret["📦 Typed Response: Message"]
```

---

## ⚡ 1. Native Built-In Middlewares

`tueen/telegram` includes three battle-tested middlewares out of the box:

### 1. `RetryMiddleware`
Automatically retries requests upon network dropouts or Telegram `429 Too Many Requests` penalties with exponential backoff and strict adherence to Telegram's `retry_after` header.

### 2. `RateLimitMiddleware`
Enforces Telegram's official rate limits locally using an in-memory token-bucket algorithm, preventing rate limit penalties before they occur:
- **Global Pacing:** Default 30 requests per second across all chats.
- **Per-Chat Pacing:** Enforces minimum interval between consecutive messages to the same chat (default: 1.0 second per chat).
- **Automatic 429 Sleep Backoff:** If Telegram still responds with 429, sleeps for `retry_after` seconds and replays automatically.

```php
use Tueen\Telegram\Telegram;
use Tueen\Telegram\Pipeline\RateLimitMiddleware;

$bot = new Telegram('YOUR_BOT_TOKEN');

// Attach rate limiter with default Telegram limits (30 req/sec, 1 sec/chat):
$bot->pipe(new RateLimitMiddleware());

// Or customize limits for high-volume broadcast bots:
$bot->pipe(new RateLimitMiddleware(
    maxRequestsPerSecond: 25.0,
    chatIntervalSeconds: 1.2,
    autoRetryOn429: true
));
```

### 3. `LoggingMiddleware`
Integrates with any PSR-3 logger (Monolog, Laravel Log, etc.) to log endpoint calls, parameters, and execution durations:

```php
use Tueen\Telegram\Pipeline\LoggingMiddleware;

$bot->pipe(new LoggingMiddleware($logger));
```

---

## 🛠️ 2. Authoring Custom Middleware

Create a class implementing `Tueen\Telegram\Pipeline\MiddlewareInterface`:

```php
namespace App\Middleware;

use Tueen\Telegram\Client\Request;
use Tueen\Telegram\Client\Response;
use Tueen\Telegram\Config;
use Tueen\Telegram\Pipeline\MiddlewareInterface;

class ExecutionTimerMiddleware implements MiddlewareInterface
{
    public function handle(Request $request, Config $config, callable $next): Response
    {
        // 1. Pre-request hook
        $startTime = hrtime(true);

        // 2. Delegate to next middleware in onion pipeline
        $response = $next($request, $config);

        // 3. Post-response hook
        $durationMs = (hrtime(true) - $startTime) / 1e6;
        error_log("API call [{$request->method}] completed in {$durationMs}ms");

        return $response;
    }
}
```

Attach your custom middleware using `$bot->pipe(...)`:

```php
$bot->pipe(new ExecutionTimerMiddleware());
```

---

## 🧭 3. Pipeline API Catalog

Below is the complete reference of built-in pipeline middlewares and registration methods.

### 🧱 Pipeline Middlewares (`Tueen\Telegram\Pipeline\`)

<ApiGroup description="Extensible middlewares for outbound Telegram Bot API requests.">
  <ApiCard
    sig="RetryMiddleware::__construct(int $maxRetries = 3, float $initialDelay = 1.0, float $multiplier = 2.0)"
    returns="RetryMiddleware"
    badge="Middleware"
    desc="Exponential backoff retry middleware with automatic retry_after parsing."
  />
  <ApiCard
    sig="RateLimitMiddleware::__construct(float $maxRequestsPerSecond = 30.0, float $chatIntervalSeconds = 1.0, bool $autoRetryOn429 = true)"
    returns="RateLimitMiddleware"
    badge="Middleware"
    desc="Token-bucket rate limiter enforcing local pacing per-second and per-chat."
  />
  <ApiCard
    sig="LoggingMiddleware::__construct(LoggerInterface $logger, string $level = 'info')"
    returns="LoggingMiddleware"
    badge="Middleware"
    desc="PSR-3 request/response logger with latency measurements and sanitized parameters."
  />
  <ApiCard
    sig="pipe(MiddlewareInterface|Closure $middleware): static"
    returns="static"
    badge="Pipeline"
    desc="Appends a middleware class instance or closure into the client's outbound request pipeline."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/error-handling-and-hooks
# Section: Application & Production > Error Handling & Lifecycle Hooks
# ==============================================================================

# Error Handling & Lifecycle Hooks

`tueen/telegram` provides a comprehensive, type-safe error handling architecture designed for PHP 8.4+ and PHP 8.5:
1. **Strongly-Typed Exceptions (Default):** Throws granular, domain-specific exceptions (`ChatNotFoundException`, `BotBlockedException`, `RateLimitException`, `CantParseEntitiesException`, etc.).
2. **Error-Object Mode:** Returns a typed `Tueen\Telegram\Types\Error` value object instead of throwing, with `TelegramErrorCode` enum reasons and helper checks.
3. **Automated Error Catalog:** Built from comprehensive Telegram Bot API error specifications with forward-compatibility fallback for unknown errors.

---

## 1. Universal `ok()` / `isOk()` Check

Every response object produced by the library inherits from [`Type`](./methods-and-types) and provides `ok(): bool` and `isOk(): bool`:

- **Successful Types (`Message`, `User`, `BooleanResult`, etc.):** Always return `true`.
- **`Error` Objects:** Always return `false`.

```php
$res = $bot->sendMessage(chatId: 12345, text: 'Hello!');

if ($res->ok()) {
    echo "Success! Message ID: {$res->messageId}\n";
} else {
    // $res is an Error object
    echo "Failed [{$res->errorCode}]: {$res->description}\n";
}
```

---

## 2. Strongly-Typed Exceptions Hierarchy

In standard exception mode, failed API requests throw specific exceptions matching the exact error returned by Telegram:

```
TelegramException
 └── ApiException
      ├── BadRequestException (400)
      │    ├── ChatNotFoundException
      │    ├── UserNotFoundException
      │    ├── MessageNotModifiedException
      │    ├── MessageNotFoundException
      │    ├── MessageCantBeDeletedException
      │    ├── MessageTooLongException
      │    ├── CantParseEntitiesException
      │    ├── CommandsListEmptyException
      │    └── ...
      ├── UnauthorizedException (401)
      ├── ForbiddenException (403)
      │    ├── BotBlockedException
      │    ├── BotKickedException
      │    ├── UserDeactivatedException
      │    └── NotEnoughRightsException
      ├── NotFoundException (404)
      ├── ConflictException (409)
      │    ├── WebhookActiveConflictException
      │    └── TerminatedByOtherGetUpdatesException
      ├── FileTooLargeException (413)
      ├── RateLimitException (429)
      └── NetworkException (cURL/connection failures)
```

### Catching Specific Exceptions

Catch the exact error condition directly without parsing strings:

```php
use Tueen\Telegram\Exceptions\BotBlockedException;
use Tueen\Telegram\Exceptions\ChatNotFoundException;
use Tueen\Telegram\Exceptions\CantParseEntitiesException;
use Tueen\Telegram\Exceptions\RateLimitException;
use Tueen\Telegram\Exceptions\BadRequestException;
use Tueen\Telegram\Exceptions\ApiException;

try {
    $bot->sendMessage(chatId: $userId, text: $markdownText, parseMode: 'MarkdownV2');
} catch (BotBlockedException $e) {
    // User blocked the bot - mark user inactive in DB
    $user->update(['is_active' => false]);
} catch (ChatNotFoundException $e) {
    // Chat or channel no longer exists
    $logger->warning("Chat {$userId} not found.");
} catch (CantParseEntitiesException $e) {
    // Markdown syntax error - fallback to plain text
    $bot->sendMessage(chatId: $userId, text: strip_tags($markdownText));
} catch (RateLimitException $e) {
    // Flood wait: inspect retryAfter duration
    sleep($e->retryAfter);
} catch (BadRequestException $e) {
    // Catch-all for any other 400 Bad Request
} catch (ApiException $e) {
    // Catch-all for any other Telegram Bot API error
}
```

---

## 3. Typed Error Reasons (`TelegramErrorCode` Enum)

All API errors are mapped to the `TelegramErrorCode` Backed Enum:

```php
use Tueen\Telegram\Enums\TelegramErrorCode;

// Match cleanly using PHP 8.4 match expression
match ($error->reason) {
    TelegramErrorCode::BotBlocked => $user->markBlocked(),
    TelegramErrorCode::ChatNotFound => $user->delete(),
    TelegramErrorCode::FloodWait => sleep($error->retryAfter),
    TelegramErrorCode::CantParseEntities => $bot->sendMessage(chatId: $chatId, text: $plain),
    default => $logger->error($error->description),
};
```

---

## 4. Error-Object Mode with Smart Helpers

To prevent API errors from throwing exceptions:

```php
use Tueen\Telegram\Telegram;
use Tueen\Telegram\Enums\TelegramErrorCode;

$bot = new Telegram(
    Telegram::create('YOUR_BOT_TOKEN')
        ->withErrorObjectMode()
        ->build()
);

$res = $bot->sendMessage(chatId: 99999, text: 'Hi');

if (!$res->ok()) {
    // 1. Inspect typed reason
    if ($res->is(TelegramErrorCode::BotBlocked)) {
        echo "User has blocked the bot.\n";
    }

    // 2. Convenience helpers
    if ($res->isChatNotFound()) { ... }
    if ($res->isBotBlocked()) { ... }
    if ($res->isRateLimit()) {
        $seconds = $res->retryAfter;
    }

    // 3. Convert to exception on demand
    $exception = $res->toException(); // returns ChatNotFoundException, etc.
}
```

---

## 5. Catch All Errors (Including Network Errors)

By default, `withErrorObjectMode()` only converts Telegram `ApiException` responses into `Error` objects.

If you also want connection drops, cURL errors, and network timeouts converted into `Error` objects:

```php
$bot = new Telegram(
    Telegram::create('YOUR_BOT_TOKEN')
        ->withCatchAllErrors()
        ->build()
);

$res = $bot->getMe();

if (!$res->ok()) {
    // Network/cURL errors receive negative error codes (e.g. -28)
    echo "Error: {$res->description} (Code: {$res->errorCode})\n";
}
```

---

## 6. Declarative `#[ApiErrors]` & Method Metadata

Every method generated by `tueen/telegram` declares its documented errors using the `#[ApiErrors]` attribute:

```php
use Tueen\Telegram\Methods\SendMessage;

$method = new SendMessage(chatId: 12345, text: 'Hello');

// Inspect expected errors programmatically
$expectedErrors = $method->expectedErrors;
// [TelegramErrorCode::ChatNotFound, TelegramErrorCode::BotBlocked, TelegramErrorCode::MessageTooLong, ...]
```

In IDEs (PhpStorm, VSCode), all methods in `TelegramMethods` and individual method classes contain `@throws` annotations for IDE autocompletion and inspection.

---

## 7. Lifecycle Event Hooks

You can register callbacks on the `Telegram` facade to observe or intercept requests and responses:

```php
$bot = new Telegram('YOUR_BOT_TOKEN');

// 1. Before sending HTTP request
$bot->onBeforeRequest(function (Request $request, Config $config) {
    // Log outbound request or attach telemetry spans
});

// 2. Immediately after raw HTTP response is received
$bot->onAfterRequest(function (Response $response, Request $request) {
    // Track HTTP status code and latency
});

// 3. When an error or exception occurs
$bot->onError(function (Throwable $error, Request $request) {
    // Send alert to Sentry, Bugsnag, or log
});

// 4. When the final result (Type or Error) is created
$bot->onResponse(function (Type $result, Request $request) {
    // Inspect the resulting Type or Error instance
});
```

---

## 8. Incoming Update Error Handling (`catch` & `onUpdateError`)

When handling incoming updates (in controllers, routes, conversation flows, or update handlers), uncaught exceptions can disrupt update dispatching if not handled. `tueen/telegram` provides first-class, bulletproof update exception handling:

### Universal Catch

Catches any `\Throwable` thrown during the processing of an incoming update:

```php
$bot->catch(function (Throwable $e, Update $update, Telegram $bot) {
    // 1. Log or report to monitoring service
    error_log("[Update {$update->updateId} Failed]: " . $e->getMessage());

    // 2. Safely reply to the user using contextual chatId
    $bot->reply('⚠️ An unexpected error occurred while processing your request.');
});
```

> [!TIP]
> You can also use `$bot->onUpdateError(...)` or `$app->catch(...)` as an identical fluent alias.

### Typed Catch (Specific Exception Filtering)

You can register granular error handlers for specific exception classes. Any unmatched exceptions will cascade to subsequent handlers or default logging:

```php
// Handles database query failures
$bot->catch(DatabaseException::class, function (DatabaseException $e, Update $update, Telegram $bot) {
    $bot->reply('Database temporarily unavailable. Please try again shortly.');
});

// Handles payment or order domain exceptions
$bot->catch(OrderExpiredException::class, function (OrderExpiredException $e, Update $update, Telegram $bot) {
    $bot->reply('Your order has expired. Please restart the checkout.');
});

// Fallback universal catch
$bot->catch(function (Throwable $e, Update $update, Telegram $bot) {
    $bot->reply('Something went wrong.');
});
```

### Quick Reply Helper (`$bot->reply`)

Inside any update handler or error handler, `$bot->reply($text, ...)` automatically resolves the active `chat_id` from the contextual update:

```php
// Automatically sends to current chat without manually extracting chatId
$bot->reply('Hello from Tueen!');

// Accepts formatted Text, keyboards, and extra API parameters
$bot->reply(
    text: Text::bold('Notice: ') . 'Service updated.',
    replyMarkup: InlineKeyboard::make()->url('Support', 'https://example.com/support')
);
```

---

## 🧭 9. Error Handling & Hooks API Catalog

Below is the complete reference of lifecycle hooks, exception catchers, and typed error inspection methods.

### 🪝 Lifecycle Request Hooks (`Telegram`)

<ApiGroup description="Hooks for intercepting outbound HTTP requests, responses, and network exceptions.">
  <ApiCard
    sig="onBeforeRequest(callable $callback): static"
    returns="static"
    badge="Lifecycle Hook"
    desc="Registers a callback (callable(Request, Config): void) executed right before an HTTP request is dispatched."
  />
  <ApiCard
    sig="onAfterRequest(callable $callback): static"
    returns="static"
    badge="Lifecycle Hook"
    desc="Registers a callback (callable(Response, Request): void) executed immediately after a raw HTTP response is received."
  />
  <ApiCard
    sig="onError(callable $callback): static"
    returns="static"
    badge="Lifecycle Hook"
    desc="Registers a callback (callable(\Throwable, Request): void) triggered whenever a request or transport error occurs."
  />
  <ApiCard
    sig="onResponse(callable $callback): static"
    returns="static"
    badge="Lifecycle Hook"
    desc="Registers a callback (callable(Type, Request): void) triggered after a final Type or Error result is produced."
  />
</ApiGroup>

---

### 🛡️ Incoming Update Exception Catchers (`Telegram`)

<ApiGroup description="Exception dispatching and error handling routines for incoming updates.">
  <ApiCard
    sig="catch(string|callable $exceptionOrHandler, ?callable $handler = null): static"
    returns="static"
    badge="Exception Catcher"
    desc="Registers an exception handler for incoming update processing errors. Supports typed exception filtering."
  />
  <ApiCard
    sig="onUpdateError(callable $handler): static"
    returns="static"
    badge="Alias"
    aliasFor="catch()"
    desc="Convenience shorthand alias for catch() with a universal \Throwable catch-all handler."
  />
  <ApiCard
    sig="reply(string|Text $text, mixed ...$args): mixed"
    returns="mixed"
    badge="Helper"
    desc="Sends a quick text message to the active chat in context without manually resolving chatId."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/testing
# Section: Application & Production > Testing & Fakes
# ==============================================================================

# Testing & Fakes

Testing Telegram bots often poses challenges: calling real Telegram API servers during automated tests is slow, rate-limited, and may inadvertently message real users.

`tueen/telegram` ships with built-in testing fakes inspired by modern testing paradigms. With `Telegram::fake()`, you can intercept all outbound API calls, stub custom responses, and assert that expected API methods were called with precise parameters.

---

## 🧪 1. Quick Example

```php
use PHPUnit\Framework\TestCase;
use Tueen\Telegram\Telegram;
use Tueen\Telegram\Types\Update;

class WelcomeBotTest extends TestCase
{
    public function test_it_sends_welcome_message_on_start(): void
    {
        // 1. Swap real client with in-memory recording fake
        $bot = Telegram::fake();

        // 2. Simulate an incoming update
        $update = new Update([
            'update_id' => 1,
            'message' => [
                'message_id' => 10,
                'chat' => ['id' => 12345, 'type' => 'private'],
                'text' => '/start',
            ],
        ]);

        // 3. Run handler or controller
        $bot->onCommand('start', function (Update $update, Telegram $bot) {
            $bot->sendMessage(
                chatId: $update->findChat()->id,
                text: 'Welcome!'
            );
        });

        $bot->router->dispatch($update, $bot);

        // 4. Assert that sendMessage was called with expected parameters
        $bot->assertSent('sendMessage', function (array $params) {
            return $params['chat_id'] === 12345 && $params['text'] === 'Welcome!';
        });

        $bot->assertSentCount('sendMessage', 1);
    }
}
```

---

## 🛠️ 2. Response Stubbing

By default, `Telegram::fake()` provides a generic success response (`['ok' => true, 'result' => []]`) for any method called.

You can customize response stubs to test how your application handles specific Telegram responses or errors:

### Stubbing Successful Responses

```php
$bot = Telegram::fake();

// Stub a specific method response:
$bot->fakeResponse('getMe', [
    'ok' => true,
    'result' => [
        'id' => 999999,
        'is_bot' => true,
        'first_name' => 'TestBot',
        'username' => 'test_bot',
    ],
]);

$user = $bot->getMe();
$this->assertSame('test_bot', $user->username);
```

### Stubbing Telegram API Errors

Test how your system responds when Telegram returns an error (e.g. user blocked the bot):

```php
$bot = Telegram::fake();

$bot->fakeError('sendMessage', 'Forbidden: bot was blocked by the user', 403);

// In ErrorHandlingMode::EXCEPTION:
$this->expectException(\Tueen\Telegram\Exceptions\TelegramException::class);
$bot->sendMessage(chatId: 123, text: 'Hello');
```

---

## 🔍 3. Inspecting Sent Requests

You can inspect the recorded requests directly:

```php
$requests = $bot->sentRequests(); // list of recorded Request objects
$lastRequest = $bot->lastSentRequest();

echo $lastRequest->method; // e.g. "sendMessage"
print_r($lastRequest->params);
```

---

## 🧭 4. Testing & Fakes API Catalog

Below is the complete reference of assertion methods, stubbing helpers, and inspection APIs available on `Tueen\Telegram\Testing\TelegramFake`.

### 🛡️ Assertion Methods (`TelegramFake`)

<ApiGroup description="In-memory test assertions for verifying outbound Telegram API method invocations.">
  <ApiCard
    sig="assertSent(string $method, ?callable $callback = null): void"
    returns="void"
    badge="Assertion"
    desc="Asserts that a specific Telegram API method was invoked at least once, optionally matching callback predicate."
  />
  <ApiCard
    sig="assertNotSent(string $method, ?callable $callback = null): void"
    returns="void"
    badge="Assertion"
    desc="Asserts that a specific Telegram API method was never invoked, or never matched the callback predicate."
  />
  <ApiCard
    sig="assertSentCount(string $method, int $expectedCount): void"
    returns="void"
    badge="Assertion"
    desc="Asserts that a specific Telegram API method was called exactly the expected number of times."
  />
  <ApiCard
    sig="assertNothingSent(): void"
    returns="void"
    badge="Assertion"
    desc="Asserts that zero outbound API requests were dispatched to Telegram during test execution."
  />
</ApiGroup>

---

### 🎭 Stubbing & Inspection Methods (`TelegramFake`)

<ApiGroup description="Methods for mocking API responses and inspecting recorded request objects.">
  <ApiCard
    sig="Telegram::fake(array $responses = [], string $botToken = 'FAKE_BOT_TOKEN'): TelegramFake"
    returns="TelegramFake"
    badge="Factory"
    desc="Creates an in-memory recording fake client pre-seeded with optional response stubs."
  />
  <ApiCard
    sig="fakeResponse(string $method, array $response): static"
    returns="static"
    badge="Stubbing"
    desc="Registers a mock successful response array to be returned when the given method is called."
  />
  <ApiCard
    sig="fakeError(string $method, string $description, int $errorCode = 400): static"
    returns="static"
    badge="Stubbing"
    desc="Configures the fake to simulate a Telegram API error with HTTP status code and error description."
  />
  <ApiCard
    sig="sentRequests(): array<int, Request>"
    returns="array<int, Request>"
    badge="Inspection"
    desc="Returns all recorded HTTP Request instances dispatched during the test lifecycle."
  />
  <ApiCard
    sig="lastSentRequest(): ?Request"
    returns="?Request"
    badge="Inspection"
    desc="Returns the most recently recorded Request instance, or null if no calls were made."
  />
</ApiGroup>


# ==============================================================================
# File: /guide/enums
# Section: Application & Production > Enums Reference
# ==============================================================================

# Enums Reference

`tueen/telegram` provides Backed Enums for Telegram Bot API string constants, ensuring type safety and IDE autocompletion.

---

## 1. Core Telegram Enums

### `ParseMode`
Specifies how Telegram parses entities in messages or captions:
```php
use Tueen\Telegram\Enums\ParseMode;

ParseMode::HTML;        // 'HTML'
ParseMode::MARKDOWN_V2; // 'MarkdownV2'
ParseMode::MARKDOWN;    // 'Markdown' (Legacy)
```
```php
$bot->sendMessage(
    chatId: 12345,
    text: "<b>Hello</b> <i>World</i>!",
    parseMode: ParseMode::HTML
);
```

### `ChatAction`
Tells the user that something is happening on the bot's side (e.g. typing, uploading media):
```php
use Tueen\Telegram\Enums\ChatAction;

ChatAction::TYPING;              // 'typing'
ChatAction::UPLOAD_PHOTO;        // 'upload_photo'
ChatAction::RECORD_VIDEO;        // 'record_video'
ChatAction::UPLOAD_VIDEO;        // 'upload_video'
ChatAction::RECORD_VOICE;        // 'record_voice'
ChatAction::UPLOAD_VOICE;        // 'upload_voice'
ChatAction::UPLOAD_DOCUMENT;     // 'upload_document'
ChatAction::CHOOSE_STICKER;      // 'choose_sticker'
ChatAction::FIND_LOCATION;       // 'find_location'
ChatAction::RECORD_VIDEO_NOTE;   // 'record_video_note'
ChatAction::UPLOAD_VIDEO_NOTE;   // 'upload_video_note'
```
```php
$bot->sendChatAction(chatId: 12345, action: ChatAction::TYPING);
```

### `ChatType`
Identifies the type of conversation:
```php
use Tueen\Telegram\Enums\ChatType;

ChatType::SENDER;     // 'sender'
ChatType::PRIVATE;    // 'private'
ChatType::GROUP;      // 'group'
ChatType::SUPERGROUP; // 'supergroup'
ChatType::CHANNEL;    // 'channel'
```
```php
if ($message->chat->type === ChatType::PRIVATE) {
    // 1-on-1 private chat
}
```

### `ChatMemberStatus`
Identifies a user's role and privileges in a chat or channel:
```php
use Tueen\Telegram\Enums\ChatMemberStatus;

ChatMemberStatus::CREATOR;       // 'creator'
ChatMemberStatus::ADMINISTRATOR; // 'administrator'
ChatMemberStatus::MEMBER;        // 'member'
ChatMemberStatus::RESTRICTED;    // 'restricted'
ChatMemberStatus::LEFT;          // 'left'
ChatMemberStatus::KICKED;        // 'kicked'
```

### `DiceEmoji`
Animation types for `sendDice`:
```php
use Tueen\Telegram\Enums\DiceEmoji;

DiceEmoji::DICE;         // '🎲' (Values 1-6)
DiceEmoji::DARTS;        // '🎯' (Values 1-6)
DiceEmoji::BASKETBALL;   // '🏀' (Values 1-5)
DiceEmoji::FOOTBALL;     // '⚽' (Values 1-5)
DiceEmoji::SLOT_MACHINE; // '🎰' (Values 1-64)
DiceEmoji::BOWLING;      // '🎳' (Values 1-6)
```
```php
$res = $bot->sendDice(chatId: 12345, emoji: DiceEmoji::SLOT_MACHINE);
echo "Result value: {$res->dice->value}\n";
```

### `ButtonStyle`
Button colors for inline keyboards:
```php
use Tueen\Telegram\Enums\ButtonStyle;

ButtonStyle::PRIMARY; // 'primary' (blue)
ButtonStyle::SUCCESS; // 'success' (green)
ButtonStyle::DANGER;  // 'danger' (red)
```

### `BotCommandScopeType`
Defines who can see specific bot commands:
```php
use Tueen\Telegram\Enums\BotCommandScopeType;

BotCommandScopeType::DEFAULT;                  // 'default'
BotCommandScopeType::ALL_PRIVATE_CHATS;        // 'all_private_chats'
BotCommandScopeType::ALL_GROUP_CHATS;          // 'all_group_chats'
BotCommandScopeType::ALL_CHAT_ADMINISTRATORS;  // 'all_chat_administrators'
BotCommandScopeType::CHAT;                     // 'chat'
BotCommandScopeType::CHAT_ADMINISTRATORS;      // 'chat_administrators'
BotCommandScopeType::CHAT_MEMBER;              // 'chat_member'
```

### `PollType`
```php
use Tueen\Telegram\Enums\PollType;

PollType::REGULAR; // 'regular'
PollType::QUIZ;    // 'quiz'
```

---

## 2. Update & Message Enums

### `UpdateType`
Every update received from Telegram is classified into an `UpdateType` enum:

| Enum Case | Value | Trigger |
| :--- | :--- | :--- |
| `UpdateType::MESSAGE` | `'message'` | Incoming user message |
| `UpdateType::EDITED_MESSAGE` | `'edited_message'` | Edited message |
| `UpdateType::CHANNEL_POST` | `'channel_post'` | New channel post |
| `UpdateType::EDITED_CHANNEL_POST` | `'edited_channel_post'` | Edited channel post |
| `UpdateType::BUSINESS_CONNECTION` | `'business_connection'` | Telegram Business connected/disconnected |
| `UpdateType::BUSINESS_MESSAGE` | `'business_message'` | Message in Telegram Business chat |
| `UpdateType::EDITED_BUSINESS_MESSAGE` | `'edited_business_message'` | Edited Business message |
| `UpdateType::DELETED_BUSINESS_MESSAGES` | `'deleted_business_messages'` | Deleted Business messages |
| `UpdateType::MESSAGE_REACTION` | `'message_reaction'` | User reacted to a message |
| `UpdateType::MESSAGE_REACTION_COUNT` | `'message_reaction_count'` | Anonymous reaction tally changed |
| `UpdateType::INLINE_QUERY` | `'inline_query'` | Inline query typed (`@bot query`) |
| `UpdateType::CHOSEN_INLINE_RESULT` | `'chosen_inline_result'` | Inline result clicked |
| `UpdateType::CALLBACK_QUERY` | `'callback_query'` | Inline keyboard button tapped |
| `UpdateType::SHIPPING_QUERY` | `'shipping_query'` | Shipping query for invoice |
| `UpdateType::PRE_CHECKOUT_QUERY` | `'pre_checkout_query'` | Final order verification before payment |
| `UpdateType::PURCHASED_PAID_MEDIA` | `'purchased_paid_media'` | Telegram Stars paid media purchased |
| `UpdateType::POLL` | `'poll'` | Poll state change |
| `UpdateType::POLL_ANSWER` | `'poll_answer'` | User voted in a non-anonymous poll |
| `UpdateType::MY_CHAT_MEMBER` | `'my_chat_member'` | Bot's status in a chat updated |
| `UpdateType::CHAT_MEMBER` | `'chat_member'` | A member's status updated in a chat |
| `UpdateType::CHAT_JOIN_REQUEST` | `'chat_join_request'` | User requested to join a private group/channel |
| `UpdateType::CHAT_BOOST` | `'chat_boost'` | Premium user boosted the chat |
| `UpdateType::REMOVED_CHAT_BOOST` | `'removed_chat_boost'` | Boost expired or removed |

---

### `MessageType`
Classifies the content of a `Message` object:

| Category | Enum Cases |
| :--- | :--- |
| **Text & Rich Text** | `TEXT`, `RICH_MESSAGE` |
| **Media Attachments** | `PHOTO`, `VIDEO`, `AUDIO`, `VOICE`, `DOCUMENT`, `STICKER`, `ANIMATION`, `VIDEO_NOTE`, `PAID_MEDIA` |
| **Interactive & Games** | `DICE`, `GAME`, `POLL`, `LOCATION`, `VENUE`, `CONTACT`, `STORY` |
| **System & Chat Events** | `NEW_CHAT_MEMBERS`, `LEFT_CHAT_MEMBER`, `NEW_CHAT_TITLE`, `NEW_CHAT_PHOTO`, `DELETE_CHAT_PHOTO`, `GROUP_CHAT_CREATED`, `SUPERGROUP_CHAT_CREATED`, `CHANNEL_CHAT_CREATED`, `PINNED_MESSAGE` |
| **Payments & Stars** | `INVOICE`, `SUCCESSFUL_PAYMENT`, `REFUNDED_PAYMENT` |
| **Forum & Topics** | `FORUM_TOPIC_CREATED`, `FORUM_TOPIC_EDITED`, `FORUM_TOPIC_CLOSED`, `FORUM_TOPIC_REOPENED`, `GENERAL_FORUM_TOPIC_HIDDEN`, `GENERAL_FORUM_TOPIC_UNHIDDEN` |
| **Giveaways & Boosts** | `GIVEAWAY`, `GIVEAWAY_CREATED`, `GIVEAWAY_WINNERS`, `GIVEAWAY_COMPLETED`, `BOOST_ADDED` |
| **Web Apps & Passport** | `CONNECTED_WEBSITE`, `WRITE_ACCESS_ALLOWED`, `PASSPORT_DATA`, `USERS_SHARED`, `CHAT_SHARED` |

---

## 3. Complete Enums Reference

For reference, here is the complete index of Enums available in `Tueen\Telegram\Enums`:

- `BackgroundFillType`
- `BackgroundTypeType`
- `BotCommandScopeType`
- `ButtonStyle`
- `ChatAction`
- `ChatBoostSourceSource`
- `ChatJoinRequestResult`
- `ChatMemberStatus`
- `ChatType`
- `Currency`
- `DiceEmoji`
- `ErrorHandlingMode`
- `ForumIconColor`
- `InlineQueryResultType`
- `InputMediaType`
- `InputPaidMediaType`
- `InputProfilePhotoType`
- `InputRichBlockButtonsAlign`
- `InputRichBlockType`
- `InputStoryContentType`
- `MaskPositionPoint`
- `MenuButtonType`
- `MessageEntityType`
- `MessageOriginType`
- `MessageType`
- `OwnedGiftType`
- `PaidMediaType`
- `ParseMode`
- `PassportSource`
- `PassportType`
- `PollType`
- `ReactionTypeType`
- `RevenueWithdrawalStateType`
- `RichBlockButtonsAlign`
- `RichBlockListItemType`
- `RichBlockTableCellAlign`
- `RichBlockTableCellValign`
- `RichBlockType`
- `RichTextType`
- `StickerFormat`
- `StickerType`
- `StoryActivePeriod`
- `StoryAreaTypeType`
- `SubscriptionState`
- `SuggestedPostInfoState`
- `SuggestedPostRefundedReason`
- `TelegramErrorCode`
- `TransactionPartnerType`
- `UniqueGiftInfoOrigin`
- `UniqueGiftModelRarity`
- `UpdateType`
- `VideoQualityCodec`