LaraGram

https://github.com/laraxgram/laragram
Admin
LaraGram is a comprehensive framework designed for building Telegram bots, offering a rich set of...
Tokens:5,722
Snippets:19
Trust Score:7.4
Update:11 months ago
Show doc for...
Tokens:
Raw
### LaraGram Development and Deployment Commands

Source: https://context7.com/laraxgram/laragram/llms.txt

This section provides essential Bash commands for managing a LaraGram project. It covers installation using Composer, generating application keys, configuring the bot token, running database migrations, starting the development server with hot-reload, and various utility commands for clearing caches, managing migrations, and performing production deployments.

```bash
# Terminal commands for development and deployment

# Installation
composer create-project laraxgram/laragram my-bot
cd my-bot
cp .env.example .env

# Generate application key
php laragram key:generate

# Configure bot token in .env
# BOT_TOKEN=your_telegram_bot_token

# Run database migrations
php laragram migrate

# Start development server with hot reload
composer dev
# This runs: serve + queue:listen + watchdog concurrently

# Or run services individually:
php laragram serve                    # Start bot polling
php laragram queue:listen            # Process background jobs
php laragram watchdog                # Watch for file changes

# Clear caches
php laragram config:clear            # Clear configuration cache
php laragram cache:clear             # Clear application cache
php laragram clear-compiled          # Clear compiled files

# Database operations
php laragram migrate                 # Run migrations
php laragram migrate:rollback        # Rollback last migration
php laragram migrate:fresh           # Drop all tables and re-run migrations
php laragram migrate:status          # Show migration status

# Custom commands
php laragram inspire                 # Display inspiring quote
php laragram user:create "John" 123  # Custom user creation

# Production deployment
php laragram config:cache            # Cache configuration
php laragram optimize                # Optimize application
php laragram queue:work --daemon     # Run queue worker as daemon

# Set webhook for production
php laragram bot:webhook:set https://yourdomain.com/webhook
php laragram bot:webhook:info        # Check webhook status

```

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

### Install LaraGram Framework using Composer

Source: https://github.com/laraxgram/laragram/blob/3.x.x/README.md

This command installs the LaraGram framework into a new project directory named 'my-bot' using Composer. It is the standard method for setting up a new LaraGram project.

```bash
composer create-project laraxgram/laragram my-bot
```

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

### Listen for Bot Commands in PHP

Source: https://github.com/laraxgram/laragram/blob/3.x.x/README.md

This snippet demonstrates how to set up a listener for the 'hello' command in a Telegram bot using LaraGram. It utilizes the Bot facade and the Request object to send a reply. Ensure LaraGram is installed via Composer.

```php
# listens/bot.php

use LaraGram\Request\Request;
use LaraGram\Support\Facades\Bot;

Bot::onText('hello', function (Request $request) {
    $request->sendMessage(chat()->id, 'hi');
});
```

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

### Environment Configuration (.env) for Laraxgram

Source: https://context7.com/laraxgram/laragram/llms.txt

Configure application settings, database connections, and bot credentials through environment variables. This section shows an example of a .env file used for configuration. Specific variables like API keys, endpoints, and cache stores are defined here.

```bash
# File: .env


```

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

### Create Custom CLI Commands with LaraGram

Source: https://context7.com/laraxgram/laragram/llms.txt

Defines custom Artisan-like console commands for bot management and administrative tasks. Uses the Commander facade for command registration and argument/option handling. Examples include displaying quotes, creating users, and clearing cache.

```php
<?php
// File: listens/console.php

use LaraGram\Foundation\Inspiring;
use LaraGram\Support\Facades\Commander;

// Simple command
Commander::command('inspire', function () {
    $this->comment(Inspiring::quote());
})->purpose('Display an inspiring quote');

// Command with arguments
Commander::command('user:create {name} {chatId}', function ($name, $chatId) {
    $user = User::create([
        'first_name' => $name,
        'chat_id' => $chatId,
        'user_id' => $chatId,
        'status' => 'active'
    ]);

    $this->info("User {$name} created with ID: {$user->id}");
})->purpose('Create a new user');

// Command with options
Commander::command('cache:clear {--type=all}', function ($type) {
    if ($type === 'config') {
        cache()->forget('config.*');
        $this->info('Config cache cleared');
    } else {
        cache()->flush();
        $this->info('All cache cleared');
    }
})->purpose('Clear application cache');

// Execute from terminal:
// php laragram inspire
// php laragram user:create "John Doe" 123456789
// php laragram cache:clear --type=config

```

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

### Database Migrations with LaraGram

Source: https://context7.com/laraxgram/laragram/llms.txt

Provides tools for managing database schema with version control. Includes examples for creating user and message tables using LaraGram's Migration and Schema components. Supports standard migration operations like creating, rolling back, and refreshing the database.

```php
<?php
// File: database/migrations/0001_01_01_000000_create_users_table.php

use LaraGram\Database\Migrations\Migration;
use LaraGram\Database\Schema\Blueprint;
use LaraGram\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('users', function (Blueprint $table) {
            $table->id();
            $table->string('first_name');
            $table->string('last_name')->nullable();
            $table->bigInteger('user_id')->unique(); // Telegram user ID
            $table->bigInteger('chat_id');
            $table->string('status')->nullable();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('users');
    }
};

// Create custom migration: database/migrations/2024_01_15_create_messages_table.php
return new class extends Migration
{
    public function up(): void
    {
        Schema::create('messages', function (Blueprint $table) {
            $table->id();
            $table->bigInteger('user_id');
            $table->bigInteger('chat_id');
            $table->text('content');
            $table->string('type')->default('text'); // text, photo, document, etc.
            $table->json('metadata')->nullable();
            $table->timestamps();

            $table->foreign('user_id')
                  ->references('user_id')
                  ->on('users')
                  ->onDelete('cascade');

            $table->index(['user_id', 'created_at']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('messages');
    }
};

// Run migrations from terminal:
// php laragram migrate
// php laragram migrate:rollback
// php laragram migrate:fresh

```

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

### User Model and Authentication with LaraGram

Source: https://context7.com/laraxgram/laragram/llms.txt

Implements an Eloquent User model for managing Telegram users and handles authentication using Telegram user IDs. Includes methods for checking admin status and examples of user registration and profile retrieval within bot handlers.

```php
<?php
// File: app/Models/User.php

namespace App\Models;

use LaraGram\Database\Eloquent\Factories\HasFactory;
use LaraGram\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasFactory;

    protected $fillable = [
        'first_name',
        'last_name',
        'chat_id',
        'user_id',
        'status',
    ];

    // Example usage in bot listener
    public function messages()
    {
        return $this->hasMany(Message::class, 'user_id', 'user_id');
    }

    public function isAdmin(): bool
    {
        return $this->status === 'admin';
    }
}

// Usage in bot handlers
Bot::onCommand('register', function (Request $request) {
    $chatData = chat();

    $user = User::firstOrCreate(
        ['user_id' => $chatData->user_id],
        [
            'first_name' => $chatData->first_name,
            'last_name' => $chatData->last_name ?? null,
            'chat_id' => $chatData->id,
            'status' => 'active'
        ]
    );

    $request->sendMessage(
        $chatData->id,
        "Welcome, {$user->first_name}! You are now registered."
    );
});

// Check authentication
Bot::onCommand('profile', function (Request $request) {
    $user = auth()->user();

    if (!$user) {
        $request->sendMessage(chat()->id, "Please register first");
        return;
    }

    $response = "Profile:\n";
    $response .= "Name: {$user->first_name} {$user->last_name}\n";
    $response .= "Status: {$user->status}\n";
    $response .= "Joined: {$user->created_at->diffForHumans()}";

    $request->sendMessage(chat()->id, $response);
});

```

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

### Service Provider for Dependency Injection in PHP

Source: https://context7.com/laraxgram/laragram/llms.txt

Register services, bindings, and bootstrap application components for dependency injection within the application. This example shows registering singleton and shared services like PaymentService and NotificationService, along with helper bindings and custom validation rules. Services can be accessed using the application instance.

```php
<?php
// File: app/Providers/AppServiceProvider.php

namespace App\Providers;

use LaraGram\Support\ServiceProvider;
use App\Services\PaymentService;
use App\Services\NotificationService;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Register singleton services
        $this->app->singleton(PaymentService::class, function ($app) {
            return new PaymentService(
                apiKey: env('PAYMENT_API_KEY'),
                endpoint: env('PAYMENT_ENDPOINT')
            );
        });

        // Register shared instances
        $this->app->bind(NotificationService::class, function ($app) {
            return new NotificationService(
                bot: bot(),
                adminChatId: env('ADMIN_CHAT_ID')
            );
        });

        // Register helper functions
        $this->app->bind('payment', function ($app) {
            return $app->make(PaymentService::class);
        });
    }

    public function boot(): void
    {
        // Bootstrap application services
        if ($this->app->environment('local')) {
            logger()->info('Running in local environment');
        }

        // Register custom validation rules
        validator()->extend('telegram_user_id', function ($attribute, $value) {
            return is_numeric($value) && $value > 0;
        });
    }
}

// Usage in bot handlers:
Bot::onCommand('pay', function (Request $request) {
    $payment = app(PaymentService::class);
    $result = $payment->createInvoice(amount: 10.00, currency: 'USD');

    $request->sendMessage(chat()->id, "Payment link: {$result['url']}");
});

```

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

### Configure LaraGram Bot Connections and API Settings (PHP)

Source: https://context7.com/laraxgram/laragram/llms.txt

This PHP configuration file defines bot connections, including tokens, webhook URLs, and allowed update types for single or multi-bot setups. It also specifies API server settings such as endpoint, directory, and authentication credentials. Environment variables are used for sensitive information.

```php
<?php
// File: config/bot.php

return [
    'default' => 'bot',

    'connections' => [
        'bot' => [
            'token' => env("BOT_TOKEN"), // Required
            'url' => env("BOT_URL"), // Webhook URL
            'username' => env("BOT_USERNAME", ''),
            'userid' => env("BOT_USERID", ''),
            'secret_token' => null,
            'allowed_updates' => ['*'] // or ['message', 'callback_query']
        ],

        // Multi-bot support
        'support_bot' => [
            'token' => env("SUPPORT_BOT_TOKEN"),
            'url' => env("SUPPORT_BOT_URL"),
            'username' => env("SUPPORT_BOT_USERNAME", ''),
            'userid' => env("SUPPORT_BOT_USERID", ''),
            'secret_token' => null,
            'allowed_updates' => ['message', 'callback_query']
        ],
    ],

    'api_server' => [
        'endpoint' => env("API_ENDPOINT", "https://api.telegram.org"),
        'dir' => env("API_DIR", storage_path('app/api-server')),
        'log_dir' => '',
        'ip' => '127.0.0.1',
        'port' => 8081,
        'stat' => ['ip' => '', 'port' => ''],
        'api_id' => env("API_ID", ''),
        'api_hash' => env("API_HASH", ''),
    ],
];

// Usage: Switch between bots
use LaraGram\Support\Facades\Bot;

Bot::connection('support_bot')->onCommand('start', function ($request) {
    $request->sendMessage(chat()->id, "Support Bot activated");
});

// Environment setup (.env file):
// BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
// BOT_URL=https://yourdomain.com/webhook
// BOT_USERNAME=your_bot_name
// BOT_USERID=1234567890

```

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

### Queue Jobs for Background Tasks in PHP

Source: https://context7.com/laraxgram/laragram/llms.txt

Process time-consuming operations like API calls or file processing asynchronously using background jobs. This example demonstrates sending newsletters to active users, including rate limiting and error logging. Jobs are dispatched from bot listeners and can be managed via terminal commands.

```php
<?php
// File: app/Jobs/SendNewsletterJob.php

namespace App\Jobs;

use LaraGram\Queue\Job;
use App\Models\User;

class SendNewsletterJob extends Job
{
    protected $newsletter;

    public function __construct($newsletter)
    {
        $this->newsletter = $newsletter;
    }

    public function handle()
    {
        $users = User::where('status', 'active')->get();

        foreach ($users as $user) {
            try {
                bot()->sendMessage($user->chat_id, $this->newsletter);
                usleep(100000); // Rate limiting: 10 messages/second
            } catch (\Exception $e) {
                logger()->error("Failed to send to user {$user->id}: {$e->getMessage()}");
            }
        }
    }
}

// Dispatch job from bot listener
Bot::onCommand('broadcast', function (Request $request) {
    $user = auth()->user();

    if (!$user || !$user->isAdmin()) {
        $request->sendMessage(chat()->id, "Unauthorized");
        return;
    }

    $message = $request->getText();
    $newsletter = str_replace('/broadcast ', '', $message);

    dispatch(new SendNewsletterJob($newsletter));

    $request->sendMessage(chat()->id, "Newsletter queued for delivery");
});

// Run queue worker from terminal:
// php laragram queue:listen
// php laragram queue:work --once

```

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

### Caching System for Bot Performance in PHP

Source: https://context7.com/laraxgram/laragram/llms.txt

Improve bot performance by storing and retrieving data efficiently using various cache drivers. Examples include caching API responses with a Time-To-Live (TTL), persisting user preferences indefinitely, and clearing the entire cache. Cache drivers are configurable via environment variables.

```php
<?php
// Cache usage examples in bot handlers

use LaraGram\Support\Facades\Cache;

Bot::onCommand('weather', function (Request $request) {
    $city = $request->getText();
    $cacheKey = "weather:{$city}";

    // Check cache first (TTL: 30 minutes)
    $weather = Cache::remember($cacheKey, 1800, function () use ($city) {
        // Expensive API call
        return fetchWeatherFromAPI($city);
    });

    $request->sendMessage(chat()->id, "Weather in {$city}: {$weather}");
});

// Store user preferences
Bot::onCommand('setlang', function (Request $request) {
    $userId = chat()->user_id;
    $lang = $request->getText(); // "en", "es", "fr", etc.

    Cache::forever("user:{$userId}:lang", $lang);
    $request->sendMessage(chat()->id, "Language set to {$lang}");
});

// Get user preferences
Bot::onCommand('start', function (Request $request) {
    $userId = chat()->user_id;
    $lang = Cache::get("user:{$userId}:lang", 'en');

    $greeting = [
        'en' => 'Hello!',
        'es' => '¡Hola!',
        'fr' => 'Bonjour!'
    ];

    $request->sendMessage(chat()->id, $greeting[$lang]);
});

// Cache invalidation
Bot::onCommand('clearcache', function (Request $request) {
    if (auth()->user()?->isAdmin()) {
        Cache::flush();
        $request->sendMessage(chat()->id, "Cache cleared");
    }
});

// Configure cache driver in .env:
// CACHE_STORE=database  // or redis, memcached, file, array

```

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

### Configure Webhook Handler in PHP

Source: https://context7.com/laraxgram/laragram/llms.txt

This PHP script configures a webhook endpoint to process incoming Telegram updates asynchronously. It escapes shell arguments for security and executes the bot handler in the background to prevent timeouts. It also includes Nginx configuration examples and instructions for setting the webhook via the Telegram API or LaraGram command.

```php
<?php
// File: public/index.php
// This file handles webhook requests from Telegram

$server = escapeshellarg(json_encode($_SERVER));
$inputs = escapeshellarg(file_get_contents('php://input'));

$vendorDir = is_dir($dir = realpath(__DIR__ . '/../vendor'))
    ? $dir
    : realpath(__DIR__ . '/vendor');

$serverPath = $vendorDir . '/laraxgram/core/src/Foundation/resources/server.php';
$output = '/dev/null';

// Execute bot handler asynchronously to prevent timeout
popen("php \"{$serverPath}\" {$inputs} {$server} >> {$output} 2>&1 &", "r");

// Nginx configuration for webhook:
/*
server {
    listen 443 ssl; 
    server_name yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    root /var/www/your-bot/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
*/

// Set webhook via Telegram API:
// curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
//   -d "url=https://yourdomain.com/webhook" \
//   -d "allowed_updates=[\"message\",\"callback_query\"]"

// Or use LaraGram command:
// php laragram bot:webhook:set https://yourdomain.com/webhook

```

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

### Initialize LaraGram Application with Listeners, Middleware, and Exceptions (PHP)

Source: https://context7.com/laraxgram/laragram/llms.txt

This PHP script initializes the LaraGram application by configuring base path, listeners for bot and console commands, middleware for request processing (logging and rate limiting), and custom exception handling for reporting and rendering errors. It utilizes the Application facade for configuration.

```php
<?php
// File: bootstrap/app.php

use LaraGram\Foundation\Application;
use LaraGram\Foundation\Configuration\Exceptions;
use LaraGram\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withListener(
        bot: __DIR__."/../listens/bot.php",
        commands: __DIR__."/../listens/console.php",
    )
    ->withMiddleware(function (Middleware $middleware): void {
        // Add custom middleware
        $middleware->append(function ($request, $next) {
            // Log all incoming requests
            logger()->info('Incoming request', [
                'update_id' => $request->getUpdateId(),
                'chat_id' => chat()->id ?? null,
            ]);

            return $next($request);
        });

        // Rate limiting middleware
        $middleware->append(function ($request, $next) {
            $userId = chat()->user_id ?? null;

            if ($userId && cache()->has("rate_limit:{$userId}")) {
                $request->sendMessage(
                    chat()->id,
                    "Too many requests. Please try again later."
                );
                return;
            }

            cache()->put("rate_limit:{$userId}", true, 60); // 1 minute
            return $next($request);
        });
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        // Custom exception handling
        $exceptions->report(function (\Throwable $e) {
            logger()->error('Bot error', [
                'message' => $e->getMessage(),
                'file' => $e->getFile(),
                'line' => $e->getLine(),
            ]);
        });

        $exceptions->render(function (\Throwable $e, $request) {
            $request->sendMessage(
                chat()->id,
                "Sorry, an error occurred. Please try again later."
            );
        });
    })->create();

```

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

### Handle Telegram Bot Commands with LaraGram

Source: https://context7.com/laraxgram/laragram/llms.txt

Register handlers for specific Telegram bot commands like /start, /help, and /stats. This listener system allows for routing bot interactions, including user authentication and sending messages with inline keyboards.

```php
<?php
// File: listens/bot.php

use LaraGram\Support\Facades\Bot;
use LaraGram\Request\Request;

// Handle /start command
Bot::onCommand('start', function (Request $request) {
    $chatId = chat()->id;
    $userName = chat()->first_name;

    $request->sendMessage($chatId, "Hello {$userName}! Welcome to LaraGram!");
});

// Handle /help command with inline keyboard
Bot::onCommand('help', function (Request $request) {
    $keyboard = [
        'inline_keyboard' => [
            [
                ['text' => 'Documentation', 'url' => 'https://laraxgram.github.io'],
                ['text' => 'Support', 'url' => 'https://telegram.me/LaraGramChat']
            ]
        ]
    ];

    $request->sendMessage(
        chat()->id,
        "Need help? Check our resources:",
        ['reply_markup' => json_encode($keyboard)]
    );
});

// Handle /stats command with user authentication
Bot::onCommand('stats', function (Request $request) {
    $user = auth()->user();

    if (!$user) {
        $request->sendMessage(chat()->id, "Please register first with /start");
        return;
    }

    $messageCount = $user->messages()->count();
    $request->sendMessage(
        chat()->id,
        "Your stats:\nTotal messages: {$messageCount}"
    );
});

```

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

### Handle Telegram Bot Text Messages with LaraGram

Source: https://context7.com/laraxgram/laragram/llms.txt

Register handlers for text messages in Telegram bots using LaraGram. This includes simple text matching, pattern matching with regular expressions, a catch-all for any text, and handling file uploads.

```php
<?php
// File: listens/bot.php

use LaraGram\Support\Facades\Bot;
use LaraGram\Request\Request;

// Simple text matching
Bot::onText('hello', function (Request $request) {
    $request->sendMessage(chat()->id, 'Hi there! How can I help you?');
});

// Pattern matching with regex
Bot::onText('/price\s+(\w+)/', function (Request $request, $matches) {
    $cryptocurrency = $matches[1];

    // Fetch price from API or database
    $price = fetchCryptoPrice($cryptocurrency);

    $request->sendMessage(
        chat()->id,
        "Current {$cryptocurrency} price: \"${$price}"
    );
});

// Handle any text message (catch-all)
Bot::onText('.*', function (Request $request) {
    $text = $request->getText();
    $userId = chat()->user_id;

    // Log the message
    logger()->info("Message from {$userId}: {$text}");

    // Echo response
    $request->sendMessage(
        chat()->id,
        "You said: {$text}"
    );
});

// Handle file uploads
Bot::onText('.*', function (Request $request) {
    if ($document = $request->getMessage()->document) {
        $fileId = $document->file_id;
        $fileName = $document->file_name;

        $request->sendMessage(
            chat()->id,
            "Received file: {$fileName}\nFile ID: {$fileId}"
        );
    }
});

```
Tokens:
Raw