victor78/yii2-messenger-target

The log target for any messenger.

Yii2MessengerTarget

MessengerTarget for Yii2 for sending logs as text and/or as files (of which archives) through messengers. Now this extension supports as messenger only Telegram., _(*1)

MessengerTarget для Yii2 для отправки логов как текст и/или как файлы(в том числе как архивы) через месенджеры. Сейчас расширение поддерживает в качестве месседжера только Телеграм., _(*2)

English: * Installation * Configuration * How to create telegram bot * How to take telegram chat id which will receive messages from the bot * How to use * Notes, _(*3)

Русский: * Установка * Настройка * Как создать телеграм бота * Как получить id чата (id пользователя), который будет получать сообщения от бота * Как использовать * Замечания, _(*4)

Installation

The preferred way to install this extension is through composer., _(*5)

Either run, _(*6)

php composer.phar require --prefer-dist victor78/yii2-messenger-target:"~0.0.4"

or add, _(*7)

"victor78/yii2-messenger-target": "~0.0.4"

to the require section of your composer.json., _(*8)

Configuration

return [
    'components' => [
        'telegramPusher' => [
            'class' => 'Victor78\MessengerTarget\TelegramPusher',

            'recipients' => [
                //any element is not required


                //all messages of levels and categories will be received by these users:
                '*' => [
                    'telegram_chat_id_0', //for example, user_id
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],

                //messages which initiated by Yii::error('some message') or Yii::info('some message', 'error')
                //or during catching ErrorException 
                //will be sent to these chats
                'error' => [
                    'telegram_chat_id_0', //for example, user_id
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],
                //messages which initiated by Yii::warning('some message') or Yii::info('some message', 'warning')
                //will be sent to these chats
                'warning' => [
                    'telegram_chat_id_0', //for example, user_id
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],
                //messages which initiated by Yii::debug('some message') or Yii::info('some message', 'trace')
                //will be sent to these chats
                'trace' => [
                    'telegram_chat_id_0', //for example, user_id
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],         
                //messages initiated by 
                //Yii::info('info message', 'some_category_1')  or
                //Yii::debug('trace message', 'some_category_1') or
                //Yii::warning('warning message', 'some_category_1') or
                //Yii::error('error message', 'some_category_1')
                //will be sent to these chats     
                'some_category_1' => [
                    'telegram_chat_id_0', //for example, user_id
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],
                //messages initiated by 
                //Yii::info('info message', 'some_category_2')  or
                //Yii::debug('trace message', 'some_category_2') or
                //Yii::warning('warning message', 'some_category_2') or
                //Yii::error('error message', 'some_category_2')
                //will be sent to these chats                
                'some_category_2' => [
                    'telegram_chat_id_0', //for example, user_id
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],

            ],
            // level or category accroding to telegram bot through 
            'tokens' => [
                //all elements are optional
                //'some_level_or_category' => 'telegram_bot_api_token'
               'info' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
               'error' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
               'warning' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
               'trace' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
               'some_category_1' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
               'some_categiry_2' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
            ], 
        ]
    ],
    //....
    'log' => [
        'targets' => [
            [
            //SPECIFIC OPTIONS for Yii2MessengerTarget
                //required properties
                'class' => 'Victor78\MessengerTarget\MessengerTarget', //required
                'messenger' => 'telegramPusher', //name of configured component

                //optional
                'archiverMethod' => 'zip', // default 'zip', also '7zip', 'tar', '.tar.gz', '.tar.bz2'
                'enableArchiving' => true, //default true; set false to disable archiving of sending files
                'password7zip' => 'password12345', //optional, only with type '7zip'

                'viewBothInOneAs' => false, //false is default, choice 'file' or 'text' - if you want glue text and context (global PHP vars) and send it by one message ('text') or one file ('file').
                // if viewBothInOneAs = false, you can choice view of text and context
                'viewMessageAs' => 'text', //also 'file' and false
                'viewContextAs' => 'file', //also 'text' and false


                //also if you want you can use your own archiver, which implements Victor78\Zipper\ZipperInterface
                'archiver' => function(){
                    return new Some\Namespace\SomeArchiver();
                },
             //USUAL OPTIONS for log target
                //for example
                'categories' => [
                    'yii\db\*',
                    'yii\web\HttpException:*',
                ],     
                'levels' => ['error', 'warning', 'trace', 'info'],
                'except' => [
                    'yii\web\HttpException:404',
                ],         
                'logVars' => ['_SERVER'],
            ]
        ]
    ]
];

How to create telegram bot

1. Message @botfather https://telegram.me/botfather with the following text: /newbot If you don't know how to message by username, click the search field on your Telegram app and type @botfather, where you should be able to initiate a conversation. Be careful not to send it to the wrong contact, because some users has similar usernames to botfather., _(*9)

   , _(*10)

2. @botfather replies with Alright, a new bot. How are we going to call it? Please choose a name for your bot., _(*11)

3. Type whatever name you want for your bot., _(*12)

4. @botfather replies with Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot., _(*13)

5. Type whatever username you want for your bot, minimum 5 characters, and must end with bot. For example: telesample_bot, _(*14)

6. @botfather replies with:, _(*15)

   Done! Congratulations on your new bot. You will find it at
   telegram.me/telesample_bot. You can now add a description, about
   section and profile picture for your bot, see /help for a list of
   commands.
   
   Use this token to access the HTTP API:
   123456789:AAG90e14-0f8-40183D-18491dDE
   
   For a description of the Bot API, see this page:
   https://core.telegram.org/bots/api
   

7. Note down the 'token' mentioned above., _(*16)

8. Type /setprivacy to @botfather., _(*17)

   , _(*18)

9. @botfather replies with Choose a bot to change group messages settings., _(*19)

10. Type (or select) @telesample_bot (change to the username you set at step 5 above, but start it with @), _(*20)

11. @botfather replies with, _(*21)

    'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
    'Disable' - your bot will receive all messages that people send to groups.
    Current status is: ENABLED
    

12. Type (or select) Disable to let your bot receive all messages sent to a group. This step is up to you actually., _(*22)

13. @botfather replies with Success! The new status is: DISABLED. /help, _(*23)

How to take telegram chat id which will receive messages from the bot

Send the /my_id to telegram bot @get_id_bot or use the instruction., _(*24)

How to use

It is enough to configure component right, and it will work. To test yout configuration, add it, for example, to some controller:, _(*25)

Yii::info('INFO MESSAGE');
Yii::debug('DEBUG MESSAGE');
Yii::warning('WARNING MESSAGE');
Yii::error('ERROR MESSAGE');

//also you can try create catching of Exception, for example:
1/0;

Notes

For archiving MessengerTarget use yii2-zipper., _(*26)

• For zip type Zipper try to use console command zip or php zip extension, so one of them is required on server for zipping.
• For tar, tar.gz, tar.bz2 Zipper try to use GNU tar and BSD tar, so one ofo them is required on server for these ways of arching.
• For zipping by 7zip, the 7za utiliy is required on server.

Установка

Предпочтительный способ установки расширения через composer., _(*27)

Либо запуск из консоли, _(*28)

php composer.phar require --prefer-dist victor78/yii2-messenger-target:"~0.0.4"

либо в composer.json в секции required, _(*29)

"victor78/yii2-messenger-target": "~0.0.4"

Настройка

return [
    'components' => [
        'telegramPusher' => [
            'class' => 'Victor78\MessengerTarget\TelegramPusher',

            'recipients' => [
                //не один элемент не является обязательным, но необходим хотя бы один


                //все сообщения будут отправлены в следующие чаты:
                '*' => [
                    'telegram_chat_id_0', //id чата, например, id пользователя
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],

                //сообщения которые  инициированы Yii::error('some message') or Yii::info('some message', 'error')
                //или во время отлавливания исключения будет отправлены в данные чаты
                'error' => [
                    'telegram_chat_id_0', //id чата, например, id пользователя
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],
                //сообщения, которые инициированы Yii::warning('some message') или Yii::info('some message', 'warning')
                //будут отправлены в следующие чаты
                'warning' => [
                    'telegram_chat_id_0', //id чата, например, id пользователя
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],
                //сообщения, инициированные Yii::debug('some message') или Yii::info('some message', 'trace')
                //будут отправлены в следующие чаты
                'trace' => [
                    'telegram_chat_id_0', //id чата, например, id пользователя
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],                

                //сообщения, инициированные
                //Yii::info('info message', 'some_category_1')  или
                //Yii::debug('trace message', 'some_category_1') или
                //Yii::warning('warning message', 'some_category_1') или
                //Yii::error('error message', 'some_category_1')                
                // будут отправлены в данные чаты
                'some_category_1' => [
                    'telegram_chat_id_0', //id чата, например, id пользователя
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],               
                //сообщения, инициированные
                //Yii::info('info message', 'some_category_1')  или
                //Yii::debug('trace message', 'some_category_1') или
                //Yii::warning('warning message', 'some_category_1') или
                //Yii::error('error message', 'some_category_1')                
                // будут отправлены в данные чаты
                'some_category_2' => [
                    'telegram_chat_id_0', //id чата, например, id пользователя
                    'telegram_chat_id_1',
                    //...
                    'telegram_chat_id_N',
                ],

            ],
            // уровень или категория и соответствующий ей токен телеграм бота
            'tokens' => [
                //все элементы опциональны
                //'some_level_or_category' => 'telegram_bot_api_token'
               'info' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
               'error' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
               'warning' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
               'trace' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
               'some_category_1' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
               'some_categiry_2' => 'NNNNNNNNN:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
            ], 
        ]
    ],
    //....
    'log' => [
        'targets' => [
            [
            //СПЕЦИФИЧЕСКИЕ для Yii2MessengerTarget ОПЦИИ
                //обязательные свойства
                'class' => 'Victor78\MessengerTarget\MessengerTarget',
                'messenger' => 'telegramPusher', //имя сконфигурированного компонента мессенджера

                //необязательные свойства
                'archiverMethod' => 'zip', // по умолчанию 'zip', also '7zip', 'tar', '.tar.gz', '.tar.bz2'
                'enableArchiving' => true, //по умолчанию true; установить false для отключения архивации отправляемых файлов
                'password7zip' => 'password12345', //опционально, работает только с типом '7zip'

                'viewBothInOneAs' => false, //false по умолчанию, выбрать 'file' или 'text' если хотите объединить текст и контекст (глобальные переменные PHP) и отправить их одним сообщением ('text') или одним файлом ('file').
                // если viewBothInOneAs = false, вы можете выбрать вид текста и контекста 
                'viewMessageAs' => 'text', //ещё можно выбрать 'file' или false
                'viewContextAs' => 'file', //ещё можно выбрать 'text' или false


                //При необходимости вы можете использовать свой архиватор, который реализует Victor78\Zipper\ZipperInterface
                'archiver' => function(){
                    return new Some\Namespace\SomeArchiver();
                },
             //ОБЫЧНЫЕ ОПЦИИ для log target
                //любые обычные опции, например
                'categories' => [
                    'yii\db\*',
                    'yii\web\HttpException:*',
                ],     
                'levels' => ['error', 'warning', 'trace', 'info'],
                'except' => [
                    'yii\web\HttpException:404',
                ],         
                'logVars' => ['_SERVER'],
            ]
        ]
    ]
];

Как создать телеграм бота

1. Напишите боту @botfather https://telegram.me/botfather следующий текст (команду): /newbot Если вы не в курсе как отправить сообщение пользователю по его username, кликните по поиску вашего приложения Телеграм и наберите @botfather, где вы получите возможность начать переписку с данным пользователем (в данном случае - ботом). Будьте внимательны, поскольку некоторые пользователи используют схожий c botfather username., _(*30)

   , _(*31)

2. @botfather ответит Alright, a new bot. How are we going to call it? Please choose a name for your bot., _(*32)

3. Отправьте сообщение с именем бота в ответ., _(*33)

4. @botfather ответит Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot., _(*34)

5. Отправьте в ответе username для бота - оно должно быть длинее 5 символов, заканчиваться на bot. Например: telesample_bot, _(*35)

6. @botfather ответит:, _(*36)

   Done! Congratulations on your new bot. You will find it at
   telegram.me/telesample_bot. You can now add a description, about
   section and profile picture for your bot, see /help for a list of
   commands.
   
   Use this token to access the HTTP API:
   123456789:AAG90e14-0f8-40183D-18491dDE
   
   For a description of the Bot API, see this page:
   https://core.telegram.org/bots/api
   

7. Сохраните токен., _(*37)

8. Отправьте боту @botfather сообщение /setprivacy., _(*38)

   , _(*39)

9. @botfather ответит Choose a bot to change group messages settings., _(*40)

10. Наберите (или выберите) вашего бота @telesample_bot (выберите по username вашего бота), _(*41)

11. @botfather ответит, _(*42)

    'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
    'Disable' - your bot will receive all messages that people send to groups.
    Current status is: ENABLED
    

12. Наберите (или выберите) Disable чтобы позволить вашему боту работать у группах., _(*43)

13. @botfather ответит Success! The new status is: DISABLED. /help, _(*44)

Как получить id чата (id пользователя), который будет получать сообщения от бота

Отправьте /my_id телеграм боту @get_id_bot или используйте инструкцию., _(*45)

Как использовать

Достаточно настроить компонент верно, и логирование через мессенджер будет работать. Протестировать верно ли настроено логирование можно добавив следующий код, например, в контроллер:, _(*46)

Yii::info('INFO MESSAGE');
Yii::debug('DEBUG MESSAGE');
Yii::warning('WARNING MESSAGE');
Yii::error('ERROR MESSAGE');

//также можно можно инициировать исключение, например:
1/0;

Замечания

Для архивации файлов MessengerTarget использует yii2-zipper., _(*47)

• Для архивирования в чистый zip используется утилита zip или расширение PHP для zip, так что или утилита, или расширение должны быть установлены на сервере для упавки и разупаковки zip.
• Для tar, tar.gz, tar.bz2 Zipper пытается использовать GNU tar или BSD tar, один из них должен быть установлен на сервере для этих типов архивов.
• Для упаковки/разупаковки zip при помощи 7zip, на сервере должа быть установлена утилита 7za.