README

A PHP package that defines custom Monolog handler to send Microsoft Teams notifications with an Incoming Webhook. The package aims to provide global messaging & log system that uses Microsoft Teams "MessageCard" notification and uses Monolog logging library.

Features

• Monolog wiring with Microsoft Teams channel
• Application error notifying
• Simple messaging

Install

$ composer require bitbirddev/microsoft-teams-monolog-handler

Please consider running composer suggest command to install required and missing dependencies related to framework you use (ex. Symfony):

$ composer suggest
bitbirddev/microsoft-teams-monolog-handler suggests:
 - symfony/monolog-bundle: The MonologBundle provides integration of the Monolog library into the Symfony framework.

Microsoft Teams Webhook setting

Follow these steps to set up new Webhook:

• In Microsoft Teams, choose More options (⋯) next to the channel name and then choose 'Connectors'
• Find in the list of Connectors the 'Incoming Webhook' option, and choose 'Add'
• Provide required information for the new Webhook
• Copy the Webhook url - that information will be used to configure the package with MICROSOFT_TEAMS_WEBHOOK_URL

Symfony configuration

Place the code below in .env file:

###> bitbirddev/microsoft-teams-monolog-handler ###
MICROSOFT_TEAMS_WEBHOOK_URL=webhook_url (without https://)
###< bitbirddev/microsoft-teams-monolog-handler ###

Register MicrosoftTeamsMonologHandler.php as a new service with the code below:

// config\services.yaml

services:
    ...

    # MICROSOFT TEAMS MONOLOG HANDLER
+    ms_teams_monolog_handler:
+        class: bitbirddev\MicrosoftTeamsNotifier\Handler\MicrosoftTeamsHandler
+        arguments:
+            $webhookDsn: '%https://env(MICROSOFT_TEAMS_WEBHOOK_URL)%'
+            $level: 'error'
+            $title: 'Message title'
+            $subject: 'Message subject'
+            $emoji:  '&#x1F6A8'
+            $color: '#fd0404'
+            $format: '[%%datetime%%] %%channel%%.%%level_name%%: %%message%%'

$webhookDsn:
Microsoft Teams webhook url

$level:
the minimum level for handler to be triggered and the message be logged in the channel (Monolog/Logger class: ‘error’ = 400)

$title (nullable):
title of Microsoft Teams Message

$subject (nullable):
subject of Microsoft Teams Message

$emoji (nullable):
emoji of Microsoft Teams Message (displayed next to the message title). Value needs to reflect the pattern: ‘&#x<EMOJI_HEX_CODE>’

$color (nullable):
hexadecimal color value for Message Card color theme

$format (nullable):
every handler uses a Formatter to format the record before logging it. This attribute can be set to overwrite default log message (available options: %datetime% | %extra.token% | %channel% | %level_name% | %message%).

Modify your Monolog settings that will point from now to the new handler:

// config\packages\dev\monolog.yaml
// config\packages\prod\monolog.yaml

monolog:
    handlers:
        ...

        # MICROSOFT TEAMS HANDLER
+        teams:
+            type: service
+            id: ms_teams_monolog_handler

type:
handler type (in our case this references custom notifier service)

id:
notifier service class \bitbirddev\MicrosoftTeamsNotifier\LogMonolog

Laravel configuration

Place the code below in .env file:

###> bitbirddev/microsoft-teams-monolog-handler ###
MICROSOFT_TEAMS_WEBHOOK_URL=webhook_url (without https://)
###< bitbirddev/microsoft-teams-monolog-handler ###

Modify your Monolog logging settings that will point to the new handler:

Att: definition of ALL parameters is compulsory - please use NULL value for attributes you want to skip.

// config\logging.php

<?php

use Monolog\Handler\NullHandler;
use Monolog\Handler\StreamHandler;
use Monolog\Handler\SyslogUdpHandler;

return [
    'channels' => [
        'stack' => [
            'driver' => 'stack',
-            'channels' => ['single'],
+            'channels' => ['single', 'custom'],
            'ignore_exceptions' => false
        ],

         # MICROSOFT TEAMS MONOLOG HANDLER
+       'custom' => [
+            'driver' => 'custom',
+            'via' => \bitbirddev\MicrosoftTeamsNotifier\LogMonolog::class,
+            'webhookDsn' => 'https://env('MICROSOFT_TEAMS_WEBHOOK_URL)',
+            'level'  => env('LOG_LEVEL', 'debug'), // or simply 'debug'
+            'title'  => 'Message Title', // can be NULL
+            'subject'  => 'Message Subject', // can be NULL
+            'emoji'  => '&#x1F3C1', // can be NULL
+            'color'  => '#fd0404', // can be NULL
+            'format' => '[%datetime%] %channel%.%level_name%: %message%' // can be NULL
+        ],

...

driver:
is a crucial part of each channel that defines how and where the log message is recorded. The ‘custom’ driver calls a specified factory to create a channel.

via:
factory class which will be invoked to create the Monolog instance

webhookDsn:
Microsoft Teams webhook url

level:
the minimum level for handler to be triggered and the message be logged in the channel (Monolog/Logger class: ‘debug’ = 100)

title (nullable):
title of Microsoft Teams Message

subject (nullable):
subject of Microsoft Teams Message

emoji (nullable):
emoji of Microsoft Teams Message (displayed next to the message title). Value needs to reflect the pattern: ‘&#x<EMOJI_HEX_CODE>’

color (nullable):
hexadecimal color value for Message Card color theme

format (nullable):
message template - available options: %datetime% | %extra.token% | %channel% | %level_name% | %message%

Usage

Correctly configured service in Symfony/Laravel will raise Logs in Microsoft Teams automatically accordingly to level assigned to.

Symfony - manual messaging

// LoggerInterface $logger
$logger->info('Info message with custom Handler');
$logger->error('Error message with custom Handler');

Laravel - manual messaging

// Illuminate\Support\Facades\Log
Log::channel('custom')->info('Info message with custom Handler');
Log::channel('custom')->error('Error message with custom Handler');

License

The code is available under the MIT license. See the LICENSE file for more info.