Laravel Telegram Logger Laravel Package

Getting Started

The terowoc/laravel-telegram-logger package simplifies sending Laravel logs to a Telegram channel or group chat. To begin:

1. Installation: Requires Laravel 8+ and PHP 8.0+. Install via Composer:

   composer require terowoc/laravel-telegram-logger
   

2. Configuration: Publish the config file:

   php artisan vendor:publish --provider="Terowoc\TelegramLogger\TelegramLoggerServiceProvider"
   

   Update config/telegram-logger.php with your Bot Token (from @BotFather) and Chat ID (e.g., -1001234567890).
3. First Use Case: Logs will automatically route to Telegram for levels defined in the config (default: error and above). Test by triggering an error:

   \Log::error('Test Telegram log');
   

Implementation Patterns

Core Workflow

• Log Routing: The package extends Laravel’s log channels. Add it to config/logging.php under channels:

  'telegram' => [
      'driver' => 'telegram',
      'level' => env('TELEGRAM_LOG_LEVEL', 'error'),
  ],
  

  Then reference it in app.php:

  'logging' => [
      'default' => env('LOG_CHANNEL', 'telegram'),
  ],
  

• Customization: Override the default log format by extending Terowoc\TelegramLogger\Messages\TelegramLogMessage or bind a custom formatter in the service provider.
• Conditional Logging: Use the telegram channel conditionally in your code:

  if (app()->environment('production')) {
      \Log::channel('telegram')->error('Production-only error');
  }
  

Integration Tips

• Exception Handling: Catch exceptions and log them to Telegram:

  try {
      // Risky code
  } catch (\Exception $e) {
      \Log::error('Exception in ' . $e->getFile(), ['exception' => $e]);
  }
  

• Scheduling: Use Laravel’s scheduler to send periodic logs or health checks:

  \Schedule::command('telegram:health-check')->hourly();
  

• Environment-Specific: Disable Telegram logging in local environments by setting TELEGRAM_LOG_LEVEL to none in .env.

Gotchas and Tips

Pitfalls

• Chat ID Format: Ensure the Chat ID is correct (must start with -100 for groups/supergroups). Use @userinfobot to verify.
• Rate Limits: Telegram’s Bot API has rate limits. Avoid spamming logs during debugging.
• Sensitive Data: Never log raw user data (passwords, tokens) to Telegram. Use Log::error('Unauthorized access', ['ip' => $request->ip()]) instead of logging full request payloads.

Debugging

• Log Levels: Adjust TELEGRAM_LOG_LEVEL in .env to debug (e.g., debug for all logs, warning for warnings+).
• Bot Token: Double-check the token—invalid tokens will silently fail. Test with:

  curl "https://api.telegram.org/bot<TOKEN>/getMe"
  

• Queue Failures: If logs aren’t appearing, check if the queue worker is running (php artisan queue:work). The package uses Laravel’s queue system by default.

Extension Points

• Custom Messages: Override the default message format by publishing and modifying the view:

  php artisan vendor:publish --tag=telegram-logger-views
  

  Then edit resources/views/vendor/telegram-logger/message.blade.php.
• Webhook Fallback: For critical logs, implement a fallback to email or Slack by extending the TelegramLogger class.
• Log Annotations: Add metadata to logs for richer context:

  \Log::error('Failed payment', [
      'user_id' => auth()->id(),
      'amount' => $amount,
      'gateway' => 'stripe',
  ]);