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

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:

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.
No Trailing Nulls: Telegram Bot API methods accept dozens of optional parameters. Named arguments eliminate the need for long lists of null placeholders.
Forward-Compatibility: When Telegram adds new parameters to Bot API methods, named arguments prevent positional shift bugs.
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`:

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.
Dual Property Access: Access properties using camelCase ($message->messageId) or snake_case ($message->message_id).
ArrayAccess Support: Access properties using bracket syntax ($message['chat']['id']).
JsonSerializable & Stringable: Passing any type to json_encode($type) or (string)$type produces clean, unescaped JSON.
Array Transformation: Call toArray() or toJson() to recursively convert the type and all nested objects into primitive arrays or JSON strings.
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`:

Endpoint Resolution: Defines the API method name (e.g. 'sendMessage').
Payload Serialization: Prepares and filters parameters, converting nested Type objects, Enums, and JSON-encoded fields.
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.
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\:

HasUpdateHelpers

→Trait on UpdateConcern Trait

Equips Update with $type, $chatId, $userId, $messageId, $fileId, findMessage(), findUser(), findChat(), and isType().

HasMessageHelpers

→Trait on MessageConcern Trait

Equips Message with $isCommand, $command, $args, $textOrCaption, $fileId, $largestPhoto, isRepliedToMessage(), and findAnyText().

HasChatHelpers

→Trait on ChatConcern Trait

Equips Chat with computed $fullName, $isPrivate, $isGroup, $isSupergroup, and $isChannel.

HasUserHelpers

→Trait on UserConcern Trait

Equips User with computed $fullName and HTML $mention.

HasInlineKeyboardHelpers

→Trait on InlineKeyboardMarkupConcern Trait

Equips InlineKeyboardMarkup with button query and row inspection helpers.

HasReplyKeyboardHelpers

→Trait on ReplyKeyboardMarkupConcern Trait

Equips ReplyKeyboardMarkup with button grid inspection helpers.

For a complete guide and code examples of these helpers, see Update & 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`)

ok(): bool

Universal Check

Determines whether the API response succeeded. Always returns true for valid Type instances and false for Error objects.

isOk(): bool

Alias

Shorthand alias for ok() adhering to standard boolean accessor naming.

public array $rawData

→arrayProperty Hook

Virtual property returning the original raw payload array received from Telegram API.

protected(set) array $raw

→arrayAsymmetric Visibility

Internal raw array populated during type construction.

toArray(): array

Serialization

Recursively converts the type instance and all nested Type objects and Enums into a clean associative array.

toJson(int $flags = JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT): string

Serialization

Serializes the type instance into formatted JSON.

offsetGet(mixed $offset): mixed

ArrayAccess

ArrayAccess getter supporting snake_case field access (e.g. $message['chat']['id']).

offsetExists(mixed $offset): bool

ArrayAccess

ArrayAccess isset check for verifying whether a property exists.

offsetSet(mixed $offset, mixed $value): void

ArrayAccess

ArrayAccess setter for modifying or injecting dynamic fields.

offsetUnset(mixed $offset): void

ArrayAccess

ArrayAccess unsetter for clearing fields.

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

endpoint(): string

Contract

Returns the Telegram Bot API endpoint method name (e.g. 'sendMessage', 'sendPhoto').

getPayload(): array

Contract

Prepares and serializes method parameters into a normalized array ready for JSON or multipart transmission.

hasUploads(): bool

Multipart

Detects whether any parameter contains an InputFile or file stream requiring multipart/form-data encoding.

isMultipart(): bool

Alias

Convenience alias to check if request must be dispatched using multipart encoding.

returnType(): string

Contract

Returns the concrete Type class name to deserialize the response into (e.g. Message::class, BooleanResult::class).

🎯 Contextual Parameter Auto-Injection

chat_id

→int|stringContextual

Inferred from active message, callback query, business message, channel post, or reaction.

business_connection_id

→stringContextual

Inferred from incoming business connection or business message update.

message_thread_id

→intContextual

Inferred from forum topic thread ID on incoming message.

user_id

→intContextual

Inferred from acting user (for getUserProfilePhotos, getUserGifts, etc.).

message_id

→intContextual

Inferred from primary message (for deleteMessage, pinChatMessage, etc.).

inline_message_id

→stringContextual

Inferred from inline callback queries for editMessageText, editMessageReplyMarkup, etc.

callback_query_id

→stringContextual

Inferred query ID for answerCallbackQuery(text: 'Done!').

inline_query_id

→stringContextual

Inferred query ID for answerInlineQuery(results: [...]).

shipping_query_id

→stringContextual

Inferred query ID for answerShippingQuery(ok: true).

pre_checkout_query_id

→stringContextual

Inferred query ID for answerPreCheckoutQuery(ok: true).

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

public readonly bool $value

→boolBooleanResult

Underlying boolean outcome for methods like deleteMessage, setWebhook, or pinChatMessage.

public readonly int $value

→intIntegerResult

Underlying integer counter for methods like getChatMemberCount.

public readonly string $value

→stringStringResult

Underlying string for methods like exportChatInviteLink or createInvoiceLink.

InputFile::fromPath(string $path, ?string $filename = null, ?string $contentType = null): self

InputFile Factory

Creates a multipart file upload wrapper from a local filesystem path.

InputFile::fromResource(resource $resource, string $filename, ?string $contentType = null): self

InputFile Factory

Creates a multipart file upload wrapper from an open PHP stream resource (e.g. fopen).

InputFile::fromString(string $contents, string $filename, ?string $contentType = null): self

InputFile Factory

Creates an in-memory multipart file upload wrapper from raw string contents.

InputFile::fromStream(StreamInterface $stream, string $filename, ?string $contentType = null): self

InputFile Factory

Creates a multipart file upload wrapper from any PSR-7 StreamInterface instance.

Calling Methods & Types ​

🚀 1. Method Invocations ​

Dynamic Method Calls (Recommended) ​

Why Named Arguments Are Recommended: ​

Method Objects (For Custom Pipelines & Architecture) ​

Forward-Compatible Unknown / New Parameters ​

Passing Complex & Nested Types (Objects or Arrays) ​

A. Using Strongly-Typed Type Objects ​

B. Using Structured Arrays ​

🏛️ 2. The Universal Base Type Class ​

Core Features of Type: ​

⚙️ 3. The Base Method Class ​

Core Responsibilities of Method: ​

🧩 4. Concerns & Computed Helpers ​

📦 5. Custom Result Wrapper Types ​

🧭 6. Methods & Types API Reference ​

🏛️ Base Type Class (Tueen\Telegram\Types\Type) ​

⚙️ Base Method Class (Tueen\Telegram\Methods\Method) ​

🎯 Contextual Parameter Auto-Injection ​

📦 Custom Wrapper Types (Tueen\Telegram\Types\Custom\) ​

Calling Methods & Types

🚀 1. Method Invocations

Dynamic Method Calls (Recommended)

Why Named Arguments Are Recommended:

Method Objects (For Custom Pipelines & Architecture)

Forward-Compatible Unknown / New Parameters

Passing Complex & Nested Types (Objects or Arrays)

A. Using Strongly-Typed Type Objects

B. Using Structured Arrays

🏛️ 2. The Universal Base `Type` Class

Core Features of `Type`:

⚙️ 3. The Base `Method` Class

Core Responsibilities of `Method`:

🧩 4. Concerns & Computed Helpers

📦 5. Custom Result Wrapper Types

🧭 6. Methods & Types API Reference

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

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

🎯 Contextual Parameter Auto-Injection

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