Skip to content

Commit abdb175

Browse files
UzziahlukekaUzziahlukeka
committed
readme update and command
1 parent 3126759 commit abdb175

File tree

5 files changed

+240
-37
lines changed

5 files changed

+240
-37
lines changed

‎README.md‎

Lines changed: 143 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -5,83 +5,192 @@
55
![Code style](https://github.com/Uzziahlukeka/telegrammonitor/actions/workflows/fix-php-code-style-issues.yml/badge.svg)
66
[![Total Downloads](https://img.shields.io/packagist/dt/uzhlaravel/telegramlogs.svg?style=flat-square)](https://packagist.org/packages/uzhlaravel/telegramlogs)
77

8-
Get real-time Laravel application logs directly in your Telegram channel. This package provides instant monitoring of your application's critical events through Telegram messages, with support for threaded discussions and Markdown formatting.
8+
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.
99

10+
## Key Features
1011

11-
## Features
12+
- **Real-time log delivery** to Telegram channels
13+
- **One-command installation** with guided setup
14+
- **Configuration testing** before deployment
15+
- **Configurable log levels** (emergency to debug)
16+
- **Threaded discussions** support via Telegram topics
17+
- **MarkdownV2** formatted messages
18+
- **JSON** formatted messages
19+
- **Automatic message splitting** for long logs
20+
- **Customizable timeout** for API calls
21+
- **Test command** to verify your setup
1222

13-
- 📨 Instant delivery of logs to Telegram
14-
- 🔔 Configurable log levels (emergency to debug)
15-
- 🧵 Support for Telegram topic threads
16-
- ✏️ MarkdownV2 formatted messages
17-
- 📦 Automatic splitting of long messages
18-
- ⏱ Configurable timeout for API calls
19-
- 🛠 Test command to verify your setup
23+
## Prerequisites
24+
25+
Before installation, you'll need:
26+
1. A Telegram bot token (create one via [BotFather](https://core.telegram.org/bots#botfather))
27+
2. A Telegram channel/group chat ID
28+
3. Laravel 8.0+ application
2029

2130
## Installation
2231

23-
You can install the package via composer:
32+
Install the package via Composer:
2433

2534
```bash
2635
composer require uzhlaravel/telegramlogs
2736
```
2837

29-
You can publish the config file with:
38+
Run the installation command for guided setup:
39+
40+
### One-command Installation
41+
42+
```bash
43+
php artisan telegramlogs:install
44+
```
45+
46+
This will:
47+
1. Publish the configuration file
48+
2. Guide you through environment setup
49+
3. Optionally set Telegram as your default log channel
50+
4. Test your configuration
51+
52+
### Manual Installation
53+
54+
Publish the configuration file:
3055

3156
```bash
3257
php artisan vendor:publish --tag="telegramlogs-config"
3358
```
3459

35-
This is the contents of the published config file:
3660

37-
```php
38-
return [
39-
'bot_token' => env('TELEGRAM_BOT_TOKEN'),
40-
'chat_id' => env('TELEGRAM_CHAT_ID'),
41-
'topic_id' => env('TELEGRAM_TOPIC_ID'),
42-
];
61+
## Configuration
62+
63+
### Automated Setup
64+
65+
The installation command will guide you through setting up:
66+
67+
```bash
68+
php artisan telegramlogs:install
4369
```
4470

45-
This is the contents in .env:
71+
### Manual Configuration
4672

47-
```php
73+
74+
Update your `.env` file with these settings:
75+
76+
```ini
4877
TELEGRAM_BOT_TOKEN=your_bot_token_here
4978
TELEGRAM_CHAT_ID=your_chat_id_here
50-
# Optional:
79+
# Optional settings:
5180
TELEGRAM_TOPIC_ID=your_thread_id_here
5281
TELEGRAM_LOGS_LEVEL=error
5382
```
5483

84+
### Available Log Levels
85+
86+
| Level | Description |
87+
|------------|--------------------------------------|
88+
| Debug | Detailed debug information |
89+
| Info | Informational messages |
90+
| Notice | Normal but significant events |
91+
| Warning | Warning conditions |
92+
| Error | Error conditions |
93+
| Critical | Critical conditions |
94+
| Alert | Immediate action required |
95+
| Emergency | System is unusable |
96+
97+
### Logging Configuration
98+
99+
Set your default log channel in `.env`:
100+
101+
```ini
102+
LOG_CHANNEL=telegram
103+
```
104+
55105
## Usage
56106

107+
### Basic Logging
108+
57109
```php
58-
$telegramlogs = new Uzhlaravel\Telegramlogs();
59-
echo $telegramlogs->echoPhrase('Hello, Uzhlaravel!');
110+
// Basic error logging
111+
\Log::error('Payment processing failed');
112+
113+
// Exception handling
114+
try {
115+
// Your code
116+
} catch (\Exception $e) {
117+
\Log::critical('API Connection Failed: ' . $e->getMessage());
118+
}
119+
120+
// Debug messages
121+
\Log::debug('User authenticated', ['user_id' => auth()->id()]);
60122
```
61123

62-
## Testing
124+
### Command Line Tools
63125

126+
#### Test Configuration
127+
128+
```bash
129+
php artisan telegramlogs:test
130+
```
131+
132+
Options:
133+
- `--message="Custom message"` - Send custom test message
134+
- `--level=error` - Specify log level
135+
- `--list` - Show available log levels
136+
- `--config` - Display current configuration
137+
138+
Example with custom message:
64139
```bash
65-
composer test
140+
php artisan telegramlogs:test --message="System check" --level=warning
141+
```
142+
143+
#### Show Configuration
144+
145+
```bash
146+
php artisan telegramlogs:test --config
147+
```
148+
149+
## Expected Output
150+
151+
Messages in your Telegram channel will appear as formatted JSON:
152+
153+
```json
154+
{
155+
"message": "Database connection failed",
156+
"level": "CRITICAL",
157+
"datetime": "2025-08-17T11:55:13.885292+00:00",
158+
"context": {
159+
"exception": "PDOException: could not find driver"
160+
}
161+
}
66162
```
67163

164+
![Sample Telegram Notification](img.png)
165+
166+
## Getting Telegram Credentials
167+
168+
1. **Create a Bot**: Visit [BotFather](https://core.telegram.org/bots#botfather) to create your bot and get the API token
169+
2. **Get Chat ID**: Add your bot to a channel/group and visit:
170+
```
171+
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
172+
```
173+
3. **Enable Topics** (optional): Create a topic in your group to get the topic_id
174+
175+
## Security Considerations
176+
177+
- Keep your bot token secure
178+
- Restrict bot access to specific chats
179+
- Review [our security policy](../../security/policy) for vulnerability reporting
180+
68181
## Changelog
69182

70-
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
183+
See [CHANGELOG](CHANGELOG.md) for version history.
71184

72185
## Contributing
73186

74-
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
187+
We welcome contributions! Please see [CONTRIBUTING](CONTRIBUTING.md) for guidelines.
75188

76-
## Security Vulnerabilities
189+
## License
77190

78-
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
191+
MIT License. See [LICENSE](LICENSE.md) for details.
79192

80193
## Credits
81194

82-
- [uzziahlukeka](https://github.com/uzhlaravel)
195+
- [Uzziahlukeka](https://github.com/Uzziahlukeka/telegrammonitor)
83196
- [All Contributors](../../contributors)
84-
85-
## License
86-
87-
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

‎img.png‎

55.4 KB
Loading

‎src/Commands/InstallTelegramLogsCommand.php‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
<?php
2+
3+
namespace Uzhlaravel\Telegramlogs\Commands;
4+
5+
use Illuminate\Console\Command;
6+
7+
class InstallTelegramLogsCommand extends Command
8+
{
9+
/**
10+
* The name and signature of the console command.
11+
*
12+
* @var string
13+
*/
14+
protected $signature = 'telegramlogs:install';
15+
16+
/**
17+
* The console command description.
18+
*
19+
* @var string
20+
*/
21+
protected $description = 'Install the Telegram Logs Monitor package';
22+
23+
/**
24+
* Execute the console command.
25+
*
26+
* @return int
27+
*/
28+
public function handle()
29+
{
30+
$this->info('Installing Telegram Logs Monitor package...');
31+
32+
// 1. Publish configuration
33+
$this->call('vendor:publish', [
34+
'--provider' => 'Uzhlaravel\Telegramlogs\TelegramlogsServiceProvider',
35+
'--tag' => 'telegramlogs-config',
36+
]);
37+
38+
// 2. Display setup instructions
39+
$this->info('Please configure these environment variables in your .env file:');
40+
$this->line('TELEGRAM_BOT_TOKEN=your_bot_token_here');
41+
$this->line('TELEGRAM_CHAT_ID=your_chat_id_here');
42+
$this->line('Optional:');
43+
$this->line('TELEGRAM_TOPIC_ID=your_thread_id_here');
44+
$this->line('TELEGRAM_LOGS_LEVEL=error');
45+
46+
// 3. Update logging configuration
47+
if ($this->confirm('Would you like to set Telegram as your default log channel?', true)) {
48+
$this->updateEnvVariable('LOG_CHANNEL', 'telegram');
49+
$this->info('Default log channel set to "telegram" in .env');
50+
}
51+
52+
// 4. Test configuration
53+
if ($this->confirm('Would you like to test your Telegram configuration now?', true)) {
54+
$this->call('telegramlogs:test');
55+
}
56+
57+
$this->info('Telegram Logs Monitor installed successfully!');
58+
$this->line('Remember to create a Telegram bot and get your credentials if you haven\'t already.');
59+
60+
return 0;
61+
}
62+
63+
/**
64+
* Update an environment variable in the .env file
65+
*
66+
* @param string $key
67+
* @param string $value
68+
*/
69+
protected function updateEnvVariable($key, $value)
70+
{
71+
$envPath = base_path('.env');
72+
73+
if (file_exists($envPath)) {
74+
$content = file_get_contents($envPath);
75+
$content = preg_replace("/^{$key}=.*/m", "{$key}={$value}", $content);
76+
file_put_contents($envPath, $content);
77+
}
78+
}
79+
}

‎src/TelegramlogsServiceProvider.php‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
namespace Uzhlaravel\Telegramlogs;
44

55
use Illuminate\Support\ServiceProvider;
6+
use Uzhlaravel\Telegramlogs\Commands\InstallTelegramLogsCommand;
7+
use Uzhlaravel\Telegramlogs\Commands\TelegramlogsCommand;
68

79
class TelegramlogsServiceProvider extends ServiceProvider
810
{
@@ -22,10 +24,23 @@ public function boot()
2224
__DIR__.'/../config/telegramlogs.php' => config_path('telegramlogs.php'),
2325
], 'telegramlogs-config');
2426

27+
// Register the command
28+
$this->registerCommands();
29+
2530
// Add telegram channel to logging configuration
2631
$this->addTelegramLogChannel();
2732
}
2833

34+
protected function registerCommands()
35+
{
36+
if ($this->app->runningInConsole()) {
37+
$this->commands([
38+
TelegramlogsCommand::class,
39+
InstallTelegramLogsCommand::class,
40+
]);
41+
}
42+
}
43+
2944
protected function addTelegramLogChannel()
3045
{
3146
// Get current logging config

‎tests/ArchTest.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@
55
->toUseStrictTypes()
66
->not->toUse(['die', 'dd', 'dump']);
77

8-
arch()
8+
arch('it will verify commands')
99
->expect('Uzhlaravel\Telegramlogs\Commands')
1010
->toBeClasses()
1111
->toExtend('Illuminate\Console\Command')
12-
->toOnlyBeUsedIn('src\Commands');
12+
->toOnlyBeUsedIn(['src\Commands', 'Uzhlaravel\Telegramlogs']);
1313

14-
arch()
14+
arch('it will verify facades')
1515
->expect('Uzhlaravel\Telegramlogs\Facades')
1616
->toBeClasses()
1717
->toExtend('Illuminate\Support\Facades\Facade');

0 commit comments

Comments
 (0)