/laravel-teams-notification

Primary LanguagePHPMIT LicenseMIT

Laravel Teams Notification

Laravel Teams Notification is a package for sending notifications to Microsoft Teams using the "Post to a channel when a webhook request is received" workflow webhook. It supports sending normal messages, exception messages with trace, and messages with additional details or JSON blocks, following the JSON structure required by Microsoft Teams adaptive cards. The package also includes custom logging functionality for Laravel, making it easy to integrate with your existing Laravel applications and log important events directly to Microsoft Teams channels.

Image 2

Table of Contents

Features

  • Send Normal Messages: Send simple text notifications to Teams.
  • Send Messages with Additional Details: Include extra details in the notification.
  • Send Success Messages: Highlight successful operations with a green color.
  • Send Warning Messages: Indicate warnings with an orange color.
  • Send Error Messages: Report errors with a red color and optional stack trace.
  • Send Messages with JSON Blocks: Include formatted JSON data in the message.
  • Custom Logging: Log messages directly to Microsoft Teams using Laravel’s logging system.
  • Configurable Message Colors: Set custom colors for messages with predefined options.

Installation

To install the package, you need PHP 7.0 or higher and Laravel 5.5 or later. Use Composer:

composer require osa-eg/laravel-teams-notification

Then, add your Microsoft Teams webhook URL to your .env file:

TEAMS_WEBHOOK_URL=your_teams_webhook_url

Publishing Files

Config

To publish the config file included with this package to your Laravel project, run:

php artisan vendor:publish --tag=laravel-teams-notification-config

Usage

Sending a Normal Message

To send a normal message, use the sendMessage method:

use Osama\LaravelTeamsNotification\TeamsNotification;

$notification = new TeamsNotification();
$message = "System Notification";
$notification->sendMessage($message);

Sending a Normal Message with Additional Details and Color

To send a normal message with additional details, use the sendMessage method with the second parameter:

use Osama\LaravelTeamsNotification\TeamsNotification;

$notification = new TeamsNotification();
$message = "System Notification";
$details = [
    'Server' => 'Production',
    'Status' => 'Running',
    'Uptime' => '24 days'
];
$notification->sendMessage($message, $details);

Sending a Success Message

To send a success message, use the success method:

use Osama\LaravelTeamsNotification\TeamsNotification;

$notification = new TeamsNotification();
$message = "Operation completed successfully!";
$details = [
    'Duration' => '2 seconds',
    'Processed Items' => '150'
];
$notification->success()->sendMessage($message, $details);

Sending a Warning Message

To send a warning message, use the warning method:

use Osama\LaravelTeamsNotification\TeamsNotification;

$notification = new TeamsNotification();
$message = "Warning: High Memory Usage Detected";
$details = [
    'Memory Usage' => '95%',
    'Server' => 'Production'
];
$notification->warning()->sendMessage($message, $details);

Sending an Error Message with Trace and Default Attention Color

To send an error message with trace, use the error method and bindTrace method:

use Osama\LaravelTeamsNotification\TeamsNotification;

try {
    // Code that may throw an exception
} catch (\Exception $exception) {
    $notification = new TeamsNotification();
    $notification->bindTrace()->error()->sendException($exception);
}

Sending a Message with Array as JSON Block and Custom Color

To send a message with an array as a JSON block, use the sendJsonMessage method:

use Osama\LaravelTeamsNotification\TeamsNotification;

$notification = new TeamsNotification();
$message = "Data Update";
$data = [
    'user_id' => 12345,
    'action' => 'update',
    'status' => 'success',
    'timestamp' => date('Y-m-d H:i:s')
];
$notification->success()->sendJsonMessage($message, $data);

Custom Logging

The package also supports custom logging to Microsoft Teams. To set up custom logging, follow these steps:

  1. Configure Logging in Your Laravel Project:

    In config/logging.php, add the following configuration:

    'channels' => [
    // Other channels...

    'teams' => [
        'driver' => 'custom',
         'via' => \Osama\LaravelTeamsNotification\Logging\TeamsLoggingChannel::class,
         'webhook_url' => env('TEAMS_WEBHOOK_URL'),
     ],

  2. Use the Custom Log Channel:

    To log messages to Teams, use the teams log channel:

    Log::channel('teams')->info('This is an info message');
Log::channel('teams')->error('This is an error message');

Methods

  • setColor(string $color): Sets the color of the message. Valid colors are "default", "dark", "light", "accent", "good", "warning", "attention".
  • success(): Sets the message color to "good".
  • warning(): Sets the message color to "warning".
  • error(): Sets the message color to "attention".
  • sendMessage($message, array $details = []): Sends a normal message with additional details.
  • sendException(\Exception $exception): Sends an exception message with optional trace details.
  • bindTrace(): Includes the trace in the exception message.
  • sendJsonMessage($message, array $data): Sends a message with an array as a JSON block.

Learn More

For a detailed guide on integrating Microsoft Teams notifications with your Laravel application, check out my Medium article:

Streamlining Laravel Notifications with Microsoft Teams Workflow Integration

License

This package is open-sourced software licensed under the MIT license.


This README now includes a Table of Contents section that links to different parts of the document for easier navigation.