README

A Laravel package that sends your application logs, exceptions, and model activity events directly to a Telegram channel or group — in real time.

Supports Laravel 10 → 13, PHP 8.2+, and includes production-only mode so notifications stay silent during local development.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
  • Environment Variables
  • Restrict to Production Only
• Usage
  • Log Channel Integration
  • Direct Messaging
  • Activity Log
    • HasTelegramActivity Trait
    • TelegramActivity Facade
• Artisan Commands
• Log Levels
• Getting Telegram Credentials
• Security
• Contributing
• License

Features

• Monolog integration — drop-in telegram log channel; works with LOG_CHANNEL=telegram or as a stacked channel
• Direct messaging — send arbitrary text to any chat from anywhere in your app
• Activity log — track Eloquent model created / updated / deleted events and push them to Telegram (inspired by spatie/laravel-activitylog)
• Production-only mode — restrict notifications to specific environments with a single env var
• Smart formatting — emoji-labelled MarkdownV2 messages with context, exception details, and stack traces
• Long message splitting — automatically splits messages that exceed Telegram's 4096-char limit
• Forum/topic support — route messages to specific threads in a Telegram group
• Interactive install — guided telegramlogs:install command

Requirements

Dependency	Version
PHP	^8.2
Laravel	^10.0 | ^11.0 | ^12.0 | ^13.0

Installation

composer require uzhlaravel/telegramlogs

Run the interactive setup wizard:

php artisan telegramlogs:install

The wizard will publish the config file, help you set environment variables, optionally enable activity log, and send a test message.

Or publish the config manually:

php artisan vendor:publish --tag="telegramlogs-config"

Configuration

Environment Variables

Add these to your .env file:

# Required
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

# Optional
TELEGRAM_LOG_LEVEL=critical          # minimum level to forward (default: critical)
TELEGRAM_TOPIC_ID=                   # forum thread / topic ID
TELEGRAM_TIMEOUT=10                  # Telegram API timeout in seconds

# Environment control — see next section
TELEGRAM_ENVIRONMENTS=production     # default: production only

# Activity log
TELEGRAM_ACTIVITY_LOG=false          # set true to enable model event tracking
TELEGRAM_ACTIVITY_LOG_LEVEL=info     # log level for activity notifications

Full Reference

Variable	Required	Default	Description
TELEGRAM_BOT_TOKEN	Yes	—	Bot API token from @BotFather
TELEGRAM_CHAT_ID	Yes	—	Target chat, channel, or group ID
TELEGRAM_TOPIC_ID	No	null	Forum topic (thread) ID
TELEGRAM_TOPIC_MESSAGE_ID	No	null	Forum thread message ID
TELEGRAM_LOG_LEVEL	No	critical	Minimum PSR-3 level to send
TELEGRAM_TIMEOUT	No	10	HTTP timeout in seconds
TELEGRAM_ENVIRONMENTS	No	production	Comma-separated env list, or *
TELEGRAM_ACTIVITY_LOG	No	false	Enable model activity tracking
TELEGRAM_ACTIVITY_LOG_LEVEL	No	info	Log level for activity messages

Restrict to Production Only

By default, notifications are only sent when APP_ENV=production. This prevents your local machine or CI from flooding your Telegram channel.

# Only production (default)
TELEGRAM_ENVIRONMENTS=production

# Production and staging
TELEGRAM_ENVIRONMENTS=production,staging

# Every environment — useful for local debugging
TELEGRAM_ENVIRONMENTS=*

The current environment and whether notifications are active are both shown in:

php artisan telegramlogs:test --config

Usage

Log Channel Integration

Set Telegram as your default channel:

LOG_CHANNEL=telegram

Or add it to a stack so critical logs go to both your file log and Telegram:

// config/logging.php
'channels' => [
    'stack' => [
        'driver'   => 'stack',
        'channels' => ['daily', 'telegram'],
    ],
],

Use it like any Laravel logger:

use Illuminate\Support\Facades\Log;

Log::error('Payment processing failure');

Log::critical('Database unreachable', [
    'connection' => 'mysql',
    'host'       => config('database.connections.mysql.host'),
]);

try {
    // ...
} catch (\Exception $e) {
    Log::error('Unexpected exception', ['exception' => $e]);
}

Messages arrive in Telegram formatted like this:

❌ ERROR — MyApp [production]

Payment processing failure

Context:
{
  "connection": "mysql"
}

🕐 2025-08-19 14:32:01 UTC

Direct Messaging

Send arbitrary messages to Telegram without going through the logger — useful for contact forms, webhooks, or manual alerts.

use Uzhlaravel\Telegramlogs\Facades\TelegramMessage;

// Simple text
TelegramMessage::message('Scheduled backup completed.');

// With Telegram API options
TelegramMessage::send('Deployment finished', [
    'parse_mode'               => 'HTML',
    'disable_web_page_preview' => true,
]);

// Send to a different chat
TelegramMessage::toChat('-100987654321', 'Alert for ops team');

// Test connectivity
TelegramMessage::test();

// Get bot information
TelegramMessage::getBotInfo();

Activity Log

Inspired by spatie/laravel-activitylog, the activity log tracks Eloquent model events and pushes a formatted notification to Telegram.

Enable it in .env:

TELEGRAM_ACTIVITY_LOG=true

HasTelegramActivity Trait

Add the trait to any Eloquent model to automatically track its lifecycle events:

use Uzhlaravel\Telegramlogs\Traits\HasTelegramActivity;

class Post extends Model
{
    use HasTelegramActivity;
}

On created, updated, or deleted, a message like the following is sent to Telegram:

🟢 Activity — MyApp [production]

Created Post

Subject: Post #42
Properties:
{
  "attributes": { "title": "Hello World", "status": "draft" }
}

🕐 2025-08-19 14:32:01 UTC

Customise per model:

use Uzhlaravel\Telegramlogs\Traits\HasTelegramActivity;

class Order extends Model
{
    use HasTelegramActivity;

    // Track only these events for this model
    protected array $telegramActivityEvents = ['created', 'deleted'];

    // Custom description
    public function getTelegramActivityDescription(string $event): string
    {
        return ucfirst($event) . ' order #' . $this->id . ' — ' . $this->status;
    }

    // Extra properties to include
    public function getTelegramActivityProperties(string $event): array
    {
        return ['total' => $this->total, 'customer' => $this->customer->name];
    }
}

Global event list is controlled in config/telegramlogs.php:

'activity_log' => [
    'events'             => ['created', 'updated', 'deleted'],
    'include_old_values' => true,   // previous values on update
    'include_new_values' => true,   // changed values on update
],

TelegramActivity Facade

For manual / one-off activity notifications, use the fluent facade:

use Uzhlaravel\Telegramlogs\Facades\TelegramActivity;

TelegramActivity::performedOn($post)
    ->causedBy(auth()->user())
    ->withProperty('plan', 'pro')
    ->event('published')
    ->dispatch('Post was published');

// Simpler form
TelegramActivity::log('Nightly cleanup job finished');

Artisan Commands

# Interactive setup
php artisan telegramlogs:install

# Send a test log message
php artisan telegramlogs:test

# Send with a custom message and level
php artisan telegramlogs:test --message="Health check OK" --level=warning

# Send a test activity notification
php artisan telegramlogs:test --activity

# Show current configuration (includes environment status)
php artisan telegramlogs:test --config

# List available log levels
php artisan telegramlogs:test --list

Log Levels

Level	Emoji	Use Case
emergency	🚨	System is unusable
alert	🔴	Immediate action required
critical	💥	Critical conditions
error	❌	Runtime errors
warning	⚠️	Potential issues
notice	📢	Significant normal events
info	ℹ️	General operational messages
debug	🐛	Detailed diagnostic information

Getting Telegram Credentials

1. Create a Bot

1. Open @BotFather in Telegram
2. Send /newbot and follow the prompts
3. Copy the token into TELEGRAM_BOT_TOKEN

2. Get Your Chat ID

• Channel — add the bot as an admin; the channel username (@mychannel) or numeric ID (-100xxxxxxxxx) works
• Group — add the bot to the group; send a message, then call https://api.telegram.org/bot<token>/getUpdates to find chat.id
• Private chat — start a chat with the bot, then use getUpdates

3. Forum Topics (optional)

1. Enable Topics in your group settings
2. Create a topic and send a message
3. From getUpdates, copy message_thread_id → TELEGRAM_TOPIC_ID

Security

• Store TELEGRAM_BOT_TOKEN only in .env — never commit it
• Restrict which commands the bot can receive (via BotFather → /mybots → Bot Settings → Group Privacy)
• Audit who has access to your Telegram channel regularly

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m 'Add my feature'
4. Push: git push origin feature/my-feature
5. Open a pull request

Development commands:

git clone https://github.com/Uzziahlukeka/telegrammonitor.git
cd telegrammonitor
composer install
composer test        # run test suite
composer analyse     # PHPStan static analysis
composer format      # Laravel Pint code style

License

This package is open-sourced software licensed under the MIT License.

💖 Made with love by Uzziah Lukeka