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.

Features
Requirements
Installation
Configuration
- Environment Variables
- Restrict to Production Only
Usage
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

Open @BotFather in Telegram
Send /newbot and follow the prompts
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)

Enable Topics in your group settings
Create a topic and send a message
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

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Commit your changes: git commit -m 'Add my feature'
Push: git push origin feature/my-feature
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

uzhlaravel / telegramlogs

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

Table of Contents

Features

Requirements

Installation

Configuration

Environment Variables

Full Reference

Restrict to Production Only

Usage

Log Channel Integration

Direct Messaging

Activity Log

HasTelegramActivity Trait

TelegramActivity Facade

Artisan Commands

Log Levels

Getting Telegram Credentials

1. Create a Bot

2. Get Your Chat ID

3. Forum Topics (optional)

Security

Contributing

License