{"id":31787105,"url":"https://github.com/uzziahlukeka/telegrammonitor","last_synced_at":"2026-05-23T05:19:58.613Z","repository":{"id":275301453,"uuid":"925708864","full_name":"Uzziahlukeka/telegrammonitor","owner":"Uzziahlukeka","description":"Monitor your Laravel application logs in real-time through Telegram. This package delivers instant notifications of critical events directly to your Telegram channel, with support for threaded discussions and Markdown formatting.","archived":false,"fork":false,"pushed_at":"2025-08-24T19:12:18.000Z","size":592,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-24T23:22:03.956Z","etag":null,"topics":["laravel","logs","package","php8","telegram"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Uzziahlukeka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"uzhlaravel"}},"created_at":"2025-02-01T14:55:34.000Z","updated_at":"2025-08-24T19:07:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"4fc411ca-e4c4-4acd-b641-df757223f554","html_url":"https://github.com/Uzziahlukeka/telegrammonitor","commit_stats":null,"previous_names":["uzziahlukeka/telegrammonitor"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/Uzziahlukeka/telegrammonitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Uzziahlukeka%2Ftelegrammonitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Uzziahlukeka%2Ftelegrammonitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Uzziahlukeka%2Ftelegrammonitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Uzziahlukeka%2Ftelegrammonitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Uzziahlukeka","download_url":"https://codeload.github.com/Uzziahlukeka/telegrammonitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Uzziahlukeka%2Ftelegrammonitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004068,"owners_count":26083667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel","logs","package","php8","telegram"],"created_at":"2025-10-10T13:50:59.207Z","updated_at":"2026-05-23T05:19:58.605Z","avatar_url":"https://github.com/Uzziahlukeka.png","language":"PHP","funding_links":["https://github.com/sponsors/uzhlaravel"],"categories":[],"sub_categories":[],"readme":"# Telegram Logs Monitor for Laravel\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/uzhlaravel/telegramlogs.svg?style=flat-square)](https://packagist.org/packages/uzhlaravel/telegramlogs)\n![GitHub Tests Action Status](https://github.com/Uzziahlukeka/telegrammonitor/actions/workflows/run-tests.yml/badge.svg)\n![Code style](https://github.com/Uzziahlukeka/telegrammonitor/actions/workflows/fix-php-code-style-issues.yml/badge.svg)\n[![Total Downloads](https://img.shields.io/packagist/dt/uzhlaravel/telegramlogs.svg?style=flat-square)](https://packagist.org/packages/uzhlaravel/telegramlogs)\n[![License](https://img.shields.io/packagist/l/uzhlaravel/telegramlogs.svg?style=flat-square)](https://packagist.org/packages/uzhlaravel/telegramlogs)\n\n---\n\nA Laravel package that sends your application logs, exceptions, and model activity events directly to a Telegram channel or group — in real time.\n\nSupports **Laravel 10 → 13**, PHP 8.2+, and includes production-only mode so notifications stay silent during local development.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Configuration](#configuration)\n  - [Environment Variables](#environment-variables)\n  - [Restrict to Production Only](#restrict-to-production-only)\n- [Usage](#usage)\n  - [Log Channel Integration](#log-channel-integration)\n  - [Direct Messaging](#direct-messaging)\n  - [Activity Log](#activity-log)\n    - [HasTelegramActivity Trait](#hastelegramactivity-trait)\n    - [TelegramActivity Facade](#telegramactivity-facade)\n- [Artisan Commands](#artisan-commands)\n- [Log Levels](#log-levels)\n- [Getting Telegram Credentials](#getting-telegram-credentials)\n- [Security](#security)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Features\n\n- **Monolog integration** — drop-in `telegram` log channel; works with `LOG_CHANNEL=telegram` or as a stacked channel\n- **Direct messaging** — send arbitrary text to any chat from anywhere in your app\n- **Activity log** — track Eloquent model `created / updated / deleted` events and push them to Telegram (inspired by [spatie/laravel-activitylog](https://github.com/spatie/laravel-activitylog))\n- **Production-only mode** — restrict notifications to specific environments with a single env var\n- **Smart formatting** — emoji-labelled MarkdownV2 messages with context, exception details, and stack traces\n- **Long message splitting** — automatically splits messages that exceed Telegram's 4096-char limit\n- **Forum/topic support** — route messages to specific threads in a Telegram group\n- **Interactive install** — guided `telegramlogs:install` command\n\n---\n\n## Requirements\n\n| Dependency | Version |\n|------------|---------|\n| PHP | ^8.2 |\n| Laravel | ^10.0 \\| ^11.0 \\| ^12.0 \\| ^13.0 |\n\n---\n\n## Installation\n\n```bash\ncomposer require uzhlaravel/telegramlogs\n```\n\nRun the interactive setup wizard:\n\n```bash\nphp artisan telegramlogs:install\n```\n\nThe wizard will publish the config file, help you set environment variables, optionally enable activity log, and send a test message.\n\nOr publish the config manually:\n\n```bash\nphp artisan vendor:publish --tag=\"telegramlogs-config\"\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\nAdd these to your `.env` file:\n\n```env\n# Required\nTELEGRAM_BOT_TOKEN=your_bot_token_here\nTELEGRAM_CHAT_ID=your_chat_id_here\n\n# Optional\nTELEGRAM_LOG_LEVEL=critical          # minimum level to forward (default: critical)\nTELEGRAM_TOPIC_ID=                   # forum thread / topic ID\nTELEGRAM_TIMEOUT=10                  # Telegram API timeout in seconds\n\n# Environment control — see next section\nTELEGRAM_ENVIRONMENTS=production     # default: production only\n\n# Activity log\nTELEGRAM_ACTIVITY_LOG=false          # set true to enable model event tracking\nTELEGRAM_ACTIVITY_LOG_LEVEL=info     # log level for activity notifications\n```\n\n### Full Reference\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `TELEGRAM_BOT_TOKEN` | Yes | — | Bot API token from @BotFather |\n| `TELEGRAM_CHAT_ID` | Yes | — | Target chat, channel, or group ID |\n| `TELEGRAM_TOPIC_ID` | No | `null` | Forum topic (thread) ID |\n| `TELEGRAM_TOPIC_MESSAGE_ID` | No | `null` | Forum thread message ID |\n| `TELEGRAM_LOG_LEVEL` | No | `critical` | Minimum PSR-3 level to send |\n| `TELEGRAM_TIMEOUT` | No | `10` | HTTP timeout in seconds |\n| `TELEGRAM_ENVIRONMENTS` | No | `production` | Comma-separated env list, or `*` |\n| `TELEGRAM_ACTIVITY_LOG` | No | `false` | Enable model activity tracking |\n| `TELEGRAM_ACTIVITY_LOG_LEVEL` | No | `info` | Log level for activity messages |\n\n---\n\n### Restrict to Production Only\n\nBy default, notifications are only sent when `APP_ENV=production`. This prevents your local machine or CI from flooding your Telegram channel.\n\n```env\n# Only production (default)\nTELEGRAM_ENVIRONMENTS=production\n\n# Production and staging\nTELEGRAM_ENVIRONMENTS=production,staging\n\n# Every environment — useful for local debugging\nTELEGRAM_ENVIRONMENTS=*\n```\n\nThe current environment and whether notifications are active are both shown in:\n\n```bash\nphp artisan telegramlogs:test --config\n```\n\n---\n\n## Usage\n\n### Log Channel Integration\n\nSet Telegram as your default channel:\n\n```env\nLOG_CHANNEL=telegram\n```\n\nOr add it to a stack so critical logs go to both your file log and Telegram:\n\n```php\n// config/logging.php\n'channels' =\u003e [\n    'stack' =\u003e [\n        'driver'   =\u003e 'stack',\n        'channels' =\u003e ['daily', 'telegram'],\n    ],\n],\n```\n\nUse it like any Laravel logger:\n\n```php\nuse Illuminate\\Support\\Facades\\Log;\n\nLog::error('Payment processing failure');\n\nLog::critical('Database unreachable', [\n    'connection' =\u003e 'mysql',\n    'host'       =\u003e config('database.connections.mysql.host'),\n]);\n\ntry {\n    // ...\n} catch (\\Exception $e) {\n    Log::error('Unexpected exception', ['exception' =\u003e $e]);\n}\n```\n\nMessages arrive in Telegram formatted like this:\n\n```\n❌ ERROR — MyApp [production]\n\nPayment processing failure\n\nContext:\n{\n  \"connection\": \"mysql\"\n}\n\n🕐 2025-08-19 14:32:01 UTC\n```\n\n---\n\n### Direct Messaging\n\nSend arbitrary messages to Telegram without going through the logger — useful for contact forms, webhooks, or manual alerts.\n\n```php\nuse Uzhlaravel\\Telegramlogs\\Facades\\TelegramMessage;\n\n// Simple text\nTelegramMessage::message('Scheduled backup completed.');\n\n// With Telegram API options\nTelegramMessage::send('Deployment finished', [\n    'parse_mode'               =\u003e 'HTML',\n    'disable_web_page_preview' =\u003e true,\n]);\n\n// Send to a different chat\nTelegramMessage::toChat('-100987654321', 'Alert for ops team');\n\n// Test connectivity\nTelegramMessage::test();\n\n// Get bot information\nTelegramMessage::getBotInfo();\n```\n\n---\n\n### Activity Log\n\nInspired by [spatie/laravel-activitylog](https://github.com/spatie/laravel-activitylog), the activity log tracks Eloquent model events and pushes a formatted notification to Telegram.\n\nEnable it in `.env`:\n\n```env\nTELEGRAM_ACTIVITY_LOG=true\n```\n\n#### HasTelegramActivity Trait\n\nAdd the trait to any Eloquent model to automatically track its lifecycle events:\n\n```php\nuse Uzhlaravel\\Telegramlogs\\Traits\\HasTelegramActivity;\n\nclass Post extends Model\n{\n    use HasTelegramActivity;\n}\n```\n\nOn `created`, `updated`, or `deleted`, a message like the following is sent to Telegram:\n\n```\n🟢 Activity — MyApp [production]\n\nCreated Post\n\nSubject: Post #42\nProperties:\n{\n  \"attributes\": { \"title\": \"Hello World\", \"status\": \"draft\" }\n}\n\n🕐 2025-08-19 14:32:01 UTC\n```\n\n**Customise per model:**\n\n```php\nuse Uzhlaravel\\Telegramlogs\\Traits\\HasTelegramActivity;\n\nclass Order extends Model\n{\n    use HasTelegramActivity;\n\n    // Track only these events for this model\n    protected array $telegramActivityEvents = ['created', 'deleted'];\n\n    // Custom description\n    public function getTelegramActivityDescription(string $event): string\n    {\n        return ucfirst($event) . ' order #' . $this-\u003eid . ' — ' . $this-\u003estatus;\n    }\n\n    // Extra properties to include\n    public function getTelegramActivityProperties(string $event): array\n    {\n        return ['total' =\u003e $this-\u003etotal, 'customer' =\u003e $this-\u003ecustomer-\u003ename];\n    }\n}\n```\n\nGlobal event list is controlled in `config/telegramlogs.php`:\n\n```php\n'activity_log' =\u003e [\n    'events'             =\u003e ['created', 'updated', 'deleted'],\n    'include_old_values' =\u003e true,   // previous values on update\n    'include_new_values' =\u003e true,   // changed values on update\n],\n```\n\n#### TelegramActivity Facade\n\nFor manual / one-off activity notifications, use the fluent facade:\n\n```php\nuse Uzhlaravel\\Telegramlogs\\Facades\\TelegramActivity;\n\nTelegramActivity::performedOn($post)\n    -\u003ecausedBy(auth()-\u003euser())\n    -\u003ewithProperty('plan', 'pro')\n    -\u003eevent('published')\n    -\u003edispatch('Post was published');\n\n// Simpler form\nTelegramActivity::log('Nightly cleanup job finished');\n```\n\n---\n\n## Artisan Commands\n\n```bash\n# Interactive setup\nphp artisan telegramlogs:install\n\n# Send a test log message\nphp artisan telegramlogs:test\n\n# Send with a custom message and level\nphp artisan telegramlogs:test --message=\"Health check OK\" --level=warning\n\n# Send a test activity notification\nphp artisan telegramlogs:test --activity\n\n# Show current configuration (includes environment status)\nphp artisan telegramlogs:test --config\n\n# List available log levels\nphp artisan telegramlogs:test --list\n```\n\n---\n\n## Log Levels\n\n| Level | Emoji | Use Case |\n|-------|-------|----------|\n| `emergency` | 🚨 | System is unusable |\n| `alert` | 🔴 | Immediate action required |\n| `critical` | 💥 | Critical conditions |\n| `error` | ❌ | Runtime errors |\n| `warning` | ⚠️ | Potential issues |\n| `notice` | 📢 | Significant normal events |\n| `info` | ℹ️ | General operational messages |\n| `debug` | 🐛 | Detailed diagnostic information |\n\n---\n\n## Getting Telegram Credentials\n\n### 1. Create a Bot\n\n1. Open [@BotFather](https://t.me/BotFather) in Telegram\n2. Send `/newbot` and follow the prompts\n3. Copy the token into `TELEGRAM_BOT_TOKEN`\n\n### 2. Get Your Chat ID\n\n- **Channel** — add the bot as an admin; the channel username (`@mychannel`) or numeric ID (`-100xxxxxxxxx`) works\n- **Group** — add the bot to the group; send a message, then call `https://api.telegram.org/bot\u003ctoken\u003e/getUpdates` to find `chat.id`\n- **Private chat** — start a chat with the bot, then use `getUpdates`\n\n### 3. Forum Topics (optional)\n\n1. Enable Topics in your group settings\n2. Create a topic and send a message\n3. From `getUpdates`, copy `message_thread_id` → `TELEGRAM_TOPIC_ID`\n\n---\n\n## Security\n\n- Store `TELEGRAM_BOT_TOKEN` only in `.env` — never commit it\n- Restrict which commands the bot can receive (via BotFather → `/mybots → Bot Settings → Group Privacy`)\n- Audit who has access to your Telegram channel regularly\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Commit your changes: `git commit -m 'Add my feature'`\n4. Push: `git push origin feature/my-feature`\n5. Open a pull request\n\n**Development commands:**\n\n```bash\ngit clone https://github.com/Uzziahlukeka/telegrammonitor.git\ncd telegrammonitor\ncomposer install\ncomposer test        # run test suite\ncomposer analyse     # PHPStan static analysis\ncomposer format      # Laravel Pint code style\n```\n\n---\n\n## License\n\nThis package is open-sourced software licensed under the [MIT License](LICENSE.md).\n\n---\n\n💖 Made with love by [Uzziah Lukeka](https://github.com/Uzziahlukeka)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuzziahlukeka%2Ftelegrammonitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuzziahlukeka%2Ftelegrammonitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuzziahlukeka%2Ftelegrammonitor/lists"}