jpblu/telegram-error-notifier

A PHP library for sending alert messages to a Telegram bot. Compatible with Laravel.

v1.3.1 2025-07-23 08:42 UTC

Requires

• php: >=7.4
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^12.0

MIT

README

Telegram Error Notifier

A PHP library for sending alert messages to a Telegram bot. Compatible with Laravel.

Installation

You can install the package using Composer:

composer require jpblu/telegram-error-notifier

Telegram Setup

1. Create a Telegram bot.
2. Get the bot token.
3. Create a private or public channel.
4. Add your bot as an admin of the channel.
5. Get the channel ID (prefix with @ if it's a public channel or use the numeric ID for private ones).

Note: Refer to Telegram Bot documentations for further instructions.

Usage (PHP projects)

use TelegramNotifier\TelegramNotifier;

$notifier = new TelegramNotifier('TELEGRAM_BOT_TOKEN', 'TELEGRAM_CHAT_ID');
$response = $notifier->send('An error occurred in your service.');

Usage (Laravel project)

This library automatically registers a Service Provider and Facade if used in a Laravel project.

Configuration

1. Add environment variables to your .env file:

TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id

1. Add to config/services.php

'telegram_notifier' => [
    'bot_token' => env('TELEGRAM_BOT_TOKEN'),
    'chat_id' => env('TELEGRAM_CHAT_ID'),
],

Examples

Send an error message inside a try/catch block

use TelegramNotifier\TelegramNotifier;

public function store(Request $request)
{
    try {
        // Application logic
    } catch (\Throwable $e) {
        app(\TelegramNotifier::class)->send($e->getMessage());
        throw $e; // or handle the exception
    }
}

Notify errors inside a queued Job

use TelegramNotifier\TelegramNotifier;
use Illuminate\Contracts\Queue\ShouldQueue;

class ProcessUserJob implements ShouldQueue
{
    public function handle()
    {
        try {
            // Background processing logic
        } catch (\Throwable $e) {
            app(\TelegramNotifier::class)->send("Job failed: " . $e->getMessage());
            throw $e;
        }
    }
}

Catch all unhandled exceptions in the global Exception Handler

Edit your app/Exceptions/Handler.php file:

use TelegramNotifier\TelegramNotifier;

public function report(Throwable $exception)
{
    parent::report($exception);

    if ($this->shouldReport($exception)) {
        app(\TelegramNotifier::class)->send($exception->getMessage());
    }
}

Manual notification

TelegramNotifier::send('User import completed successfully.');

Returned Values

The send() method returns an array with the response from the Telegram API (or an error if applicable).

Example:

[
    'ok' => true,
    'result' => [
        'message_id' => 123,
        'chat' => [...],
        'text' => 'Your message'
    ]
]

Laravel Compatibility

This package has been tested and works with the following Laravel versions:

• Laravel 8.x
• Laravel 9.x (LTS)
• Laravel 10.x (LTS)
• Laravel 11.x
• Laravel 12.x

Laravel 5.5+ may also work, as this package uses automatic service provider registration via Composer.

Acknowledgments

• GuzzleHTTP for client connection
• PHPUnit for testing suite