Manufacture Part Telegram Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require baks-dev/manufacture-part-telegram
   php bin/console baks:assets:install
   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

2. First Use Case

   • Register a Telegram bot with BotFather and obtain an API token.
   • Configure the bot token in .env:

     TELEGRAM_BOT_TOKEN=your_bot_token_here
     

   • Start the bot and interact via Telegram to trigger production workflows (e.g., /start, /create_part).

3. Where to Look First

   • Config: config/manufacture-part-telegram.php (if auto-generated by baks:assets:install).
   • Commands: app/Console/Commands/ for custom workflows.
   • Controllers/Handlers: Look for TelegramUpdateHandler or similar in app/Http/Controllers/ or src/.
   • Models: Check app/Entities/ or src/Entity/ for Part, ProductionBatch, etc.

Implementation Patterns

Core Workflows

1. Telegram Bot Integration

   • Use the package’s built-in Telegram update handler (likely extends Symfony\Component\HttpKernel\EventListener\TerminateEventListener or similar).
   • Example workflow:

     // In a controller or command
     $telegram = app(\BaksDev\ManufacturePartTelegram\Telegram\TelegramClient::class);
     $response = $telegram->sendMessage(
         chatId: $userId,
         text: "Production batch created: #{$batch->id}"
     );
     

2. Production Batch Creation

   • Trigger via Telegram commands (e.g., /create_part).
   • Validate input (e.g., product ID, quantity) and persist to DB:

     $batch = app(\BaksDev\ManufacturePartTelegram\Entity\ProductionBatch::class);
     $batch->productId = $productId;
     $batch->quantity = $quantity;
     $batch->userId = $userId; // Telegram user ID
     $entityManager->persist($batch);
     $entityManager->flush();
     

3. State Management

   • Use the package’s state machine (if included) to track batch status (e.g., pending, in_production, completed).
   • Example:

     $batch->changeStateTo(\BaksDev\ManufacturePartTelegram\Entity\ProductionBatch::STATE_IN_PRODUCTION);
     

4. Webhook Setup

   • Configure a route to handle Telegram updates (likely in routes/web.php or routes/telegram.php):

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

   • Verify the webhook URL with Telegram’s API:

     $telegram->setWebhook(['url' => url('/telegram/webhook')]);
     

5. Event-Driven Extensions

   • Listen for production events (e.g., BatchCreated, BatchCompleted) to trigger notifications or side effects:

     // In EventSubscriber
     public function onBatchCreated(BatchCreatedEvent $event): void {
         $this->telegram->sendMessage(
             chatId: $event->getUserId(),
             text: "Batch {$event->getBatch()->id} is ready!"
         );
     }
     

Gotchas and Tips

Pitfalls

1. Database Schema Mismatches

   • Always run doctrine:migrations:diff and migrate after updating the package or manually modifying migrations.
   • Check for reserved column names (e.g., state) if extending the ProductionBatch entity.

2. Telegram API Rate Limits

   • Avoid spamming Telegram’s API. Batch messages or use queues:

     dispatch(new SendTelegramMessage($userId, $message))->onQueue('telegram');
     

3. User ID Handling

   • Telegram user IDs are not Laravel user IDs. Store them separately (e.g., telegram_user_id in a pivot table or user extension).
   • Example:

     $user->telegramUserId = $telegramUpdate->getMessage()->getFrom()->getId();
     

4. Local Development Quirks

   • Use ngrok to expose your local server for Telegram webhook testing:

     ngrok http 8000
     

   • Update the webhook URL in Telegram’s API with your ngrok.io endpoint.

5. Translation Issues

   • The package may use Russian strings (from the README). Override translations in resources/lang/ or extend the language provider.

Debugging Tips

1. Log Telegram Updates Add a middleware to log raw updates for debugging:

   // app/Http/Middleware/LogTelegramUpdates.php
   public function handle($request, Closure $next) {
       if ($request->is('telegram/webhook')) {
           \Log::debug('Telegram Update:', $request->all());
       }
       return $next($request);
   }
   

2. Test with BotFather Use Telegram’s Test Bot to simulate updates locally.

3. Check for Deprecated Methods The package is new (2026). Verify if methods like sendMessage() have changed in newer Telegram Bot API versions.

Extension Points

1. Custom Commands Extend the bot’s command handler to add new Telegram commands:

   // app/Telegram/Commands/CreatePartCommand.php
   public function handle(TelegramContext $context) {
       $args = $context->getArgs();
       // Parse $args[0] as product ID, $args[1] as quantity
       // Create batch and reply
   }
   

2. Hook into Production Workflows Subscribe to events or override services:

   // config/services.php
   'manufacture_part_telegram.production_workflow' => [
       'class' => \App\Services\CustomProductionWorkflow::class,
   ];
   

3. Add Notifications Extend the ProductionBatch entity to include notification logic:

   // app/Entities/ProductionBatch.php
   public function markAsCompleted(): void {
       $this->state = self::STATE_COMPLETED;
       // Trigger email/SMS/Telegram notifications
       event(new BatchCompleted($this));
   }
   

4. Localization Override the package’s language files in resources/lang/{locale}/manufacture-part-telegram.php.

5. Testing Use the --group=manufacture-part-telegram flag to run isolated tests:

   php bin/phpunit --group=manufacture-part-telegram
   

   Mock Telegram updates in tests:

   $update = new \BaksDev\ManufacturePartTelegram\Telegram\Update\MessageUpdate(
       new \BaksDev\ManufacturePartTelegram\Telegram\User(123),
       new \BaksDev\ManufacturePartTelegram\Telegram\Message('test', '/create_part')
   );
   $handler = new TelegramUpdateHandler();
   $handler->handle($update);