README

A Laravel package for sending comprehensive error notifications to Telegram channels with detailed context, stack traces, and environment information.

Features

🚨 Automatic Error Notifications - Captures all exceptions and sends them to Telegram
📝 Rich Error Context - Includes file, line, URL, user ID, environment, and stack trace
⚙️ Configurable - Control which environments send notifications
🔒 Safe - Won't break your app if Telegram is unreachable
🎯 Queue Support - Async notification processing to avoid blocking requests
🧪 Testable - Includes test notification for verifying setup
🎨 Markdown Formatting - Clean, readable error messages in Telegram

Requirements

PHP 8.2 or higher
Laravel 11.x or 12.x
A Telegram Bot Token (get one from @BotFather)
A Telegram Channel/Group/Chat ID

Installation

Install the package via Composer:

composer require technobase/alert

The service provider will be automatically registered via Laravel's package discovery.

Configuration

1. Publish Configuration File

php artisan vendor:publish --tag=alert-config

This creates config/alert.php in your application.

2. Set Environment Variables

Add these to your .env file:

# Telegram Bot Token (from @BotFather)
TELEGRAM_BOT_TOKEN=your-bot-token-here

# Telegram Chat ID (channel, group, or private chat)
TELEGRAM_CHAT_ID=your-chat-id-here

# Optional: Customize settings
ALERT_ENABLED=true
ALERT_NOTIFICATION_TITLE="🚨 Application Error"
ALERT_TRACE_LINES=10
ALERT_QUEUE=true

3. Configure Telegram Bot

Create a bot by messaging @BotFather on Telegram
Send /newbot and follow the prompts
Copy the bot token to your .env file
Create a Telegram channel for errors
Add your bot as an administrator to the channel
Get the channel ID (use @userinfobot or check Telegram API)
Add the chat ID to your .env file

Usage

Automatic Error Notifications

Once configured, Alert automatically catches all exceptions in production and staging environments and sends them to your Telegram channel.

No additional code needed! Just let your application run.

Testing the Integration

Send a test notification to verify your setup:

use Illuminate\Support\Facades\Notification;
use Technobase\Alert\Notifications\TestTelegramNotification;

Notification::route('telegram', config('alert.chat_id'))
    ->notify(new TestTelegramNotification('Testing Alert integration'));

Or create a test route:

Route::get('/test-alert', function() {
    \Notification::route('telegram', config('alert.chat_id'))
        ->notify(new \Technobase\Alert\Notifications\TestTelegramNotification());
    
    return 'Test notification sent!';
});

Manual Error Notifications

You can manually send error notifications:

use Illuminate\Support\Facades\Notification;
use Technobase\Alert\Notifications\TelegramErrorNotification;

try {
    // Your code that might fail
    riskyOperation();
} catch (\Exception $e) {
    Notification::route('telegram', config('alert.chat_id'))
        ->notify(new TelegramErrorNotification(
            title: 'Custom Error Title',
            message: $e->getMessage(),
            context: [
                'file' => $e->getFile(),
                'line' => $e->getLine(),
                'custom_data' => 'additional context',
            ]
        ));
    
    throw $e; // Re-throw if needed
}

Disabling for Specific Environments

Edit config/alert.php:

'enabled_environments' => [
    'production',
    'staging',
    // 'local' - not included, won't send notifications locally
],

Or disable entirely:

ALERT_ENABLED=false

Configuration Options

Option	Environment Variable	Default	Description
`enabled`	`ALERT_ENABLED`	`true`	Enable/disable package
`bot_token`	`TELEGRAM_BOT_TOKEN`	`null`	Telegram bot API token
`chat_id`	`TELEGRAM_CHAT_ID`	`null`	Telegram chat/channel ID
`enabled_environments`	-	`['production', 'staging']`	Environments to send notifications
`notification_title`	`ALERT_NOTIFICATION_TITLE`	`🚨 Application Error`	Title of error notifications
`trace_lines`	`ALERT_TRACE_LINES`	`10`	Max stack trace lines
`queue`	`ALERT_QUEUE`	`true`	Queue notifications
`queue_connection`	`ALERT_QUEUE_CONNECTION`	`null`	Queue connection to use
`log_notification_errors`	`ALERT_LOG_ERRORS`	`false`	Log notification failures
`include_request_data`	`ALERT_INCLUDE_REQUEST`	`true`	Include URL & user ID
`include_environment`	`ALERT_INCLUDE_ENV`	`true`	Include environment name

Example Telegram Notification

🚨 **Application Error**

**Message**: Call to undefined method User::nonExistent()

**File**: `/var/www/app/Services/UserService.php:42`
**URL**: `https://api.example.com/users/5`
**User**: `ID: 123`
**Environment**: `production`

**Trace**:

#0 UserController.php(23): UserService->process() #1 Router.php(822): UserController->store() #2 Pipeline.php(180): Router->dispatch() ...

Troubleshooting

Bot Not Receiving Messages

Check bot is admin: Your bot must be added as an administrator to the channel
Verify chat ID: Use negative ID for channels (e.g., -1001234567890)

Test with curl:

curl -X POST "https://api.telegram.org/bot{YOUR_TOKEN}/sendMessage" \
  -d "chat_id={YOUR_CHAT_ID}" \
  -d "text=Test message"

No Notifications in Production

Check environment: Verify APP_ENV=production or staging
Check config: Run php artisan config:cache after changes
Check logs: Enable ALERT_LOG_ERRORS=true and check storage/logs/laravel.log
Check queue: If using queues, ensure queue worker is running: php artisan queue:work

DNS Resolution Errors

If you see Could not resolve host: api.telegram.org:

Check internet connectivity
Flush DNS cache: sudo dscacheutil -flushcache (macOS)
Try different DNS servers (e.g., Google DNS 8.8.8.8)
Check firewall/antivirus settings

Notifications Delayed

If notifications arrive late:

Check queue worker: php artisan queue:work must be running
Disable queue: Set ALERT_QUEUE=false for immediate sending
Check queue connection: Verify your QUEUE_CONNECTION is working

Security

Sensitive Data

Be careful not to send sensitive information in error notifications:

Avoid logging passwords, API keys, or tokens
Consider filtering context data before sending
Use environment-specific chat channels
Review stack traces for sensitive information

Best Practices

Use separate Telegram channels for different environments
Restrict channel access to authorized personnel only
Regularly rotate bot tokens
Monitor notification volume to detect attacks

Testing

Run the package tests:

composer test

Or with PHPUnit directly:

vendor/bin/phpunit

Changelog

Please see CHANGELOG for recent changes.

Contributing

Contributions are welcome! Please submit pull requests to the main repository.

License

The MIT License (MIT). Please see License File for more information.

Credits

Technobase - Package development and maintenance
Laravel Notification Channels - Telegram integration
All contributors

Support

For support, please contact dev@technobase.krd or open an issue on GitHub.

Made with ❤️ by Technobase

technobase / alert

Maintainers

Details