Orders Telegram Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/orders-telegram
   php artisan vendor:publish --provider="BaksDev\OrdersTelegram\OrdersTelegramServiceProvider" --tag="config"
   php artisan migrate
   

2. Configure Telegram Bot Edit .env:

   TELEGRAM_BOT_TOKEN=your_bot_token_here
   TELEGRAM_CHAT_ID=your_chat_id
   

3. First Use Case: Sending an Order Notification

   use BaksDev\OrdersTelegram\Facades\OrdersTelegram;
   
   // Trigger a notification for a new order
   OrdersTelegram::sendOrderNotification($orderId, [
       'customer_name' => 'John Doe',
       'items' => [
           ['name' => 'Product A', 'quantity' => 2],
       ],
       'total' => 99.99,
   ]);
   

Key Files to Review

• config/orders-telegram.php (Configuration)
• app/Providers/OrdersTelegramServiceProvider.php (Service binding)
• src/Facades/OrdersTelegram.php (Facade usage)
• src/Services/TelegramNotifier.php (Core logic)

Implementation Patterns

Workflow: Order Processing Pipeline

1. Order Created/Updated Event Listen to order.created or order.updated events and dispatch notifications:

   use BaksDev\OrdersTelegram\Events\OrderNotificationSent;
   
   public function handle(OrderCreated $event)
   {
       OrdersTelegram::sendOrderNotification($event->order->id, $this->formatOrderData($event->order));
       event(new OrderNotificationSent($event->order));
   }
   

2. Customizing Notifications Extend the default template via a service provider:

   public function boot()
   {
       OrdersTelegram::extend(function ($notifier) {
           $notifier->setTemplatePath(resource_path('views/orders/telegram-template.blade.php'));
       });
   }
   

3. Batch Processing Use the sendBatchNotifications method for bulk orders:

   $orderIds = Order::where('status', 'pending')->pluck('id');
   OrdersTelegram::sendBatchNotifications($orderIds, $this->formatBatchData());
   

Integration Tips

• Laravel Queues: Wrap notifications in a job for async processing:

  SendOrderTelegramNotification::dispatch($orderId, $data)->onQueue('telegram');
  

• Webhooks: Use the webhook method to handle Telegram updates (e.g., for order status changes):

  Route::post('/telegram/webhook', [TelegramWebhookController::class, 'handle']);
  

• Localization: Override language strings in config/orders-telegram.php:

  'messages' => [
      'order_received' => 'Новый заказ от {customer}',
  ],
  

Gotchas and Tips

Pitfalls

1. Rate Limits Telegram imposes message limits. Handle TelegramApiException gracefully:

   try {
       OrdersTelegram::sendOrderNotification($orderId, $data);
   } catch (TelegramApiException $e) {
       Log::warning("Telegram rate limit hit: {$e->getMessage()}");
       // Retry logic or queue the job
   }
   

2. Chat ID Validation Ensure TELEGRAM_CHAT_ID is set correctly. Test with:

   php artisan telegram:test
   

3. Migration Conflicts If using Doctrine migrations, run:

   php artisan doctrine:migrations:diff --env=testing
   

   to avoid schema conflicts in CI.

Debugging

• Enable Logging Set LOG_CHANNEL=telegram in .env to log all Telegram interactions.
• Dry Run Mode Use OrdersTelegram::setDryRun(true) to test without sending messages.

Extension Points

1. Custom Notifiers Implement BaksDev\OrdersTelegram\Contracts\NotifierInterface:

   class SlackNotifier implements NotifierInterface {
       public function send(array $data): void {
           // Custom Slack logic
       }
   }
   

   Register via service provider:

   OrdersTelegram::extendNotifier('slack', function () {
       return new SlackNotifier();
   });
   

2. Webhook Middleware Add middleware to validate Telegram updates:

   public function handle($request, Closure $next) {
       if (!$request->hasValidTelegramSignature()) {
           abort(403);
       }
       return $next($request);
   }
   

3. Database Schema Extend the orders_telegram_notifications table via a migration:

   Schema::table('orders_telegram_notifications', function (Blueprint $table) {
       $table->string('custom_field')->nullable();
   });