Download the PHP package marekmiklusek/telegram-logger without Composer

Sends Laravel log messages and exceptions to Telegram for real-time monitoring, with flood protection and redaction of sensitive context.

Features

• Real-time logging to Telegram
• Supports all log levels (debug, info, warning, error, etc.)
• Automatic exception handling, capturing the file, line and message
• Configurable log level filtering
• Silent notifications, to avoid sound and vibration in Telegram
• Flood protection and deduplication of repeated messages
• Redaction of sensitive context before anything leaves the app
• Fully tested: 100% code coverage and 100% type coverage

Requirements

• PHP 8.4+
• Laravel 13.0+
• allow_url_fopen enabled in php.ini (the default)

Installation

Require the package via Composer:

Configuration

Publish the package configuration:

This will create a config file at config/telegram-logger.php.

.env Configuration

Add your Telegram Bot API token and Chat ID to your .env file:

All other options are configurable via .env as well:

Config File (config/telegram-logger.php)

Usage

Basic Logging

Use Laravel's Log facade as usual, and errors will be sent to Telegram automatically:

Logging with Context

You can pass additional context to logs:

Logging Exceptions

Exceptions are automatically detected and logged:

How It Works

The package listens to Laravel's logging events and sends structured messages to Telegram.

Example Telegram Log Output

Example Telegram Log Output (Exception)

Advanced Configuration

1️⃣ Logger Enablement

You can enable or disable the logger in config/telegram-logger.php:

✅ If true, logs will be sent to Telegram as configured
✅ If false, the logger will be completely disabled (no logs sent)

2️⃣ Log Level Filtering

You can define the minimum log level in config/telegram-logger.php:

• debug: Logs everything
• info: Logs info, notice, warning, error, critical, alert, emergency
• error: Logs error, critical, alert, emergency
• critical: Logs only critical, alert, emergency

3️⃣ Silent Notifications

Enable silent notifications (no sound/vibration) in config/telegram-logger.php

✅ If true, messages will be sent silently.
✅ If false, Telegram will send notifications normally.

4️⃣ Failure Reporting

By default a failed delivery is swallowed, because a logger must never break the application:

Set TELEGRAM_LOG_THROW_ON_FAILURE=true locally to surface the actual Telegram API error (invalid token, chat not found, rate limit) instead of silence.

If Telegram rejects the message formatting (HTTP 400), the package automatically retries once as plain text, so the log is delivered even when formatting fails.

5️⃣ Flood Protection

An error storm must not turn into hundreds of Telegram requests, so two limits apply:

• dedupe_seconds sends an identical message only once per window
• max_per_minute caps how many messages leave the application per minute

Set either to 0 to disable it. Both require a working cache; when no cache is available they are skipped and logs are delivered as usual.

6️⃣ Redacting Sensitive Data

Context is sent to a third party, so known sensitive keys are replaced with [REDACTED]:

Keys are matched case-insensitively as a substring, so password also covers password_confirmation. Nested arrays are redacted too. Configure the list via redact_keys, or set it to [] to disable redaction.

Troubleshooting

❓ Logs not appearing in Telegram?

1. Set TELEGRAM_LOG_THROW_ON_FAILURE=true, so the real API error is thrown.

2. Check that your .env values are correctly set:

3. Ensure your bot has permission to send messages to your chat.
4. Verify TELEGRAM_LOG_LEVEL is not more severe than the level you are logging.
5. Confirm allow_url_fopen is enabled. Without it the API cannot be reached and the package throws Telegram API is unreachable.

❓ Behind a proxy?

Point TELEGRAM_LOG_API_URL at your own Bot API endpoint.

❓ Getting "Chat not found" error?

• Make sure you have sent a message to your bot first.
• Use this tool to get your Chat ID.

Testing

This runs the full quality chain: Pint, Rector, PHPStan (level max), 100% type coverage and the test suite with 100% code coverage.

Individual steps:

To apply automatic fixes:

Changelog

See CHANGELOG.md for release notes and upgrade instructions.

License

This package is open-source and licensed under the MIT License.