diff --git a/doc/01-utils.md b/doc/01-utils.md index 64b3e4d40b86f54e03bc8e11854c2f0249372997..304f3d6fc29b399d56d8ee375f47bf555eaca5e2 100644 --- a/doc/01-utils.md +++ b/doc/01-utils.md @@ -1,34 +1,46 @@ ## 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