Nutgram Laravel

https://github.com/nutgram/laravel
Admin
Nutgram Laravel is a Laravel package that integrates the Nutgram Telegram bot framework, enabling...
Tokens:33,346
Snippets:259
Trust Score:8.9
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Usage examples for console commands

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-hook-commands.md

Shows example invocations for all console commands: setting webhook with optional IP and max connections, retrieving info, removing webhook with optional drop-pending-updates, logging out, and registering commands. Exit codes: 0 success, 1 for hook:info when webhook info is unavailable.

```bash
php artisan nutgram:hook:set https://example.com/telegram/webhook
php artisan nutgram:hook:set https://example.com/hook --ip=1.2.3.4 --max-connections=100
php artisan nutgram:hook:info
php artisan nutgram:hook:remove
php artisan nutgram:hook:remove --drop-pending-updates
php artisan nutgram:logout
php artisan nutgram:register-commands
```

--------------------------------

### Register command and run with Telegram facade

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Registers a 'start' command handler and runs the bot using the Telegram facade. The command description is set via the description() method.

```php
use Nutgram\Laravel\Facades\Telegram;

Telegram::onCommand('start', function (Nutgram $bot) {
    $bot->sendMessage('Hello!');
})->description('The start command.');

Telegram::run();
```

--------------------------------

### Usage examples for console commands

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-runtime-commands.md

Shows typical invocations of the nutgram console commands: run in long polling, run once with a polling timeout, listen in dev loop, list handlers, and generate the IDE helper.

```bash
php artisan nutgram:run                        # long polling (web context default is webhook; this forces polling)
php artisan nutgram:run --once --pollingTimeout=10
php artisan nutgram:listen                     # dev loop, restart after each update
php artisan nutgram:list                       # inspect registered handlers
php artisan nutgram:ide:generate               # writes _ide_helper_nutgram.php
```

--------------------------------

### run()

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Starts the bot's long polling loop to receive updates from Telegram.

```APIDOC
## run()

### Description
Starts the bot's long polling loop to receive updates from Telegram.

### Method
run

### Signature
```php
@method static void run()
```

```

--------------------------------

### Usage example: using webAppData() in a controller method

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/support-helpers.md

Example of using webAppData() inside a controller method after the middleware has run, equivalent to $request->attributes->get('webAppData').

```php
public function handleInitData(Request $request)
{
    // attribute set by the middleware; equivalent to $request->attributes->get('webAppData')
    $webAppData = webAppData();
}
```

--------------------------------

### Usage example: reading webAppData in a controller

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/support-helpers.md

Example of using webAppData() inside a Laravel route to read validated Web App data. Returns 403 if data is null.

```php
use function Nutgram\Laravel\Support\webAppData;

Route::post('/webapp', function () {
    $data = webAppData(); // ?WebAppData

    if ($data === null) {
        return response('invalid data', 403);
    }

    return response()->json([
        'user' => $data->user,
        'authDate' => $data->authDate,
    ]);
})->middleware(ValidateWebAppData::class);
```

--------------------------------

### Safe mode route example

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/laravel-webhook.md

Route definition for safe mode. Same as the basic route but without the comment about processUpdate.

```php
// routes/web.php
use SergiX44\Nutgram\Nutgram;

Route::post('/telegram/webhook', function (Nutgram $bot) {
    $bot->run();
});
```

--------------------------------

### Install Nutgram Laravel Package via Composer

Source: https://github.com/nutgram/laravel/blob/master/README.md

Use this command to install the Nutgram package for Laravel 9.0+ via Composer. Run it in your project root to add the dependency.

```bash
composer require nutgram/laravel
```

--------------------------------

### Webhook route example

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/laravel-webhook.md

Typical HTTP route that receives Telegram webhook updates. The route is not defined by the package; the user must register it. The bot's run() method processes the update from the request body.

```php
// routes/web.php
use SergiX44\Nutgram\Nutgram;

Route::post('/telegram/webhook', function (Nutgram $bot) {
    $bot->run(); // processUpdate is dispatched from the request body by LaravelWebhook
});
```

--------------------------------

### Writing a log record to the Telegram channel

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/logging.md

Example of writing an info-level log to the 'telegram' channel. The record is delivered to the configured chat as an HTML chunked message.

```php
use Illuminate\Support\Facades\Log;

Log::channel('telegram')->info('Deploy finished', ['build' => 42]);
```

--------------------------------

### BaseMakeCommand handle() method signature

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-make-commands.md

Public method that executes the scaffolding logic. Returns int: 0 on success, 1 when the target file already exists.

```php
public function handle(): int
```

--------------------------------

### BaseMakeCommand abstract class signature

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-make-commands.md

Abstract base for all nutgram:make:* commands. Defines the command signature and description placeholders. Subclasses must implement getSubDirName() and getStubPath().

```php
abstract class BaseMakeCommand extends Command
{
    protected $signature = 'nutgram:make:? {name : ? name}';
    protected $description = 'Create a new Nutgram ?';
    ...
}
```

--------------------------------

### boot() method signature

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/nutgram-service-provider.md

Declares the boot method of the NutgramServiceProvider. It loads package logging views and, when running in console, registers Artisan commands and publishes configuration files.

```php
public function boot(): void
```

--------------------------------

### Make handler with nested namespace

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-make-commands.md

Shows how to specify a nested namespace for a handler. The command creates the file in a subdirectory and sets the namespace accordingly.

```bash
php artisan nutgram:make:handler 'Admin/CleanupJob'    # app/Telegram/Handlers/Admin/CleanupJob.php, namespace App\Telegram\Handlers\Admin
```

--------------------------------

### Basic make commands for command, conversation, exception, handler, middleware

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-make-commands.md

Shows how to generate various Nutgram classes using artisan make commands. Each command creates a file in the corresponding subdirectory under app/Telegram. The conversation command with --menu option creates an InlineMenu conversation.

```bash
php artisan nutgram:make:command StartCommand          # app/Telegram/Commands/StartCommand.php
php artisan nutgram:make:conversation OrderFlow --menu # app/Telegram/Conversations/OrderFlow.php (InlineMenu)
php artisan nutgram:make:exception ChatNotFound        # app/Telegram/Exceptions/ChatNotFound.php
php artisan nutgram:make:handler HandleUpload          # app/Telegram/Handlers/HandleUpload.php
php artisan nutgram:make:middleware OnlyAdmins         # app/Telegram/Middleware/OnlyAdmins.php
```

--------------------------------

### Handle missing-bot failure with RuntimeException

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/mixins.md

Wrap `downloadFileToDisk` in a try-catch to handle the case where no bot instance is found. The exception message is 'Bot instance not found.' and can be reported using Laravel's `report()` helper.

```php
use RuntimeException;

try {
    $bot->downloadFileToDisk($file, 'x.txt');
} catch (RuntimeException $e) { // 'Bot instance not found.'
    report($e);
}
```

--------------------------------

### IdeGenerateCommand signature and description

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-runtime-commands.md

Defines the nutgram:ide:generate command signature and description for generating an IDE helper file.

```php
protected $signature = 'nutgram:ide:generate';
protected $description = 'Generate IDE helper for Nutgram';
```

--------------------------------

### ListCommand signature and description

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-runtime-commands.md

Defines the nutgram:list command signature and description for listing all registered handlers.

```php
protected $signature = 'nutgram:list';
protected $description = 'List all registered handlers';
```

--------------------------------

### Download file to disk with mixin from app container

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/mixins.md

Use the mixin methods after enabling `mixins` in `config/nutgram.php`. The `downloadFileToDisk` method accepts a file, target path, optional disk name, and optional client options. The first call uses the default disk, the second appends the file name to a directory on the 's3' disk, and the third passes custom client options like a timeout.

```php
use SergiX44\Nutgram\Nutgram;

$bot = app(Nutgram::class);

$bot->downloadFileToDisk($file, 'downloads/text.txt');                 // default disk
$bot->downloadFileToDisk($file, 'downloads/', 's3');                    // file name appended, S3 disk
$bot->downloadFileToDisk($file, 'downloads/', null, ['timeout' => 30]); // custom client opts
```

--------------------------------

### ListenCommand signature and description

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-runtime-commands.md

Defines the nutgram:listen command signature and description for development mode. It restarts nutgram:run --once after every update batch and defaults --pollingTimeout to 5.

```php
protected $signature = 'nutgram:listen {--pollingTimeout=5}';
protected $description = 'Start the bot for development and reloads after every update.';
```

--------------------------------

### saveToDisk()

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/mixins.md

Adds a saveToDisk() method to the File class via a mixin. Downloads the file to a Laravel disk and returns a boolean indicating success.

```APIDOC
## saveToDisk()

### Description
Adds a `saveToDisk()` method to the `File` class via a mixin. Downloads the file to a Laravel disk and returns a boolean indicating success.

### Method
`saveToDisk()`

### Signature
```php
public function saveToDisk(): Closure
```

### Parameters
- **path** (string) - Required - Destination path on the Laravel disk; trailing `/` or `\` appends the remote file name.
- **disk** (?string) - Optional - Laravel disk name; `null` = default disk.
- **clientOpt** (array) - Optional - Extra HTTP client options.

### Return Type
`bool` — `true` when stored, `false` otherwise. `$this` is the `File` the mixin is applied to.
```

--------------------------------

### Build SergiX44\Nutgram\Configuration from nutgram.config.* keys

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/configuration.md

The provider constructs the upstream Configuration object, mapping each nutgram.config.* key to a constructor parameter. Fixed values are the Laravel container, cache repository, and the logger channel from nutgram.log_channel. Defaults come from Configuration::DEFAULT_* constants when keys are absent.

```php
new Configuration(
    apiUrl: config('nutgram.config.api_url', Configuration::DEFAULT_API_URL),
    botId: config('nutgram.config.bot_id'),
    botName: config('nutgram.config.bot_name'),
    testEnv: config('nutgram.config.test_env', false),
    isLocal: config('nutgram.config.is_local', false),
    clientTimeout: config('nutgram.config.timeout', Configuration::DEFAULT_CLIENT_TIMEOUT),
    clientOptions: config('nutgram.config.client', []),
    container: $app,
    hydrator: config('nutgram.config.hydrator', Configuration::DEFAULT_HYDRATOR),
    cache: $app->get(Cache::class),
    logger: $app->get(LoggerInterface::class)->channel(config('nutgram.log_channel', 'null')),
    localPathTransformer: config('nutgram.config.local_path_transformer'),
    pollingTimeout: config('nutgram.config.polling.timeout', Configuration::DEFAULT_POLLING_TIMEOUT),
    pollingAllowedUpdates: config('nutgram.config.polling.allowed_updates', Configuration::DEFAULT_ALLOWED_UPDATES),
    pollingLimit: config('nutgram.config.polling.limit', Configuration::DEFAULT_POLLING_LIMIT),
    enableHttp2: config('nutgram.config.enable_http2', Configuration::DEFAULT_ENABLE_HTTP2),
    conversationTtl: config('nutgram.config.conversation_ttl', Configuration::DEFAULT_CONVERSATION_TTL)
);
```

--------------------------------

### composer.json autoload configuration

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/support-helpers.md

The composer.json autoload entry that loads the Helpers.php file globally.

```json
"autoload": {
    "psr-4": { "Nutgram\\Laravel\\": "src/" },
    "files": ["src/Support/Helpers.php"]
}
```

--------------------------------

### Publish config and routes with vendor:publish

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/nutgram-service-provider.md

Publishes the package's config and routes files under the 'nutgram' tag. Run this command to make the configuration and route files available for customization.

```php
php artisan vendor:publish --provider=Nutgram\Laravel\NutgramServiceProvider --tag=nutgram
```

--------------------------------

### Save file to disk from File object inside handler

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/mixins.md

Inside a handler, the `File` object provides `saveToDisk` to store the file. The first call saves to 'downloads/photo.jpg' on the default disk, the second saves to the 'downloads/' directory on the 'local' disk.

```php
$file->saveToDisk('downloads/photo.jpg');
$file->saveToDisk('downloads/', 'local');
```

--------------------------------

### saveFileToDisk() static method signature in MixinUtils

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/mixins.md

Internal helper that both mixins delegate to. Downloads the file and stores it on a Laravel disk. Throws RuntimeException if bot instance is missing, and container exceptions when resolving ClientInterface.

```php
public static function saveFileToDisk(File $file, string $path, ?string $disk = null, array $clientOpt = []): bool
```

--------------------------------

### RegisterCommandsCommand signature and description

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-hook-commands.md

Defines the command signature and description for registering the bot command list. No arguments or options are defined.

```php
protected $signature = 'nutgram:register-commands';
protected $description = 'Register the bot commands';
```

--------------------------------

### MakeConversationCommand::getStubPath() with --menu variance

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-make-commands.md

Returns the InlineMenu stub when the --menu option is set, otherwise the Conversation stub. Used by the nutgram:make:conversation command to select the appropriate stub file.

```php
protected function getStubPath(): string
{
    if ($this->option('menu')) {
        return __DIR__.'/../Stubs/InlineMenu.stub';
    }

    return __DIR__.'/../Stubs/Conversation.stub';
}
```

--------------------------------

### downloadFileToDisk() method

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/mixins.md

Adds downloadFileToDisk() to SergiX44\Nutgram\Nutgram. Returns a closure that saves a Telegram file to a Laravel disk using MixinUtils::saveFileToDisk(). Throws RuntimeException when $file->getBot() is null.

```php
public function downloadFileToDisk(): Closure
{
    return function (File $file, string $path, ?string $disk = null, array $clientOpt = []): bool {
        /** @var Nutgram $this */

        return MixinUtils::saveFileToDisk($file, $path, $disk, $clientOpt);
    };
}
```

--------------------------------

### HookSetCommand signature and description

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-hook-commands.md

Defines the command signature and description for setting the bot webhook. The signature includes a required 'url' argument and optional '--ip' and '--max-connections' options (default 50).

```php
protected $signature = 'nutgram:hook:set {url} {--ip=} {--max-connections=50}';
protected $description = 'Set the bot webhook';
```

--------------------------------

### Constructor

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/validate-web-app-data.md

Creates a new instance of the ValidateWebAppData middleware with the Nutgram bot instance injected by Laravel's container.

```APIDOC
## Constructor

### Description
Creates a new instance of the ValidateWebAppData middleware with the Nutgram bot instance injected by Laravel's container.

### Signature
```php
public function __construct(protected Nutgram $bot)
```

### Parameters
- **bot** (SergiX44\Nutgram\Nutgram) - Required - The resolved Nutgram bot used to validate the Web App init data.
```

--------------------------------

### HookInfoCommand signature and description

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-hook-commands.md

Defines the command signature and description for retrieving current webhook status. No arguments or options are defined.

```php
protected $signature = 'nutgram:hook:info';
protected $description = 'Get current webhook status';
```

--------------------------------

### instance(mixed $update = null, array $responses = [], Configuration|null $config = null)

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Creates a fake bot instance for testing purposes.

```APIDOC
## instance(mixed $update = null, array $responses = [], Configuration|null $config = null)

### Description
Creates a fake bot instance for testing purposes.

### Method
instance

### Signature
```php
@method static \SergiX44\Nutgram\Testing\FakeNutgram instance(mixed $update = null, array $responses = [], \SergiX44\Nutgram\Configuration|null $config = null)
```

```

--------------------------------

### Re-running make command for existing file

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-make-commands.md

Shows the output when re-running a make command for an existing file. The command fails with exit code 1 and prints a message indicating the file already exists.

```bash
php artisan nutgram:make:command StartCommand
# → /app/Telegram/Commands/StartCommand.php already exists.  (exit code 1)
```

--------------------------------

### onCommand(string $command, callable $callable, UpdateType $target = 'message')

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Registers a handler for a specific bot command (e.g., /start).

```APIDOC
## onCommand(string $command, callable $callable, UpdateType $target = 'message')

### Description
Registers a handler for a specific bot command (e.g., /start).

### Method
onCommand

### Signature
```php
@method static mixed onCommand(string $command, void $callable, \SergiX44\Nutgram\Telegram\Properties\UpdateType $target = 'message')
```

```

--------------------------------

### Define bot command in routes/telegram.php

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/nutgram-service-provider.md

Handlers declared in routes/telegram.php are loaded automatically when 'nutgram.routes' is true (the default). The $bot variable is a SergiX44\Nutgram\Nutgram instance.

```php
// routes/telegram.php — $bot is a SergiX44\Nutgram\Nutgram instance
$bot->onCommand('start', function (Nutgram $bot) {
    $bot->sendMessage('Hello, world!');
})->description('The start command!');
```

--------------------------------

### handle()

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/validate-web-app-data.md

Validates the Telegram Web App initData from the incoming request and stores the parsed payload on the request attributes. Returns the result of the next middleware in the pipeline.

```APIDOC
## handle()

### Description
Validates the Telegram Web App initData from the incoming request and stores the parsed payload on the request attributes. Returns the result of the next middleware in the pipeline.

### Signature
```php
public function handle(Request $request, Closure $next): mixed
```

### Parameters
- **request** (Illuminate\Http\Request) - Required - Incoming HTTP request; the Web App init data is read from the `initData` input field.
- **next** (Closure) - Required - Next middleware in the pipeline.

### Return Type
`mixed` - The result of `$next($request)`.

### Logic
1. Reads the raw query string from the `initData` input (defaults to `''`).
2. Delegates to the upstream validation (`SergiX44\Nutgram\Support\ValidatesWebData`).
3. On success: adds `webAppData` attribute to the request and returns `$next($request)`.
4. On `SergiX44\Nutgram\Exception\InvalidDataException`: calls `handleInvalidData()`.
```

--------------------------------

### formatText method

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/logging.md

Formats the record as HTML: <b>{app.name} {LEVEL}</b> ({env}):\n<pre>{record->formatted}</pre>.

```php
protected function formatText(LogRecord $record): string
```

--------------------------------

### ValidateWebAppData class constructor and handle method

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/validate-web-app-data.md

The middleware class constructor injects the Nutgram bot instance. The handle method reads the initData input, validates it, and stores the result in the request attributes.

```php
class ValidateWebAppData
{
    public function __construct(protected Nutgram $bot)
    {
    }
    ...
}
```

```php
public function __construct(protected Nutgram $bot)
```

```php
public function handle(Request $request, Closure $next): mixed
```

```php
protected function handleInvalidData(Request $request, Closure $next): mixed
```

--------------------------------

### LoggerHandler constructor

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/logging.md

Constructor accepts channel config. Reads 'level' via Logger::toMonologLevel and stores 'chat_id' as the target chat.

```php
public function __construct(array $config)
```

--------------------------------

### saveToDisk() mixin method in FileMixin

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/mixins.md

Adds saveToDisk() to SergiX44\Nutgram\Telegram\Types\Media\File. Returns a Closure that saves the file to a Laravel disk. Returns true when stored, false otherwise. $this is the File the mixin is applied to.

```php
public function saveToDisk(): Closure
{
    return function (string $path, ?string $disk = null, array $clientOpt = []): bool {
        /** @var File $this */

        return MixinUtils::saveFileToDisk($this, $path, $disk, $clientOpt);
    };
}
```

--------------------------------

### RunCommand signature and description

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-runtime-commands.md

Defines the nutgram:run command signature and description for long polling mode. The --once option switches to SingleUpdate mode and --pollingTimeout overrides the config value at runtime.

```php
protected $signature = 'nutgram:run {--once} {--pollingTimeout=}';
protected $description = 'Start the bot in long polling mode';
```

--------------------------------

### downloadFileToDisk()

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/mixins.md

Downloads a Telegram file to a Laravel storage disk. This method is added to the Nutgram class via the NutgramMixin and requires the mixins configuration to be enabled.

```APIDOC
## downloadFileToDisk()

### Description
Downloads a remote Telegram file to a Laravel storage disk. The method is added to the `SergiX44\Nutgram\Nutgram` class via the `NutgramMixin` and is only available when `config('nutgram.mixins')` is `true`.

### Method
`downloadFileToDisk()`

### Parameters
- **file** (`SergiX44\Nutgram\Telegram\Types\Media\File`) - Required - The remote Telegram file to download.
- **path** (string) - Required - Destination path on the Laravel disk; if it ends with `/` or `\`, the remote file name is appended.
- **disk** (?string) - Optional - Laravel disk name (`Storage::disk()`); `null` = default disk.
- **clientOpt** (array) - Optional - Extra HTTP client options passed to the PSR-18 client used for the download.

### Return Type
`bool` — `true` when the file was stored, `false` otherwise.

### Throws
`RuntimeException` when `$file->getBot()` is `null`.
```

--------------------------------

### LogoutCommand signature and description

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-hook-commands.md

Defines the command signature and description for logging out from the cloud Bot API server. Includes a boolean option '--d|drop-pending-updates'.

```php
protected $signature = 'nutgram:logout {--d|drop-pending-updates}';
protected $description = 'Log out from the cloud Bot API server';
```

--------------------------------

### register() method signature

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/nutgram-service-provider.md

Defines the register() method without a return type. Called by Laravel during container registration to set up configuration, bindings, and aliases.

```php
public function register()
```

--------------------------------

### NutgramFormatter::formatBatch() method signature

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/logging.md

Public method signature for formatting a batch of log records by applying format() to each record.

```php
public function formatBatch(array $records): void
```

--------------------------------

### Import Telegram facade

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Import path for using the Telegram facade in Laravel applications.

```php
use Nutgram\Laravel\Facades\Telegram;
```

--------------------------------

### Catch RuntimeException for Bot instance not found

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/errors.md

Catches the RuntimeException thrown by downloadFileToDisk() when the File's getBot() returns null. The exception message is 'Bot instance not found.'

```php
use RuntimeException;

try {
    $bot->downloadFileToDisk($file, 'x.txt');
} catch (RuntimeException $e) {
    // 'Bot instance not found.'
}
```

--------------------------------

### Custom failure handling by extending ValidateWebAppData

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/validate-web-app-data.md

Overrides handleInvalidData to attach a null webAppData attribute and redirect to /login instead of aborting with 403.

```php
class MyWebAppMiddleware extends ValidateWebAppData
{
    protected function handleInvalidData(Request $request, Closure $next): mixed
    {
        $request->attributes->add(['webAppData' => null]);
        return redirect('/login'); // or $next($request)
    }
}
```

--------------------------------

### Handler Registration Methods

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Methods for registering handlers for various Telegram updates, commands, and events. These methods are forwarded from the underlying Nutgram instance.

```APIDOC
## Handler Registration Methods

### Description
Methods for registering handlers for various Telegram updates, commands, and events. These methods are forwarded from the underlying Nutgram instance.

### Methods
- `middleware`
- `middlewares`
- `group`
- `clearErrorHandlers`
- `onUpdate`
- `onMessage`
- `onMessageType`
- `onEditedMessage`
- `onChannelPost`
- `onEditedChannelPost`
- `onBusinessConnection`
- `onBusinessMessage`
- `onEditedBusinessMessage`
- `onDeletedBusinessMessages`
- `onMessageReaction`
- `onMessageReactionCount`
- `onInlineQuery`
- `onInlineQueryText`
- `onChosenInlineResult`
- `onChosenInlineResultQuery`
- `onChosenInlineResultId`
- `onCallbackQuery`
- `onCallbackQueryData`
- `onShippingQuery`
- `onPreCheckoutQuery`
- `onPreCheckoutQueryPayload`
- `onPaidMediaPurchased`
- `onPaidMediaPurchasedPayload`
- `onUpdatePoll`
- `onPollAnswer`
- `onMyChatMember`
- `onChatMember`
- `onChatJoinRequest`
- `onChatBoost`
- `onRemovedChatBoost`
- `onCommand`
- `registerCommand`
- `onText`
- `onAnimation`
- `onAudio`
- `onDocument`
- `onPhoto`
- `onSticker`
- `onVideo`
- `onVideoNote`
- `onVoice`
- `onContact`
- `onDice`
- `onGame`
- `onMessagePoll`
- `onVenue`
- `onLocation`
- `onStory`
- `onNewChatMembers`
- `onLeftChatMember`
- `onChatOwnerLeft`
- `onChatOwnerChanged`
- `onNewChatTitle`
- `onNewChatPhoto`
- `onDeleteChatPhoto`
- `onGroupChatCreated`
- `onSupergroupChatCreated`
- `onChannelChatCreated`
- `onMessageAutoDeleteTimerChanged`
- `onMigrateToChatId`
- `onMigrateFromChatId`
- `onPinnedMessage`
- `onInvoice`
- `onSuccessfulPayment`
- `onSuccessfulPaymentPayload`
- `onRefundedPayment`
- `onRefundedPaymentPayload`
- `onUsersShared`
- `onChatShared`
- `onConnectedWebsite`
- `onPassportData`
- `onProximityAlertTriggered`
- `onBoostAdded`
- `onDirectMessagePriceChanged`
- `onChecklist`
- `onChecklistTasksDone`
- `onChecklistTasksAdded`
- `onForumTopicCreated`
- `onForumTopicEdited`
- `onForumTopicClosed`
- `onForumTopicReopened`
- `onGiveawayCreated`
- `onGiveaway`
- `onGiveawayWinners`
- `onGiveawayCompleted`
- `onVideoChatScheduled`
- `onVideoChatStarted`
- `onVideoChatEnded`
- `onVideoChatParticipantsInvited`
- `onWebAppData`
- `fallback`
- `fallbackOn`
- `onException`
- `onApiError`
- `registerApiException`
- `beforeApiRequest`
- `afterApiRequest`
```

--------------------------------

### Safe mode webhook instance construction

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/laravel-webhook.md

Constructs a LaravelWebhook instance with a getToken callback reading the X-Telegram-Bot-Api-Secret-Token header and a secretToken derived from md5(config('app.key')). Then enables safe mode.

```php
new LaravelWebhook(
    getToken: fn () => request()?->header('X-Telegram-Bot-Api-Secret-Token'),
    secretToken: md5(config('app.key'))
);
$webhook->setSafeMode(true);
```

--------------------------------

### Register Nutgram and File mixins

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/mixins.md

Registers the NutgramMixin and FileMixin with the Nutgram and File classes. Only performed when config('nutgram.mixins') is true.

```php
Nutgram::mixin(new Mixins\NutgramMixin());
File::mixin(new Mixins\FileMixin());
```

--------------------------------

### nutgram:hook:info

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-hook-commands.md

Shows the current webhook status. This command retrieves and displays webhook information in a table format.

```APIDOC
## [COMMAND] nutgram:hook:info

### Description
Shows the current webhook status.

### Command
`php artisan nutgram:hook:info`

### Behavior
Calls `$bot->getWebhookInfo()`. If it returns `null`, renders `terminal::fail` with "Unable to get webhook info" and returns `1`. Otherwise renders a `terminal::table` with: `url`, `has_custom_certificate` (`'true'`/`'false'`), `pending_update_count`, `ip_address`, `last_error_date` (formatted `Y-m-d H:i:s` UTC or `null`), `last_error_message`, `last_synchronization_error_date`, `max_connections`, `allowed_updates` (comma-joined). Returns `0`.

### Exceptions
- `TelegramException`
- `GuzzleException`
- `JsonException`

### Example
```bash
php artisan nutgram:hook:info
```
```

--------------------------------

### input() method signature

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/laravel-webhook.md

Shows the method signature of the overridden input() method. It returns the raw request body or null when no request instance is bound.

```php
protected function input(): ?string
```

--------------------------------

### LoggerHandler::__construct()

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/logging.md

Constructor for the LoggerHandler that initializes the handler with channel configuration. Reads 'level' and 'chat_id' from the config array.

```APIDOC
## LoggerHandler::__construct()

### Description
Constructor for the LoggerHandler that initializes the handler with channel configuration. Reads 'level' and 'chat_id' from the config array.

### Method
__construct

### Parameters
- `config` (array) - Required - Channel config; `level` is read via `Logger::toMonologLevel($config['level'])` and `chat_id` is stored as the target chat.

### Config Keys
- `level` - any Monolog level name/value accepted by `toMonologLevel`
- `chat_id` - `string|int|null`, stored in `protected string|int|null $chatId`
```

--------------------------------

### webAppData() helper definition

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/support-helpers.md

Defines the global webAppData() helper function that returns the webAppData request attribute or null. Guarded with function_exists and autoloaded via composer.json.

```php
namespace Nutgram\Laravel\Support;

use SergiX44\Nutgram\Telegram\Web\WebAppData;

if (!function_exists(__NAMESPACE__.'\webAppData')) {
    function webAppData(): ?WebAppData
    {
        return request()?->get('webAppData');
    }
}
```

--------------------------------

### nutgram:hook:set

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-hook-commands.md

Sets the bot webhook URL. This command accepts a URL argument and optional IP and max connections options.

```APIDOC
## [COMMAND] nutgram:hook:set

### Description
Sets the bot webhook URL.

### Command
`php artisan nutgram:hook:set {url} {--ip=} {--max-connections=50}`

### Arguments
- **url** (string) - Required - Webhook URL.

### Options
- **--ip** (?string) - Optional - Fixed IP address for the webhook.
- **--max-connections** (?int) - Optional - Max connections; cast to `int` when numeric. Default: `50`.

### Behavior
Calls `$bot->setWebhook(url: $url, ip_address: $ip_address, max_connections: $max_connections, secret_token: config('nutgram.safe_mode', false) ? md5(config('app.key')) : null)`.

Prints `Bot webhook set with url: {url}`; returns `0`.

### Exceptions
- `SergiX44\Nutgram\Telegram\Exceptions\TelegramException`
- `GuzzleHttp\Exception\GuzzleException`
- `JsonException`

### Example
```bash
php artisan nutgram:hook:set https://example.com/telegram/webhook
php artisan nutgram:hook:set https://example.com/hook --ip=1.2.3.4 --max-connections=100
```
```

--------------------------------

### LoggerHandler::formatText()

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/logging.md

Formats a log record into an HTML string for Telegram delivery. The format is `<b>{app.name} {LEVEL}</b> ({env}):\n<pre>{record->formatted}</pre>`.

```APIDOC
## LoggerHandler::formatText()

### Description
Formats a log record into an HTML string for Telegram delivery. The format is `<b>{app.name} {LEVEL}</b> ({env}):\n<pre>{record->formatted}</pre>`.

### Method
formatText

### Parameters
- `record` (`Monolog\LogRecord`) - Required - The log record to format.

### Return Type
`string` - The formatted HTML string.
```

--------------------------------

### Test bot with fake Telegram facade

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Uses Telegram::fake() to swap the facade for testing, registers a text handler, simulates a text message, and asserts the reply text.

```php
Telegram::fake();
Telegram::onText('/start', fn (Nutgram $bot) => $bot->sendMessage('hello'));

Telegram::hearText('/start')->reply();
Telegram::assertReplyText('hello');
```

--------------------------------

### webAppData()

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/support-helpers.md

Retrieves the validated Web App data from the current request. Returns null if no request is active or the attribute is absent.

```APIDOC
## Function: webAppData()

### Description
Returns the value of the `webAppData` request attribute set by the `ValidateWebAppData` middleware, or `null` when no request is active or the attribute is absent.

### Signature
```php
function webAppData(): ?SergiX44\Nutgram\Telegram\Web\WebAppData
```

### Parameters
None.

### Return Value
- **Type:** `?SergiX44\Nutgram\Telegram\Web\WebAppData`
- **Description:** The validated Web App data, or `null` if unavailable.

### Behavior
- Uses the Laravel `request()` helper to fetch the `webAppData` attribute.
- Returns `null` when `request()` resolves to `null` or the attribute is not set.
- The attribute is populated by the `ValidateWebAppData` middleware.

### Usage Example
```php
use function Nutgram\Laravel\Support\webAppData;

Route::post('/webapp', function () {
    $data = webAppData(); // ?WebAppData

    if ($data === null) {
        return response('invalid data', 403);
    }

    return response()->json([
        'user' => $data->user,
        'authDate' => $data->authDate,
    ]);
})->middleware(ValidateWebAppData::class);
```

### Notes
- The `WebAppData` type is defined by the upstream `nutgram/nutgram` dependency.
- The function is autoloaded globally and guarded with `function_exists`.
```

--------------------------------

### write method

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/logging.md

Delivers the log record to the Telegram chat. Throws InvalidArgumentException if chatId is null, with message about NUTGRAM_LOG_CHAT_ID. On success, sends chunked message with HTML parse mode.

```php
protected function write(LogRecord $record): void
```

--------------------------------

### Safe mode configuration

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/laravel-webhook.md

Configuration snippet showing how to enable safe mode in config/nutgram.php or via APP_ENV=production.

```php
'safe_mode' => true, // or APP_ENV=production
```

--------------------------------

### Send message with full options via Telegram facade

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Sends a message with text, parse mode, and an inline keyboard with a button. Uses named arguments and fluent keyboard construction.

```php
Telegram::sendMessage(
    text: 'Hello from Laravel!',
    parse_mode: ParseMode::HTML,
    reply_markup: InlineKeyboardMarkup::make()
        ->addInlineButton(InlineKeyboardButton::make('Button', callback_data: 'btn')),
);
```

--------------------------------

### nutgram:register-commands

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/console-hook-commands.md

Registers the bot command list. This command calls the upstream `registerMyCommands` method.

```APIDOC
## [COMMAND] nutgram:register-commands

### Description
Registers the bot command list.

### Command
`php artisan nutgram:register-commands`

### Behavior
Calls `$bot->registerMyCommands()`, prints "Bot commands set.", returns `0`. No declared throws; exceptions from the upstream call propagate.

### Example
```bash
php artisan nutgram:register-commands
```
```

--------------------------------

### NutgramFormatter::format() method signature

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/logging.md

Public method signature for formatting a single log record. It dispatches to formatRequest() or formatResponse() based on context['type'], and does nothing for other types.

```php
public function format(LogRecord $record): void
```

--------------------------------

### Bot API Client Methods

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Methods forwarded to the Bot API client for interacting with Telegram's Bot API. These methods cover messaging, chat management, stickers, payments, and more.

```APIDOC
## Bot API Client Methods

### Description
These methods are forwarded to the Bot API client (`SergiX44\Nutgram\Telegram\Client`) and provide direct access to Telegram Bot API endpoints.

### Methods
- `getMe`
- `logOut`
- `close`
- `sendMessage`
- `forwardMessage`
- `forwardMessages`
- `copyMessage`
- `copyMessages`
- `sendPhoto`
- `sendAudio`
- `sendDocument`
- `sendVideo`
- `sendAnimation`
- `sendVoice`
- `sendVideoNote`
- `sendPaidMedia`
- `sendMediaGroup`
- `sendLocation`
- `stopMessageLiveLocation`
- `sendVenue`
- `sendContact`
- `sendPoll`
- `sendChecklist`
- `sendDice`
- `sendMessageDraft`
- `sendChatAction`
- `setMessageReaction`
- `getUserProfilePhotos`
- `getUserProfileAudios`
- `setUserEmojiStatus`
- `getFile`
- `banChatMember`
- `unbanChatMember`
- `restrictChatMember`
- `promoteChatMember`
- `setChatAdministratorCustomTitle`
- `setChatMemberTag`
- `banChatSenderChat`
- `unbanChatSenderChat`
- `setChatPermissions`
- `exportChatInviteLink`
- `createChatInviteLink`
- `editChatInviteLink`
- `createChatSubscriptionInviteLink`
- `editChatSubscriptionInviteLink`
- `revokeChatInviteLink`
- `approveChatJoinRequest`
- `declineChatJoinRequest`
- `setChatPhoto`
- `deleteChatPhoto`
- `setChatTitle`
- `setChatDescription`
- `pinChatMessage`
- `unpinChatMessage`
- `unpinAllChatMessages`
- `leaveChat`
- `getChat`
- `getChatAdministrators`
- `getChatMemberCount`
- `getChatMember`
- `setChatStickerSet`
- `deleteChatStickerSet`
- `getForumTopicIconStickers`
- `createForumTopic`
- `editForumTopic`
- `closeForumTopic`
- `reopenForumTopic`
- `deleteForumTopic`
- `unpinAllForumTopicMessages`
- `editGeneralForumTopic`
- `closeGeneralForumTopic`
- `reopenGeneralForumTopic`
- `hideGeneralForumTopic`
- `unhideGeneralForumTopic`
- `answerCallbackQuery`
- `getUserChatBoosts`
- `getBusinessConnection`
- `setMyCommands`
- `deleteMyCommands`
- `getMyCommands`
- `getMyName`
- `setMyName`
- `setMyDescription`
- `getMyDescription`
- `setMyShortDescription`
- `getMyShortDescription`
- `setMyProfilePhoto`
- `removeMyProfilePhoto`
- `setChatMenuButton`
- `getChatMenuButton`
- `setMyDefaultAdministratorRights`
- `getMyDefaultAdministratorRights`
- `unpinAllGeneralForumTopicMessages`
- `getUserGifts`
- `getChatGifts`
- `repostStory`
- `editMessageText`
- `editMessageCaption`
- `editMessageMedia`
- `editMessageLiveLocation`
- `editMessageChecklist`
- `editMessageReplyMarkup`
- `stopPoll`
- `approveSuggestedPost`
- `declineSuggestedPost`
- `deleteMessage`
- `deleteMessages`
- `giftPremiumSubscription`
- `readBusinessMessage`
- `deleteBusinessMessages`
- `setBusinessAccountName`
- `setBusinessAccountUsername`
- `setBusinessAccountBio`
- `setBusinessAccountProfilePhoto`
- `removeBusinessAccountProfilePhoto`
- `setBusinessAccountGiftSettings`
- `getBusinessAccountStarBalance`
- `transferBusinessAccountStars`
- `getBusinessAccountGifts`
- `convertGiftToStars`
- `upgradeGift`
- `transferGift`
- `postStory`
- `editStory`
- `deleteStory`
- `sendSticker`
- `getStickerSet`
- `uploadStickerFile`
- `createNewStickerSet`
- `addStickerToSet`
- `setStickerPositionInSet`
- `setCustomEmojiStickerSetThumbnail`
- `deleteStickerFromSet`
- `replaceStickerInSet`
- `setStickerEmojiList`
- `setStickerKeywords`
- `setStickerMaskPosition`
- `setStickerSetThumbnail`
- `getCustomEmojiStickers`
- `setStickerSetTitle`
- `deleteStickerSet`
- `getAvailableGifts`
- `sendGift`
- `verifyUser`
- `verifyChat`
- `removeUserVerification`
- `removeChatVerification`
- `answerInlineQuery`
- `answerWebAppQuery`
- `savePreparedInlineMessage`
- `sendInvoice`
- `createInvoiceLink`
- `answerShippingQuery`
- `answerPreCheckoutQuery`
- `getMyStarBalance`
- `getStarTransactions`
- `editUserStarSubscription`
- `refundStarPayment`
- `setPassportDataErrors`
- `sendGame`
- `setGameScore`
- `getGameHighScores`
- `sendChunkedMessage`
- `sendChunkedPhoto`
- `sendChunkedAudio`
- `sendChunkedDocument`
- `sendChunkedVideo`
- `sendChunkedAnimation`
- `sendChunkedVoice`
```

--------------------------------

### fake method

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Swaps the facade root with a fresh fake bot for testing. After calling, forwarded calls are intercepted by FakeNutgram, enabling assertions like assertReplyText(). Does not replace the container binding.

```php
public static function fake(): void
```

--------------------------------

### NutgramFormatter::formatResponse() method signature

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/logging.md

Public method signature for formatting a response log record. Renders the logging::response view with time, message, and response from the record context.

```php
public function formatResponse(LogRecord $record): void
```

--------------------------------

### setWebhook(...)

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Sets the webhook URL for the bot to receive updates.

```APIDOC
## setWebhook(...)

### Description
Sets the webhook URL for the bot to receive updates.

### Method
setWebhook

### Signature
```php
@method static bool|null setWebhook(string $url, \SergiX44\Nutgram\Telegram\Types\Internal\InputFile|null $certificate = null, string|null $ip_address = null, int|null $max_connections = null, string[]|null $allowed_updates = ['message','edited_message','channel_post','edited_channel_post','business_connection','business_message','edited_business_message','deleted_business_messages','message_reaction','message_reaction_count','inline_query','chosen_inline_result','callback_query','shipping_query','pre_checkout_query','purchased_paid_media','poll','poll_answer','my_chat_member','chat_member','chat_join_request','chat_boost','removed_chat_boost'], bool|null $drop_pending_updates = null, string|null $secret_token = null)
```

```

--------------------------------

### webAppData() function signature

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/support-helpers.md

The function signature for webAppData(), showing the return type ?SergiX44\Nutgram\Telegram\Web\WebAppData.

```php
function webAppData(): ?SergiX44\Nutgram\Telegram\Web\WebAppData
```

--------------------------------

### Macros

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Methods for managing macros in the Nutgram library. These allow defining and checking custom macros.

```APIDOC
## Macros

### Description
These methods are used to define, check, and manage macros in the Nutgram library.

### Methods
- `macro`
- `mixin`
- `hasMacro`
- `flushMacros`
```

--------------------------------

### middlewares(mixed $callable)

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Adds multiple middlewares to the bot's request pipeline.

```APIDOC
## middlewares(mixed $callable)

### Description
Adds multiple middlewares to the bot's request pipeline.

### Method
middlewares

### Signature
```php
@method static void middlewares(mixed $callable)
```

```

--------------------------------

### middleware(callable|mixed|array $callable)

Source: https://github.com/nutgram/laravel/blob/master/_autodocs/api-reference/telegram-facade.md

Adds a middleware to the bot's request pipeline.

```APIDOC
## middleware(callable|mixed|array $callable)

### Description
Adds a middleware to the bot's request pipeline.

### Method
middleware

### Signature
```php
@method static void middleware(callable|mixed|array $callable)
```

```
Tokens:
Raw