Laravel
Instead of installing the base nutgram/nutgram
base package, you have to install the package version:
composer require nutgram/laravel
# remove the base package if you have installed it:
# composer remove nutgram/nutgram
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,
// 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'),
The second config
array, is basically any configuration option, already
explained here.
However, please remember to convert the keys to snake_case.
Additionally, any keys starting with polling
should be divided into a sub-array.
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
- Register the bot commands, see automatically-register-bot-commands
nutgram:run
- Start the bot in long polling mode. Useful in development mode.
nutgram:make:command {name}
- Create a new command class
nutgram:make:conversation {name} {--menu}
- Create a new conversation class
nutgram:make:handler {name}
- Create a new handler class
nutgram:make:middleware {name}
- Create a new middleware class
nutgram:ide:generate
- Generate a file helping IDEs to autocomplete mixins methods.
nutgram:logout {--d|drop-pending-updates}
- Log out from the cloud Bot API server
Cache
The cache adapter gets automatically configured by Laravel; make sure to configure the appropriate driver inside your
config/cache.php
and .env
file.
Logging
The framework provides a channel to log any data you want to a Telegram chat.
To use it, you need to create the telegram
channel inside the config/logging.php
file:
'telegram' => [
'driver' => 'custom',
'via' => \SergiX44\Nutgram\Laravel\Log\NutgramLogger::class,
'level' => 'debug',
'chat_id' => env('NUTGRAM_LOG_CHAT_ID'), // any chat_id where bot can write messages
]
Now, you can log any data to the chat using the telegram
channel:
Log::channel('telegram')->info('Hello world!', ['xyz' => 123]);
Output:
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.
Mixins
Nutgram provides a few mixins to help you work best with Laravel.
Just enable the mixins
option in the config/nutgram.php
file, and you will be able to use them in your handlers.
Nutgram
class:downloadFileToDisk(File $file, string $path, string $disk = null, array $clientOpt = []): bool
Save a File to Laravel disk.
File
class:saveToDisk(string $path, string $disk = null, array $clientOpt = []): bool
Save the File to Laravel disk.
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();
}
}
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');
Facade support
Nutgram provides a Facade to access the bot instance anywhere in your application.
You can use it like this:
use SergiX44\Nutgram\Facades\Telegram;
Telegram::sendMessage('Hello, world!');
You can use the Facade in your telegram.php
routes file too:
use SergiX44\Nutgram\Facades\Telegram;
Telegram::onCommand('start', function () {
return Telegram::sendMessage('Hello, world!');
});
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);
// ...
}
}