Nutgram

https://nutgram.dev/docs/
Admin
Nutgram is a PHP 8.2 Telegram bot framework designed for speed, scalability, and flexibility,...
Tokens:59,294
Snippets:734
Trust Score:6.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Basic Nutgram Bot Setup

Source: https://nutgram.dev/docs/3.x/usage/getting_updates

This snippet shows the fundamental setup for a Nutgram bot, including instantiation and calling the run method to process updates. It's a common starting point for any Nutgram application.

```php
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']); // new instance  
  
// register callbacks  
// middlewares  
// do your stuff  
  
$bot->run(); // finally, begin to process incoming updates  

```

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

### Basic Message Handler Setup - PHP

Source: https://nutgram.dev/docs/3.x/usage/handlers

Sets up a basic message handler to respond to any incoming message. The bot instance is created using an environment variable for the token, and the run method is called to start processing updates. Chat ID is automatically inferred from the update context.

```php
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onMessage(function (Nutgram $bot) {  
    $bot->sendMessage('You sent a message!');  
});  
  
$bot->run();  

```

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

### Basic Nutgram Bot Setup and Handlers

Source: https://nutgram.dev/docs/3.x/introduction

This snippet demonstrates the basic setup of a Nutgram bot using an environment variable for the token. It includes handlers for the '/start' command and text messages with parameter extraction.

```php
<?php  
  
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onCommand('start', function(Nutgram $bot) {  
    $bot->sendMessage('Ciao!');  
});  
  
$bot->onText('My name is {name}', function(Nutgram $bot, string $name) {  
    $bot->sendMessage("Hi $name");  
});  
  
$bot->run();  
  

```

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

### Setup and Assert Mocked Replies

Source: https://nutgram.dev/docs/3.x/testing/introduction

Set up a fake Nutgram instance and define assertions for mocked API replies. This example demonstrates how to check for specific `sendMessage` calls with expected arguments.

```php
use PHPUnit\Framework\TestCase;
use SergiX44\Nutgram\Testing\FakeNutgram;
use SergiX44\Nutgram\Nutgram;

class BotTest extends TestCase
{
    private FakeNutgram $bot;
      
    public function setUp(): void 
    {
        $this->bot = Nutgram::fake();
        $this->bootInstance($this->bot);      
    }
  
  
    public function test_retrieve_mocked_instance(): void
    {
        // define assertions
        $this->bot->reply()
            ->assertReply('sendMessage', ['text' => 'bar'], 0)
            ->assertReply('sendMessage', ['text' => 'baz'], 1);
    }
}
```

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

### InlineMenu Example

Source: https://nutgram.dev/docs/3.x/usage/inline_menu

An example demonstrating how to create and use an `InlineMenu` subclass to handle user choices.

```APIDOC
## Example

```php
class ChooseColorMenu extends InlineMenu
{
    public function start(Nutgram $bot)
    {
        $this->menuText('Choose a color:')
            ->addButtonRow(InlineKeyboardButton::make('Red', callback_data: 'red@handleColor'))
            ->addButtonRow(InlineKeyboardButton::make('Green', callback_data: 'green@handleColor'))
            ->addButtonRow(InlineKeyboardButton::make('Yellow', callback_data: 'yellow@handleColor'))
            ->orNext('none')
            ->showMenu();
    }

    public function handleColor(Nutgram $bot)
    {
        $color = $bot->callbackQuery()->data;
        $this->menuText("Choosen: $color!")
            ->showMenu();
    }

    public function none(Nutgram $bot)
    {
        $bot->sendMessage('Bye!');
        $this->end();
    }
}
```
```

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

### Basic Nutgram Bot Setup

Source: https://nutgram.dev/docs/introduction

This snippet demonstrates the basic setup for a Nutgram bot, including initializing the bot with a token and defining command and text handlers. It shows how to respond to the /start command and text messages containing a name.

```php
<?php  
  
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onCommand('start', function(Nutgram $bot) {  
    $bot->sendMessage('Ciao!');  
});  
  
$bot->onText('My name is {name}', function(Nutgram $bot, string $name) {  
    $bot->sendMessage("Hi $name");  
});  
  
$bot->run();  
  


```

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

### Complete Conversation Example with Inline Keyboard

Source: https://nutgram.dev/docs/usage/conversations

A comprehensive example demonstrating a multi-step conversation that includes asking for user input via an inline keyboard and processing callback queries.

```PHP
use SergiX44\Nutgram\Conversations\Conversation;  
use SergiX44\Nutgram\Nutgram;  
use SergiX44\Nutgram\Telegram\Types\Keyboard\InlineKeyboardButton;  
use SergiX44\Nutgram\Telegram\Types\Keyboard\InlineKeyboardMarkup;  
  
class AskIceCreamConversation extends Conversation {  
  
    protected ?string $step = 'askCupSize';  
  
    public $cupSize;  
  
    public function askCupSize(Nutgram $bot)  
    {  
        $bot->sendMessage(  
            text: 'How big should be you ice cream cup?',   
            reply_markup: InlineKeyboardMarkup::make()  
                ->addRow(InlineKeyboardButton::make('Small', callback_data: 'S'), InlineKeyboardButton::make('Medium', callback_data: 'M'))  
                ->addRow(InlineKeyboardButton::make('Big', callback_data: 'L'), InlineKeyboardButton::make('Super Big', callback_data: 'XL')),  
        );  
        $this->next('askFlavors');  
    }  
  
    public function askFlavors(Nutgram $bot)  
    {  
        // if is not a callback query, ask again!  
        if (!$bot->isCallbackQuery()) {  
            $this->askCupSize($bot);  
            return;  
        }  
  
        $this->cupSize = $bot->callbackQuery()->data;  
  
        $bot->sendMessage('What flavors do you like?');  
        $this->next('recap');  
    }  
  
    public function recap(Nutgram $bot)  
    {  
        $flavors = $bot->message()->text;  
        $bot->sendMessage("You want an $this->cupSize cup with this flavors: $flavors");  
        $this->end();  
    }  
}
```

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

### Set Up Fake Instance with Handlers

Source: https://nutgram.dev/docs/testing/introduction

Configure a fake Nutgram instance with handlers and middleware for comprehensive testing. The `setUp` method is a common place to register these.

```php
use PHPUnit\Framework\TestCase;  
use SergiX44\Nutgram\Testing\FakeNutgram;  
use SergiX44\Nutgram\Nutgram;  
  
class BotTest extends TestCase  
{
    private FakeNutgram $bot;  
      
    public function setUp(): void   
    {
        $this->bot = Nutgram::fake();  
          
        // your custom method to register handlers  
        $this->bootInstance($this->bot);  
          
        /*  
         * Example:  
         *   
         * $this->bot->onCommand('hello', function (Nutgram $bot) {  
         *     $bot->sendMessage('Hello!');  
         * });  
         */  
    }


    public function test_retrieve_mocked_instance(): void  
    {
        // define assertions  
        $this->bot  
            ->hearText('/hello')  
            ->reply()  
            ->assertReplyText('Hello!');  
    }
}

```

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

### Basic Grouping with Middleware

Source: https://nutgram.dev/docs/3.x/usage/middleware

This example demonstrates how to group routes under a middleware using Nutgram.

```php
$bot = new Nutgram('TOKEN');  
  
$bot->group(CheckUserMiddleware::class, function(Nutgram $bot){  
    $bot->onCallbackQueryData('user/([0-9]+)/show', [UserController::class, 'show']);  
    $bot->onCallbackQueryData('user/([0-9]+)/edit', [UserController::class, 'edit']);  
    $bot->onCallbackQueryData('user/([0-9]+)/delete', [UserController::class, 'delete']);  
});  
  
$bot->run();  


```

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

### Handle Incoming Messages with Nutgram

Source: https://nutgram.dev/docs/usage/handlers

This snippet demonstrates the basic setup for handling any incoming message using the `onMessage` handler. It initializes the Nutgram bot with a token and defines a closure to send a reply when a message is received. The bot is then started using `run()`.

```php
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onMessage(function (Nutgram $bot) {  
    $bot->sendMessage('You sent a message!');  
});  
  
$bot->run();  
```

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

### Install Nutgram via Composer

Source: https://nutgram.dev/docs/3.x/configuration/installation

Use Composer to add the Nutgram package to your project. This is the standard method for installation.

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

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

### Register Command with Custom Middleware

Source: https://nutgram.dev/docs/usage/middleware

Example of registering a command that uses a custom middleware class.

```php
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onCommand('start {param}', MyCommand::class)  
    ->middleware(MyMiddleware::class);  
  
$bot->run();  
  

```

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

### Basic Bulk Messenger Usage (Sync)

Source: https://nutgram.dev/docs/3.x/usage/bulk_messenger

Demonstrates how to set up and start the Bulk Messenger to send messages synchronously in a script. Requires setting chats, text, and optional parameters.

```php
use SergiX44\Nutgram\Nutgram;

$bot = new Nutgram($_ENV['TOKEN']);

$chats = [];

// Using the default sendMessage method ***************************************

// in scripts
$bot->getBulkMessenger()
    ->setChats($chats)
    ->setText('Hello!')
    ->setOpt([/* optional parameters */])
    ->startSync()

```

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

### Nutgram Bot Initialization with Options

Source: https://nutgram.dev/docs/3.x/configuration/installation

Initialize a Nutgram bot instance with the API token and a configuration array for custom options. The 'timeout' option is shown as an example.

```php
use SergiX44\Nutgram\Nutgram;
  
$config = [
    'timeout' => 10, // default in seconds, when contacting the Telegram API  
];  
  
$bot = new Nutgram('you telegram token here', $config);  
```

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

### Start Conversation with Command

Source: https://nutgram.dev/docs/usage/conversations

Initiates a conversation when a specific command is received. The first step of the conversation is automatically triggered.

```php
use SergiX44\Nutgram\StartConversation;  
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onCommand('start', StartConversation::class);  
  
$bot->run();  


```

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

### Install Nutgram Symfony Bundle

Source: https://nutgram.dev/docs/3.x/configuration/symfony

Install the Nutgram Symfony bundle using Composer. If you previously installed the base package, remove it first.

```bash
composer require nutgram/symfony-bundle  
  
# remove the base package if you have installed it:  
# composer remove nutgram/nutgram  
```

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

### Start Conversation from Handler

Source: https://nutgram.dev/docs/usage/conversations

Starts a conversation from within another handler. The `begin` method is used, and the first step of the conversation is automatically fired.

```php
use SergiX44\Nutgram\StartConversation;  
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onCommand('start', function (Nutgram $bot) {  
    // do stuff  
    StartConversation::begin($bot); // the first step will be automatically fired  
});  
  
$bot->run();  


```

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

### Define Middleware with Callback Query Handlers

Source: https://nutgram.dev/docs/usage/middleware

This example shows how to group callback query handlers and apply a middleware to them. The middleware is intended to check user permissions based on the callback query data.

```php
$bot = new Nutgram('TOKEN');  
  
$bot->group(function(Nutgram $bot){  
    $bot->onCallbackQueryData('user/([0-9]+)/show', [UserController::class, 'show']);  
    $bot->onCallbackQueryData('user/([0-9]+)/edit', [UserController::class, 'edit']);  
    $bot->onCallbackQueryData('user/([0-9]+)/delete', [UserController::class, 'delete']);  
})->middleware(CheckUserMiddleware::class);  
  
$bot->run();  


```

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

### Start Conversation with Command

Source: https://nutgram.dev/docs/3.x/usage/conversations

Initiates a conversation when a specific command is received. The conversation class is directly mapped to the command.

```PHP
use SergiX44\Nutgram\StartConversation; 
use SergiX44\Nutgram\Nutgram; 
 
$bot = new Nutgram($_ENV['TOKEN']); 
 
$bot->onCommand('start', StartConversation::class); 
 
$bot->run(); 

```

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

### Define a Basic Conversation

Source: https://nutgram.dev/docs/usage/conversations

Define a conversation with multiple steps. The `start` method is the default entry point. Use `next()` to transition to the next step and `end()` to finish.

```PHP
use SergiX44\Nutgram\Conversations\Conversation;  
use SergiX44\Nutgram\Nutgram;  
  
class MyConversation extends Conversation {  
  
    public function start(Nutgram $bot)  
    {  
        $bot->sendMessage('This is the first step!');  
        $this->next('secondStep');  
    }  
  
    public function secondStep(Nutgram $bot)  
    {  
        $bot->sendMessage('Bye!');  
        $this->end();  
    }  
}  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onCommand('start', MyConversation::class);  
  
$bot->run();  
```

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

### Define a Basic Conversation

Source: https://nutgram.dev/docs/3.x/usage/conversations

Create a conversation by extending the `Conversation` class and defining steps as methods. The `start` method is the default entry point. Use `next()` to define the subsequent step and `end()` to terminate the conversation.

```php
use SergiX44\Nutgram\Conversations\Conversation;
use SergiX44\Nutgram\Nutgram;

class MyConversation extends Conversation {

    public function start(Nutgram $bot)
    {
        $bot->sendMessage('This is the first step!');
        $this->next('secondStep');
    }

    public function secondStep(Nutgram $bot)
    {
        $bot->sendMessage('Bye!');
        $this->end();
    }
}

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('start', MyConversation::class);

$bot->run();

```

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

### Creating an Inline Menu with Buttons

Source: https://nutgram.dev/docs/3.x/usage/inline_menu

This example demonstrates how to create an inline menu with multiple button rows. Each button is configured with text and a callback data that maps to a specific handler method. The `orNext` method specifies a fallback handler if no button matches, and `showMenu` sends the message.

```php
class ChooseColorMenu extends InlineMenu
{

    public function start(Nutgram $bot)
    {
        $this->menuText('Choose a color:')
            ->addButtonRow(InlineKeyboardButton::make('Red', callback_data: 'red@handleColor'))
            ->addButtonRow(InlineKeyboardButton::make('Green', callback_data: 'green@handleColor'))
            ->addButtonRow(InlineKeyboardButton::make('Yellow', callback_data: 'yellow@handleColor'))
            ->orNext('none')
            ->showMenu();
    }

    public function handleColor(Nutgram $bot)
    {
        $color = $bot->callbackQuery()->data;
        $this->menuText("Choosen: $color!")
            ->showMenu();
    }

    public function none(Nutgram $bot)
    {
        $bot->sendMessage('Bye!');
        $this->end();
    }
}

```

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

### Begin Conversation from Handler

Source: https://nutgram.dev/docs/3.x/usage/conversations

Starts a conversation dynamically from within another handler. The first step of the conversation is automatically triggered.

```PHP
use SergiX44\Nutgram\StartConversation; 
use SergiX44\Nutgram\Nutgram; 
 
$bot = new Nutgram($_ENV['TOKEN']); 
 
$bot->onCommand('start', function (Nutgram $bot) { 
    // do stuff 
    StartConversation::begin($bot); // the first step will be automatically fired 
}); 
 
$bot->run(); 

```

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

### Accessing All Resolved Handler Parameters

Source: https://nutgram.dev/docs/3.x/usage/middleware

This example shows how to access all parameters from all resolved handlers in the current update context using `currentParameters`. Be cautious as this can lead to unexpected results if not used carefully.

```php
// CheckUserMiddleware.php  
class CheckUserMiddleware  
{  
    public function __invoke(Nutgram $bot, $next)  
    {  
        $parameters = $bot->currentParameters();  
        //$parameters[0] = 'your-value'; <= for onCallbackQueryData('user/([0-9]+)/show')  
        //$parameters[1] = 'your-value'; <= for onCallbackQueryData('user/([0-9]+)/.*')  
        $next($bot);  
    }  
}  
  
// bot.php  
$bot = new Nutgram('TOKEN');  
  
$bot->group(CheckUserMiddleware::class, function(Nutgram $bot){  
    $bot->onCallbackQueryData('user/([0-9]+)/show', [UserController::class, 'show']);  
    $bot->onCallbackQueryData('user/([0-9]+)/.*', [UserController::class, 'edit']);  
});  
  
$bot->run();  


```

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

### Sending a Document with File Details

Source: https://nutgram.dev/docs/3.x/testing/asserting

Example of sending a document using `sendDocument` with a file resource, caption, and parse mode. Ensure the file is properly opened and closed.

```php
$bot->onText('foo', function (Nutgram $bot) {  
    $file = fopen('image.jpg', 'r');  
    $bot->sendDocument(InputFile::make(file, 'name.jpg'), [  
        'caption' => 'my caption',  
        'parse_mode' => ParseMode::HTML,  
    ]);  
    fclose($file);  
});  

```

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

### Start Conversation Server-Side

Source: https://nutgram.dev/docs/usage/conversations

Initiates a conversation programmatically from the server without direct user interaction. Requires explicit `userId` and `chatId`.

```php
use SergiX44\Nutgram\StartConversation;  

StartConversation::begin(  
    bot: $bot,   
    userId: $userID,   
    chatId: $chatID  
);  


```

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

### Customize Conversation Start Step

Source: https://nutgram.dev/docs/3.x/usage/conversations

Override the protected `$step` property to customize the name of the initial method invoked when a conversation begins.

```php
use SergiX44\Nutgram\Conversations\Conversations\Conversation;
use SergiX44\Nutgram\Nutgram;

class MyConversation extends Conversation {

    protected ?string $step = 'myStart';

    public function myStart(Nutgram $bot)
    {
        $bot->sendMessage('This is the first step!');
    }

    // ...


```

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

### Passing Parameters to Conversation via Handler

Source: https://nutgram.dev/docs/usage/conversations

Starts a conversation from a command that includes parameters, which are then passed to the conversation's constructor or methods.

```php
$bot->onCommand('start {name}', StartConversation::class);  


```

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

### Starting a Conversation with Caching

Source: https://nutgram.dev/docs/3.x/testing/mocking

Use `willStartConversation` to cache the `userId` and `chatId`. This is particularly helpful when testing conversations using `assertActiveConversation` and `assertNoConversation`.

```php
->willStartConversation(remember: true);

```

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

### Get Download Progress with withProgress

Source: https://nutgram.dev/docs/usage/sending_requests

Track the download progress of a file by using the `withProgress` method before calling `downloadFile`. The callback receives progress information for each byte downloaded.

```php
use SergiX44\Nutgram\Nutgram;  
use SergiX44\Nutgram\Telegram\Types\Media\File;  
use SergiX44\Nutgram\Progress;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onSticker(function (Nutgram $bot) {  
    // get the file_id  
    $fileId = $bot->message()->sticker->file_id;  
      
    // get the File  
    $file = $bot->getFile($fileId);  
      
    // download the file  
    $bot  
      ->withProgress(function (Progress $progress) {  
          echo sprintf("Downloading file: %s%% - Downloaded: %s bytes of %s bytes\n",  
              $progress->downloadPercentage(),  
              $progress->downloadedBytes,  
              $progress->totalDownloadBytes,  
          );  
      })  
      ->downloadFile($file, 'file.ext');  
});  


```

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

### Advanced Rate Limiter Configuration

Source: https://nutgram.dev/docs/usage/rate_limiting

Demonstrates a complex setup combining global, group, and handler-specific rate limits to manage request frequency across different bot functionalities.

```php
$bot = new Nutgram('your-token-here');
$bot->throttle(4);

$bot->onCommand('start', StartCommand::class); // 4 messages per minute
$bot->onCommand('help', HelpCommand::class)->throttle(2); // 2 messages per minute

$bot->group(function (Nutgram $bot) {

    $bot->onCommand('feedback', FeedbackCommand::class); // 3 messages per minute
    $bot->onCommand('stats', StatsCommand::class)->throttle(2); // 2 messages per minute
    $bot->onCommand('what', WhatCommand::class)->throttle(5); // 5 messages per minute

    $bot->group(function (Nutgram $bot) {
      
        $bot->onCommand('settings', SettingsCommand::class); // 2 messages per minute
        $bot->onCommand('donate', DonateCommand::class)->throttle(1); // 1 message per minute
        $bot->onCommand('refund', RefundCommand::class)->throttle(3); // 3 messages per minute
          
    })->throttle(2);
      
})->throttle(3);


```

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

### Define Global and Specific Middleware

Source: https://nutgram.dev/docs/3.x/usage/middleware

This example demonstrates how to define both global middleware that applies to all message handlers and specific middleware for a single message handler. Global middleware is registered using `$bot->middleware()`, and specific middleware is attached to a handler using `->middleware()`.

```php
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
// global middleware  
$bot->middleware(function (Nutgram $bot, $next) {  
    $bot->sendMessage('I\'m the global middleware!!');  
    $next($bot);  
});  
  
$bot->onMessage(function (Nutgram $bot) {  
    $bot->sendMessage('I\'m the message handler!!');  
})->middleware(function (Nutgram $bot, $next) {  
  
    $bot->sendMessage('I\'m the specific middleware!!');  
    $next($bot);  
});  
  
$bot->run();  

```

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

### Advanced Conversation with Inline Keyboard

Source: https://nutgram.dev/docs/3.x/usage/conversations

An example of a more complex conversation flow that uses an inline keyboard to gather user input for ice cream preferences. It demonstrates handling callback queries and re-prompting if the input is not a callback.

```php
use SergiX44\Nutgram\Conversations\Conversation;
use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Types\Keyboard\InlineKeyboardButton;
use SergiX44\Nutgram\Telegram\Types\Keyboard\InlineKeyboardMarkup;

class AskIceCreamConversation extends Conversation {

    protected ?string $step = 'askCupSize';

    public $cupSize;

    public function askCupSize(Nutgram $bot)
    {
        $bot->sendMessage('How big should be you ice cream cup?', [
            'reply_markup' => InlineKeyboardMarkup::make()
                ->addRow(InlineKeyboardButton::make('Small', callback_data: 'S'), InlineKeyboardButton::make('Medium', callback_data: 'M'))
                ->addRow(InlineKeyboardButton::make('Big', callback_data: 'L'), InlineKeyboardButton::make('Super Big', callback_data: 'XL')),
        ]);
        $this->next('askFlavors');
    }

    public function askFlavors(Nutgram $bot)
    {
        // if is not a callback query, ask again!
        if (!$bot->isCallbackQuery()) {
            $this->askCupSize($bot);
            return;
        }

        $this->cupSize = $bot->callbackQuery()->data;

        $bot->sendMessage('What flavors do you like?');
        $this->next('recap');
    }

    public function recap(Nutgram $bot)
    {
        $flavors = $bot->message()->text;
        $bot->sendMessage("You want an $this->cupSize cup with this flavors: $flavors");
        $this->end();
    }
}


```

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

### Install Nutgram Laravel Package

Source: https://nutgram.dev/docs/configuration/laravel

Use Composer to install the specific Laravel version of the Nutgram package. If you previously installed the base package, remove it first.

```bash
composer require nutgram/laravel  
  
# remove the base package if you have installed it:  
# composer remove nutgram/nutgram  
```

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

### Initialize Nutgram Configuration

Source: https://nutgram.dev/docs/3.x/configuration/symfony

Run the Nutgram console command to create initial configuration files for handlers and bundle settings.

```bash
php bin/console nutgram:init  
```

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

### Apply Single and Multiple Middlewares to Groups

Source: https://nutgram.dev/docs/usage/middleware

Demonstrates applying a single middleware or a sequence of middlewares to a command group.

```php
// single middleware  
$bot->group(function (Nutgram $bot){
    // Your handlers here  
})->middleware(Middleware::class);

// multiple middlewares  
$bot->group(function (Nutgram $bot){
    // Your handlers here  
})
->middleware(Middleware1::class)
->middleware(Middleware2::class);

```

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

### Install Nutgram Laravel Package

Source: https://nutgram.dev/docs/upgrading/from-3.x-to-4.x

Install the nutgram/laravel package to continue using Laravel functionality with Nutgram. This package includes the core nutgram/nutgram functionality.

```bash
composer require nutgram/laravel  

```

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

### Upload video via InputFile (file resource)

Source: https://nutgram.dev/docs/usage/sending_requests

For uploading videos, you can pass a file resource descriptor (obtained via `fopen`) to `InputFile::make()`. The framework handles the upload.

```php
use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Types\Internal\InputFile;
use SergiX44\Nutgram\Telegram\Types\Message\Message;

$bot = new Nutgram($_ENV['TOKEN']);

$message = $bot->sendVideo(
    video: InputFile::make(fopen('funnyvideo.mp4', 'r+')),
    chat_id: 123456789
);

```

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

### Nutgram Bot Initialization with Configuration

Source: https://nutgram.dev/docs/configuration/installation

Initialize a Nutgram bot with custom configuration options, such as client timeout. The Configuration object allows for fine-tuning the bot's behavior.

```php
use SergiX44\Nutgram\Nutgram;  
use SergiX44\Nutgram\Configuration;  
  
$config = new Configuration(  
    clientTimeout: 10, // default in seconds, when contacting the Telegram API  
);  
  
$bot = new Nutgram('you telegram token here', $config);  
```

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

### Registering Commands via Command Classes

Source: https://nutgram.dev/docs/usage/handlers

Define commands as classes extending SergiX44\Nutgram\Handlers\Type\Command. Set the $description property to have the command automatically registered.

```php
// 1. create a command class like "StartCommand.php":  
  
namespace App\Telegram\Commands;  
  
use SergiX44\Nutgram\Handlers\Type\Command;  
use SergiX44\Nutgram\Nutgram;  
  
class StartCommand extends Command  
{
    // Called on command "/start"  
    protected string $command = 'start';  

    // It's possible to set a description for the current command  
    // this WILL be automatically registered  
    protected ?string $description = 'A lovely start command';  

    public function handle(Nutgram $bot): void  
    {
        $bot->sendMessage('Hello there!');  
    }
}
  
// 2. Register StartCommand inside Nutgram  
  
$bot->registerCommand(StartCommand::class);  
```

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

### Force Reply to User

Source: https://nutgram.dev/docs/3.x/usage/keyboards

Employ ForceReply to compel users to reply to a specific message. This is useful for guiding user input.

```PHP
$bot->onCommand('start', function(Nutgram $bot){  
    $bot->sendMessage('Welcome!', [  
        'reply_markup' => ForceReply::make(  
            force_reply: true,  
            input_field_placeholder: 'Type something',
            selective: true,  
        ),
    ]);  
});  

```

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

### Create and Handle Inline Keyboard

Source: https://nutgram.dev/docs/usage/keyboards

Use InlineKeyboardMarkup to create inline keyboards with buttons that trigger callback queries. Handle callbacks to respond to user selections.

```php
$bot->onCommand('start', function(Nutgram $bot){  
    $bot->sendMessage(  
        text: 'Welcome!',  
        reply_markup: InlineKeyboardMarkup::make()  
            ->addRow(  
                InlineKeyboardButton::make('A', callback_data: 'type:a'),  
                InlineKeyboardButton::make('B', callback_data: 'type:b')  
            )  
    );
});  
  
$bot->onCallbackQueryData('type:a', function(Nutgram $bot){  
    $bot->answerCallbackQuery(  
        text: 'You selected A'
    );
});  
  
$bot->onCallbackQueryData('type:b', function(Nutgram $bot){  
    $bot->answerCallbackQuery(  
        text: 'You selected B'
    );
});  

```

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

### Configure Nutgram Cache Pool

Source: https://nutgram.dev/docs/3.x/configuration/symfony

Configure a cache pool for Nutgram in `config/packages/cache.yaml` if `symfony/cache` is installed. Specify the adapter and enable tags.

```yaml
# config/packages/cache.yaml  
framework:  
  cache:  
  
    # ...  
  
    pools:  
      nutgram.cache:  
        adapter: cache.adapter.redis # or whatever adapter you want  
        tags: true  
  
```

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

### Register Bot Commands using Command Classes

Source: https://nutgram.dev/docs/3.x/usage/handlers

Defines a command class with a description property that is automatically registered. The `handle` method contains the command's logic.

```PHP
// 1. create a command class like "StartCommand.php":  
  
namespace App\Telegram\Commands;  
  
use SergiX44\Nutgram\Handlers\Type\Command;  
use SergiX44\Nutgram\Nutgram;  
  
class StartCommand extends Command  
{  
    // Called on command "/start"  
    protected string $command = 'start';  
  
    // It's possible to set a description for the current command  
    // this WILL be automatically registered  
    protected ?string $description = 'A lovely start command';  
  
    public function handle(Nutgram $bot): void  
    {  
        $bot->sendMessage('Hello there!');  
    }  
}  
  
// 2. Register StartCommand inside Nutgram  
  
$bot->registerCommand(StartCommand::class);  


```

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

### Create and Handle Inline Keyboard

Source: https://nutgram.dev/docs/3.x/usage/keyboards

Use InlineKeyboard to create buttons that trigger callbacks. Handle callback queries to respond to user selections.

```PHP
$bot->onCommand('start', function(Nutgram $bot){  
    $bot->sendMessage('Welcome!', [  
        'reply_markup' => InlineKeyboardMarkup::make()  
            ->addRow(  
                InlineKeyboardButton::make('A', callback_data: 'type:a'),   
                InlineKeyboardButton::make('B', callback_data: 'type:b')  
            )
    ]);  
});  

$bot->onCallbackQueryData('type:a', function(Nutgram $bot){  
    $bot->answerCallbackQuery([  
        'text' => 'You selected A'
    ]);  
});  

$bot->onCallbackQueryData('type:b', function(Nutgram $bot){  
    $bot->answerCallbackQuery([  
        'text' => 'You selected B'
    ]);  
});  

```

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

### FeedbackConversation Class Implementation

Source: https://nutgram.dev/docs/testing/examples

Defines the FeedbackConversation class, handling the start of the conversation, asking for feedback, and processing user input or cancellation.

```php
class FeedbackConversation extends Conversation
{
    public function start(Nutgram $bot): void
    {
        // ask for feedback
        $bot->sendMessage(
            text: 'Send your feedback',
            reply_markup: InlineKeyboardMarkup::make()->addRow(
                InlineKeyboardButton::make('Cancel', callback_data: 'feedback.cancel')
            ),
        );

        // wait for the user to send feedback
        $this->next('getFeedback');
    }

    public function getFeedback(Nutgram $bot): void
    {
        //handle cancel button
        if ($bot->callbackQuery()?->data === 'feedback.cancel') {
            $bot->sendMessage('Feedback cancelled');
            $bot->answerCallbackQuery();

            //close conversation
            $this->end();
            return;
        }

        //get the input
        $feedback = $bot->message()?->text;

        //check valid input
        if ($feedback === null) {
            $bot->sendMessage('Invalid input, please send your feedback again');
            $this->start($bot);
            return;
        }

        //save the feedback
        // TODO: save $feedback to database

        // thanks the user
        $bot->sendMessage('Thanks for your feedback!');

        //close conversation
        $this->end();
    }
}
```

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

### Custom Bulk Messenger Action (Document - Async)

Source: https://nutgram.dev/docs/usage/bulk_messenger

Demonstrates initiating the Bulk Messenger with a custom action to send a document asynchronously within a command handler. The bot must be run using `$bot->run()`.

```php
$bot->onCommand('start', function (Nutgram $bot) use ($document, $chats) {
    $bot->getBulkMessenger()
        ->setChats($chats)
        ->using(fn (Nutgram $bot, int $chatId) => $bot->sendDocument(document: $document, chat_id: $chatId))
        ->startAsync();
});
$bot->run()
```

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

### Nutgram Configuration Options

Source: https://nutgram.dev/docs/configuration/laravel

Review the default configuration options in config/nutgram.php. Keys starting with 'polling' should be nested in a sub-array, and all keys must be in snake_case.

```php
    // The Telegram BOT api token  
    'token' => env('TELEGRAM_TOKEN'),  
  
    // if the webhook mode must validate the incoming IP range is from a telegram server  
    'safe_mode' => env('APP_ENV', 'local') === 'production',  
  
    // Extra or specific configurations  
    'config' => [],  
  
    // Set if the service provider should automatically load  
    // handlers from /routes/telegram.php  
    'routes' => true,  
  
    // Enable or disable Nutgram mixins  
    'mixins' => false,  
  
    // Path to save files generated by nutgram:make command  
    'namespace' => app_path('Telegram'),  
  
    // Set log channel  
    'log_channel' => env('TELEGRAM_LOG_CHANNEL', 'null'),  

```

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

### Define Command Scope with `BotCommandScopeAllPrivateChats`

Source: https://nutgram.dev/docs/usage/middleware

The `scope()` method restricts command visibility. This example limits grouped commands to private chats using `BotCommandScopeAllPrivateChats`.

```php
use SergiX44\Nutgram\Nutgram;
use SergiX44\Nutgram\Telegram\Types\Command\BotCommandScopeAllPrivateChats;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('start', function (Nutgram $bot) {
    // 
})->description('Start command');

$bot->group(function (Nutgram $bot) {
    $bot->onCommand('private', function (Nutgram $bot) {   
        // 
    })->description('A command visible just in a private chat');      
      
    $bot->onCommand('private2', function (Nutgram $bot) {   
        // 
    })->description('Another command visible just in a private chat');  
})->scope(new BotCommandScopeAllPrivateChats());

$bot->run();

```

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

### Basic Bulk Messenger Usage (Sync)

Source: https://nutgram.dev/docs/usage/bulk_messenger

Demonstrates how to use the Bulk Messenger to send a text message synchronously in a script. Ensure the `TOKEN` environment variable is set.

```php
use SergiX44\Nutgram\Nutgram;

$bot = new Nutgram($_ENV['TOKEN']);

$chats = [];

// Using the default sendMessage method ***************************************

// in scripts
$bot->getBulkMessenger()
    ->setChats($chats)
    ->setText('Hello!')
    ->setOpt([/* optional parameters */])
    ->startSync()
```

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

### Set Reaction Type Emoji

Source: https://nutgram.dev/docs/usage/helpers

This example demonstrates how to set a message reaction using an emoji type. It requires importing Nutgram and ReactionTypeEmoji classes.

```php
use SergiX44\Nutgram\Nutgram;  
use SergiX44\Nutgram\Telegram\Types\Reaction\ReactionTypeEmoji;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onMessage(function (Nutgram $bot) {  
    $bot->setMessageReaction([  
        new ReactionTypeEmoji(ReactionTypeType::THUMBS_UP), // 👍  
    ]);  
});  
  
$bot->run();  


```

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

### Nesting Groups with Scopes and Middlewares

Source: https://nutgram.dev/docs/usage/middleware

Shows how to create nested command groups, applying different scopes and middlewares at each level.

```php
// nested middlewares  
$bot->group(function (Nutgram $bot){
    // Your handlers here  
  
    $bot->group(function (Nutgram $bot){
        // Your handlers here  
    })->scope(/* */)->middleware(Middleware2::class);
      
})->middleware(Middleware1::class)->scope(/* */);

```

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

### Configure ReplyKeyboardMarkup Options

Source: https://nutgram.dev/docs/3.x/usage/keyboards

Customize ReplyKeyboardMarkup with options like resizing, one-time use, placeholder text, and selective display.

```PHP
ReplyKeyboardMarkup::make(  
    resize_keyboard: true,  
    one_time_keyboard: true,  
    input_field_placeholder: 'Type something',
    selective: true,
);

```

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

### Set up Webhook Controller in Laravel

Source: https://nutgram.dev/docs/3.x/configuration/laravel

Create a controller to handle incoming Telegram webhook requests and run the Nutgram bot instance.

```php
class FrontController extends Controller
{
    /**
     * Handle the telegram webhook request.
     */
    public function __invoke(Nutgram $bot)
    {
        $bot->run();
    }
}
```

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

### Get a Fake Nutgram Instance

Source: https://nutgram.dev/docs/3.x/testing/introduction

Instantiate Nutgram as a `Fake` instance to mock Telegram API requests. This is useful for unit testing your application logic.

```php
use PHPUnit\Framework\TestCase;
use SergiX44\Nutgram\Nutgram;

class BotTest extends TestCase
{
    public function test_retrieve_mocked_instance(): void
    {
        $bot = Nutgram::fake();
          
        // ...
    }
}
```

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

### Handle CallbackQuery Data with Parameters

Source: https://nutgram.dev/docs/usage/handlers

Use `onCallbackQueryData` with parameters to capture dynamic data from callback queries. This example extracts numbers from 'number 1' or 'number 2'.

```php
use SergiX44\Nutgram\Nutgram;
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onCommand('start', function (Nutgram $bot) {
    $bot->sendMessage(
        text: 'Choose an option:',
        reply_markup: InlineKeyboardMarkup::make()->addRow(
            InlineKeyboardButton::make('One', callback_data: 'number 1'),
            InlineKeyboardButton::make('Two', callback_data: 'number 2'),
            InlineKeyboardButton::make('Cancel', callback_data: 'cancel'),
        )
    );
});
  
$bot->onCallbackQueryData('number {param}', function (Nutgram $bot, $param) {
    $bot->sendMessage($param); // 1 or 2
    $bot->answerCallbackQuery();
});
  
$bot->onCallbackQueryData('cancel', function (Nutgram $bot) {
    $bot->sendMessage('Canceled!');
    $bot->answerCallbackQuery();
});
  
$bot->run();

```

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

### Callback and Command Methods

Source: https://nutgram.dev/docs/3.x/usage/sending_requests

Methods for answering callback queries and managing bot commands.

```APIDOC
## answerCallbackQuery

### Description
Answers a callback query.

### Method
`answerCallbackQuery(?array $opt = [])`

### Return
`?bool`
```

```APIDOC
## setMyCommands

### Description
Sets the bot's commands.

### Method
`setMyCommands(array $commands = [])`

### Return
`?bool`
```

```APIDOC
## getMyCommands

### Description
Retrieves the bot's commands.

### Method
`getMyCommands()`

### Return
`?array`
```

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

### Registering Command Classes with Localized Descriptions

Source: https://nutgram.dev/docs/usage/handlers

Register a command class with localized descriptions. Use the $localizedDescriptions property to define descriptions for specific languages and $description for the default.

```php
// 1. create a command class like "StartCommand.php":  
class StartCommand extends Command  
{
    protected string $command = 'start';  

    protected ?string $description = 'The start command!'; // All other languages  

    protected array $localizedDescriptions = [
        'it' => 'Il comando start!', // Italian  
        'es' => 'El comando start!', // Spanish  
    ];  

    public function handle(Nutgram $bot): void  
    {
        $bot->sendMessage('Hello there!');  
    }
}
  
// 2. Register StartCommand inside Nutgram  
$bot->registerCommand(StartCommand::class);  
```

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

### Basic Bulk Messenger Usage (Async)

Source: https://nutgram.dev/docs/3.x/usage/bulk_messenger

Shows how to configure and initiate the Bulk Messenger for asynchronous message sending within a Telegram bot handler. The process runs in the background.

```php
use SergiX44\Nutgram\Nutgram;

$bot = new Nutgram($_ENV['TOKEN']);

$chats = [];

// inside handlers (polling)
$bot->onCommand('start', function (Nutgram $bot) use ($chats) {
    $bot->getBulkMessenger()
        ->setChats($chats)
        ->setText('Hello!')
        ->setOpt([/* optional parameters */])
        ->startAsync();
});
$bot->run();

```

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

### Tag Handlers and Retrieve Tags in Middleware

Source: https://nutgram.dev/docs/usage/middleware

This example demonstrates how to tag a handler with custom data ('foo' => 'bar') and retrieve that tag within a middleware using `currentResolvedHandler()->getTag()`.

```php
$bot = new Nutgram('TOKEN');  
  
$bot->middleware(function (Nutgram $bot, $next) {  
    $currentResolvedHandler = $bot->currentResolvedHandler();  

    $myTag = $currentResolvedHandler->getTag('foo');   
    // on '/start' command this will return 'bar' value otherwise null  
  
    $next($bot);
});  
  
$bot->onCommand('start', function (Nutgram $bot) {  
    $bot->sendMessage('Hello');  
})->tag('foo', 'bar');  
  
$bot->run();  


```

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

### Create and Handle Reply Keyboard

Source: https://nutgram.dev/docs/3.x/usage/keyboards

Use ReplyKeyboard to present users with predefined message options. Handle text messages to respond to user input from the reply keyboard.

```PHP
$bot->onCommand('start', function(Nutgram $bot){  
    $bot->sendMessage('Welcome!', [  
        'reply_markup' => ReplyKeyboardMarkup::make()->addRow(  
            KeyboardButton::make('Give me food!'),  
            KeyboardButton::make('Give me animal!'),  
        )
    ]);  
});  

$bot->onText('Give me food!', function (Nutgram $bot) {  
    $bot->sendMessage('Apple!');  
});  

$bot->onText('Give me animal!', function (Nutgram $bot) {  
    $bot->sendMessage('Dog!');  
});  

```

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

### Register Handlers with Different Definitions

Source: https://nutgram.dev/docs/3.x/usage/handlers

Nutgram accepts various handler definitions: invokable classes, class methods, and instance methods. This example shows how to register them using `onCommand`.

```php
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
// all of those are valid definitions:  
$bot->onCommand('start {param}', MyCommand::class); // with __invoke  
$bot->onCommand('start1 {param}', [MyCommand::class, 'handle']); // class-method  
$bot->onCommand('start2 {param}', [$instance, 'handle']); // instance-method  
  
$bot->run();  
```

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

### Download File via downloadFile Method

Source: https://nutgram.dev/docs/usage/sending_requests

Use the `downloadFile` method to download a file to a specified path. This requires obtaining the `File` object first.

```php
use SergiX44\Nutgram\Nutgram;  
use SergiX44\Nutgram\Telegram\Types\Media\File;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onSticker(function (Nutgram $bot) {  
    // get the file_id  
    $fileId = $bot->message()->sticker->file_id;  
      
    // get the File  
    $file = $bot->getFile($fileId);  
      
    // download the file  
    $bot->downloadFile($file, 'file.ext');  
});  


```

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

### Hear Callback Query Data

Source: https://nutgram.dev/docs/3.x/testing/hearing

Simulates an incoming `CallbackQuery` with specific data. Use this to test handlers that respond to button presses in inline keyboards.

```php
->hearCallbackQueryData('baz');  

```

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

### Registering a Text Handler

Source: https://nutgram.dev/docs/3.x/testing/asserting

Sets up a handler for specific text input. This is a foundational step for testing bot responses to user messages.

```php
$bot->onText('foo', function (Nutgram $bot) {
    $bot->sendMessage('bar');
});

```

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

### Stop Middleware Chain Execution

Source: https://nutgram.dev/docs/3.x/usage/middleware

This example shows how to stop the middleware chain execution by not calling the `$next($bot)` method within a middleware. This prevents subsequent middleware and the main handler from being executed.

```php
use SergiX44\Nutgram\Nutgram;  
  
$bot = new Nutgram($_ENV['TOKEN']);  
  
$bot->onMessage(function (Nutgram $bot) {  
    $bot->sendMessage('I will be never called :(');  
})->middleware(function (Nutgram $bot, $next) {  
  
    $bot->sendMessage('Stop!');  
    //$next($bot);  
});  
  
$bot->run();  

```
Tokens:
Raw