Unverified Commit 0e5821b2 authored by Armando Lüscher's avatar Armando Lüscher Committed by GitHub

Merge pull request #964 from noplanman/psr3-logger

Use PSR-3 LoggerInterface to allow custom logging implementations.
parents c8329d63 377173e8
......@@ -11,7 +11,9 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
- Use PSR-12 for code style.
- Some general housekeeping. (#972)
- [:exclamation:][unreleased-bc] Return an empty array for Entity properties with no items, instead of `null`. (#969)
- `TelegramLog` now adheres to [PSR-3] `LoggerInterface` and allows custom logger implementations.
### Deprecated
- Old logging that uses Monolog still works but will be removed in the near future. Use `TelegramLog::initialize($logger, $update_logger);` from now on.
### Removed
- Botan.io integration completely removed.
### Fixed
......@@ -290,6 +292,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
[0.45.0-bc-up-download-directory]: https://github.com/php-telegram-bot/core/wiki/Breaking-backwards-compatibility#up-download-directory
[0.44.0-bc-update-content-type]: https://github.com/php-telegram-bot/core/wiki/Breaking-backwards-compatibility#update-getupdatecontent
[example-bot]: https://github.com/php-telegram-bot/example-bot
[PSR-3]: https://www.php-fig.org/psr/psr-3
[Unreleased]: https://github.com/php-telegram-bot/core/compare/master...develop
[0.57.0]: https://github.com/php-telegram-bot/core/compare/0.56.0...0.57.0
......
......@@ -28,6 +28,7 @@
"ext-curl": "*",
"ext-json": "*",
"ext-mbstring": "*",
"psr/log": "^1.1",
"monolog/monolog": "^1.24",
"guzzlehttp/guzzle": "^6.3"
},
......
......@@ -4,7 +4,7 @@
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
"This file is @generated automatically"
],
"content-hash": "b3ac8abe31dc69491d76f5b4bb65ca26",
"content-hash": "07b4a4919442371656638370b1b75f85",
"packages": [
{
"name": "guzzlehttp/guzzle",
......
## Logging
PHP Telegram Bot library features [Monolog](https://github.com/Seldaek/monolog) to store logs.
PHP Telegram Bot library features [PSR-3] compatible logging to store logs.
You can find a list of compatible packages that can be used on [Packagist][PSR-3-providers].
Logs are divided into the following streams:
### Error
Collects all the exceptions thrown by the library:
```php
TelegramLog::initErrorLog($path . '/' . $BOT_NAME . '_error.log');
```
- `error`: Collects all the exceptions thrown by the library.
- `debug`: Stores requests made to the Telegram API, useful for debugging.
- `update`: Incoming raw updates (JSON string from Webhook and getUpdates).
### Initialisation
To initialise the logger, you can pass any `LoggerInterface` objects to the `TelegramLog::initialize` method.
The first parameter is the main logger, the second one is used for the raw updates.
### Debug
Stores requests made to the Telegram API, useful for debugging:
(in this example we're using [Monolog])
```php
TelegramLog::initDebugLog($path . '/' . $BOT_NAME . '_debug.log');
use Monolog\Formatter\LineFormatter;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use Longman\TelegramBot\TelegramLog;
TelegramLog::initialize(
// Main logger that handles all 'error' and 'debug' logs.
new Logger('telegram_bot', [
(new StreamHandler(__DIR__ . "/logs/{$bot_username}_debug.log", Logger::DEBUG))->setFormatter(new LineFormatter(null, null, true)),
(new StreamHandler(__DIR__ . "/logs/{$bot_username}_error.log", Logger::ERROR))->setFormatter(new LineFormatter(null, null, true)),
]),
// Updates logger for raw updates.
new Logger('telegram_bot_updates', [
(new StreamHandler(__DIR__ . "/logs/{$bot_username}_update.log", Logger::INFO))->setFormatter(new LineFormatter('%message%' . PHP_EOL)),
])
);
```
### Raw data
Incoming updates (JSON string from Webhook and getUpdates) get logged in a text file:
```php
TelegramLog::initUpdateLog($path . '/' . $BOT_NAME . '_update.log');
```
Why do I need to log the raw updates?
Telegram API changes continuously and it often happens that the database schema is not up to date with new entities/features. So it can happen that your table schema doesn't allow storing new valuable information coming from Telegram.
If you store the raw data you can import all updates on the newest table schema by simply using [this script](../utils/importFromLog.php).
Remember to always backup first!!
## Stream and external sources
Error and Debug streams rely on the `bot_log` instance that can be provided from an external source:
```php
TelegramLog::initialize($monolog);
```
Raw data relies on the `bot_update_log` instance that uses a custom format.
[PSR-3]: https://www.php-fig.org/psr/psr-3
[PSR-3-providers]: https://packagist.org/providers/psr/log-implementation
[Monolog]: https://github.com/Seldaek/monolog
......@@ -538,7 +538,7 @@ class Telegram
public function enableAdmin($admin_id)
{
if (!is_int($admin_id) || $admin_id <= 0) {
TelegramLog::error('Invalid value "%s" for admin.', $admin_id);
TelegramLog::error('Invalid value "' . $admin_id . '" for admin.');
} elseif (!in_array($admin_id, $this->admins_list, true)) {
$this->admins_list[] = $admin_id;
}
......@@ -631,7 +631,7 @@ class Telegram
public function addCommandsPath($path, $before = true)
{
if (!is_dir($path)) {
TelegramLog::error('Commands path "%s" does not exist.', $path);
TelegramLog::error('Commands path "' . $path . '" does not exist.');
} elseif (!in_array($path, $this->commands_paths, true)) {
if ($before) {
array_unshift($this->commands_paths, $path);
......
This diff is collapsed.
......@@ -35,8 +35,9 @@ class TelegramLogTest extends TestCase
protected function setUp()
{
// Make sure no monolog instance is set before each test.
TestHelpers::setStaticProperty(TelegramLog::class, 'monolog', null);
// Make sure no logger instance is set before each test.
TestHelpers::setStaticProperty('Longman\TelegramBot\TelegramLog', 'logger', null);
TestHelpers::setStaticProperty('Longman\TelegramBot\TelegramLog', 'update_logger', null);
}
protected function tearDown()
......@@ -78,12 +79,14 @@ class TelegramLogTest extends TestCase
TelegramLog::initErrorLog($file);
TelegramLog::error('my error');
TelegramLog::error('my 50% error');
TelegramLog::error('my %s error', 'placeholder');
TelegramLog::error('my old %s %s error', 'custom', 'placeholder');
TelegramLog::error('my new {place} {holder} error', ['place' => 'custom', 'holder' => 'placeholder']);
$this->assertFileExists($file);
$error_log = file_get_contents($file);
$this->assertContains('bot_log.ERROR: my error', $error_log);
$this->assertContains('bot_log.ERROR: my 50% error', $error_log);
$this->assertContains('bot_log.ERROR: my placeholder error', $error_log);
$this->assertContains('bot_log.ERROR: my old custom placeholder error', $error_log);
$this->assertContains('bot_log.ERROR: my new custom placeholder error', $error_log);
}
public function testDebugStream()
......@@ -93,12 +96,14 @@ class TelegramLogTest extends TestCase
TelegramLog::initDebugLog($file);
TelegramLog::debug('my debug');
TelegramLog::debug('my 50% debug');
TelegramLog::debug('my %s debug', 'placeholder');
TelegramLog::debug('my old %s %s debug', 'custom', 'placeholder');
TelegramLog::debug('my new {place} {holder} debug', ['place' => 'custom', 'holder' => 'placeholder']);
$this->assertFileExists($file);
$debug_log = file_get_contents($file);
$this->assertContains('bot_log.DEBUG: my debug', $debug_log);
$this->assertContains('bot_log.DEBUG: my 50% debug', $debug_log);
$this->assertContains('bot_log.DEBUG: my placeholder debug', $debug_log);
$this->assertContains('bot_log.DEBUG: my old custom placeholder debug', $debug_log);
$this->assertContains('bot_log.DEBUG: my new custom placeholder debug', $debug_log);
}
public function testUpdateStream()
......@@ -108,12 +113,14 @@ class TelegramLogTest extends TestCase
TelegramLog::initUpdateLog($file);
TelegramLog::update('my update');
TelegramLog::update('my 50% update');
TelegramLog::update('my %s update', 'placeholder');
TelegramLog::update('my old %s %s update', 'custom', 'placeholder');
TelegramLog::update('my new {place} {holder} update', ['place' => 'custom', 'holder' => 'placeholder']);
$this->assertFileExists($file);
$debug_log = file_get_contents($file);
$this->assertContains('my update', $debug_log);
$this->assertContains('my 50% update', $debug_log);
$this->assertContains('my placeholder update', $debug_log);
$update_log = file_get_contents($file);
$this->assertContains('my update', $update_log);
$this->assertContains('my 50% update', $update_log);
$this->assertContains('my old custom placeholder update', $update_log);
$this->assertContains('my new custom placeholder update', $update_log);
}
public function testExternalStream()
......@@ -121,25 +128,29 @@ class TelegramLogTest extends TestCase
$file = self::$logfiles['external'];
$this->assertFileNotExists($file);
$external_monolog = new Logger('bot_update_log');
$external_monolog = new Logger('bot_external_log');
$external_monolog->pushHandler(new StreamHandler($file, Logger::ERROR));
$external_monolog->pushHandler(new StreamHandler($file, Logger::DEBUG));
TelegramLog::initialize($external_monolog);
TelegramLog::error('my error');
TelegramLog::error('my 50% error');
TelegramLog::error('my %s error', 'placeholder');
TelegramLog::error('my old %s %s error', 'custom', 'placeholder');
TelegramLog::error('my new {place} {holder} error', ['place' => 'custom', 'holder' => 'placeholder']);
TelegramLog::debug('my debug');
TelegramLog::debug('my 50% debug');
TelegramLog::debug('my %s debug', 'placeholder');
TelegramLog::debug('my old %s %s debug', 'custom', 'placeholder');
TelegramLog::debug('my new {place} {holder} debug', ['place' => 'custom', 'holder' => 'placeholder']);
$this->assertFileExists($file);
$file_contents = file_get_contents($file);
$this->assertContains('bot_update_log.ERROR: my error', $file_contents);
$this->assertContains('bot_update_log.ERROR: my 50% error', $file_contents);
$this->assertContains('bot_update_log.ERROR: my placeholder error', $file_contents);
$this->assertContains('bot_update_log.DEBUG: my debug', $file_contents);
$this->assertContains('bot_update_log.DEBUG: my 50% debug', $file_contents);
$this->assertContains('bot_update_log.DEBUG: my placeholder debug', $file_contents);
$this->assertContains('bot_external_log.ERROR: my error', $file_contents);
$this->assertContains('bot_external_log.ERROR: my 50% error', $file_contents);
$this->assertContains('bot_external_log.ERROR: my old custom placeholder error', $file_contents);
$this->assertContains('bot_external_log.ERROR: my new custom placeholder error', $file_contents);
$this->assertContains('bot_external_log.DEBUG: my debug', $file_contents);
$this->assertContains('bot_external_log.DEBUG: my 50% debug', $file_contents);
$this->assertContains('bot_external_log.DEBUG: my old custom placeholder debug', $file_contents);
$this->assertContains('bot_external_log.DEBUG: my new custom placeholder debug', $file_contents);
}
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment