Skip to main content
Version: 2.x

Laravel Integration

If you are using the Laravel framework, much of the setup is handled automatically for you. First, you should install the package via composer as usual (see the installation page)

In you .env file, you should only define the TELEGRAM_TOKEN var, that's it!

TELEGRAM_TOKEN="api-telegram-token"

The framework instance, is available anywhere via the DI container, for example:

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use SergiX44\Nutgram\Nutgram;

class TelegramController extends Controller
{
    /**
     * Handle the request.
     */
    public function handle(Nutgram $bot)
    {
        //
    }
}

Configuration​

To expose the undelying configuration, you need to publish the configuration file:

php artisan vendor:publish --provider="SergiX44\Nutgram\NutgramServiceProvider" --tag="nutgram"

In the config/nutgram.php file, you will find something like that:

    // 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,

The second config array, is basically any configuration option, already explained here.

The third routes, set if the service provider should load the handlers form the folder routes/telegram.php, by default is true.

Commands​

The framework automatically register some useful commands in your Laravel application:

  • nutgram:list
    • List all registered handlers
  • nutgram:hook:info
    • Get current webhook status
  • nutgram:hook:remove {--d|drop-pending-updates}
    • Remove the bot webhook
  • nutgram:hook:set {url}
    • Set the bot webhook
  • nutgram:register-commands
  • nutgram:run
    • Start the bot in long polling mode. Useful in development mode.

Handlers definition​

The routes/telegram.php should be something like this:

<?php
/** @var SergiX44\Nutgram\Nutgram $bot */

use SergiX44\Nutgram\Nutgram;

/*
|--------------------------------------------------------------------------
| Nutgram Handlers
|--------------------------------------------------------------------------
|
| Here is where you can register telegram handlers for Nutgram. These
| handlers are loaded by the NutgramServiceProvider. Enjoy!
|
*/

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

This file is automatically loaded by the framework, so here is where you should define middleware, handlers and conversations.

Webhook updates​

For production mode, the webhook mode is recommended. Run the bot in that way is really simple, you should just create a new controller php artisan make:controller FrontController, and call the run method on the bot instance:

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

When calling the run() method on the bot instance, it automatically recognize if use the Polling method to retrieve updates, or Webhook, based on whether the current instance is running in a cli process, or is serving a web request.

and remember to register it on you http routes:

// routes/api.php

Route::post('/webhook', 'FrontController');

Testing​

Inside unit tests, you can automatically retrieve the fake instance with all your handlers and middleware loaded, simply by resolving it via DI:

namespace Tests\Feature;

use SergiX44\Nutgram\Nutgram;
use Tests\TestCase;

class ExampleTest extends TestCase
{
    /**
     * @return void
     */
    public function test_bot()
    {
        $bot = app(Nutgram::class);
        
        // ...
    }
}