Microsoft Teams notifications with Monolog and custom Handler

Published in

Active Developement

5 min readMay 24, 2021

Microsoft Teams is one of the tools available on the market that delivers an excellent chat experiance to the end user. Which is great with Teams, is an easy connection with external apps based on incoming Webhooks system. Let’s try then to integrate the connector in a Symfony/Laravel application on the top of Monolog.

Why Monolog?

Monolog is well known in Symfony & Laravel ecosystem as a PHP logging library where each logger can be categorized and organised differently regarding the task it should cover.

Hidden Benefit

Using Monolog, we can raise not only a simple message to our chat mates, but also be notified about logs raised inside our app (commonly stored in .log files).

The problem

Before shouting ‘victory’, there is a master piece that needs to be placed in order to wire up Monolog and the app together — it’s called Handler.
Handler is a wrapper that triggers and executes tasks in relation to occured app event. Most of the time you will find the handler adapted to your needs. You can also create a custom one as we did for you.

The Handler

actived/microsoft-teams-notifier is a custom handler that is able to send messages, notify about the app logs and works with both Symfony and Laravel. Follow 3 installation steps to make it 🚀:

Install the composer dependency

$ composer require actived/microsoft-teams-notifier

Since version 1.1 of the package “monolog/monolog” dependency was integrated that makes Actived Microsoft Teams Notifier more flexible for global use. Please consider running composer suggest command to install required dependencies related to framework you use (ex. for Symfony you would need “symfony/monolog-bundler”).

$ composer suggest

2. Set up the environment (with the variables below — root/.env file) — Microsoft Teams Webhook url for the channel:

###> actived/microsoft-teams-notifier ###
ACTIVED_MS_TEAMS_DSN=webhook_dsn
###< actived/microsoft-teams-notifier ###

3. Register the Handler — this is the most complicated part and needs to be done accordingly to your framework (for all handlers available on the market setup should be pretty the same — learn more about the handler integration on github.com/actived/microsoft-teams-notifier) . Symfony & Laravel configurations should be as follow:

Symfony setup

actived_ms_teams_handler:
 class: Actived\MicrosoftTeamsNotifier\Handler\MicrosoftTeamsHandler
  arguments:
    $webhookDsn:   '%env(ACTIVED_MS_TEAMS_DSN)%' //#1
    $title: 'Message title' //#2
    $subject: 'Message Subject',//#3
    $emoji:  '&#x1F6A8' //#4
    $color: '#fd0404'//#5
    $format: '[%datetime%] %channel%.%level_name%: %message%' //#6-- Due to recently raised issue: 'You have requested a non-existent  -- parameter "datetime", probably you will need update $format 
-- params with double '%%' as below:
-- $format: '[%%datetime%%] %%channel%%.%%level_name%%:%%message%%'    $level: 'error' //#7

#1 ‘dsn’: Microsoft Teams webhook url
#2 ‘title’: title of Microsoft Teams Message
#3 ‘subject’: subject of Microsoft Teams Message
#4 ‘emoji’: emoji of Microsoft Teams Message (displayed next to the message title). Value needs to reflect the pattern: ‘&#x<EMOJI_HEX_CODE>’ :

emoji: ‘&#x1F6A8’

#5 ‘color’: hexadecimal color value for Message Card color theme
#6 ‘format’: 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%).
#7 ‘level’: the minimum level for handler to be triggered and the message be logged in the channel (Monolog/Logger class: ‘error’ = 400)

🔌 Wire up the service with Monolog — (your_environment/monolog.yaml)

monolog:
 handlers:
   teams:
   type:  service //#1
   id:    actived_ms_teams_handler //#2

#1 ‘type’: handler type (in our case this references custom notifier service)
#2 ‘id’: notifier service class \Actived\MicrosoftTeamsNotifier\LogMonolog

Laravel setup

Laravel setup is even easier 😄. Everything is handled in a single configuration file — config\logging.php.

❗️ In Laravel, definition of ALL below parameters is compulsory — please use NULL value for attributes you want to skip:

'custom' => [
  'driver' => 'custom',//#1
  'via'    => \Actived\MicrosoftTeamsNotifier\LogMonolog::class,//#2
  'dsn'    => env('ACTIVED_MS_TEAMS_DSN'),//#3
  'title'  => 'Message Title',//#4
  'subject' => 'Message Subject',//#5 
  'level'  => 'debug',//#6
  'emoji'  => '&#x1F3C1',//#7
  'color'  => '#fd0404',//#8
  'format' => '[%datetime%] %channel%.%level_name%: %message%'//#9
]

#1 ‘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.
#2 ‘via’: factory class which will be invoked to create the Monolog instance
#3 ‘dsn’: Microsoft Teams webhook url
#4 ‘title’: title of Microsoft Teams Message
#5 ‘subject’: subject of Microsoft Teams Message
#6 ‘level’: the minimum level for handler to be triggered and the message be logged in the channel (Monolog/Logger class: ‘debug’ = 100)
#7 ‘emoji’: emoji of Microsoft Teams Message (displayed next to the message title). Value needs to reflect the pattern: ‘&#x<EMOJI_HEX_CODE>’ :

emoji: ‘&#x1F3C1’

#8 ‘color’: hexadecimal color value for Message Card color theme
#9 ‘format’: 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%).

Result — custom log message

Congratulations 🎉, you have just defined your first custom messaging module!

Usage

Symfony setup

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

Laravel setup

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