rocketfellows/ms-teams-webhook-message-sender

v1.0.0 2024-03-17 13:51 UTC

Requires

• php: >=7.4
• guzzlehttp/guzzle: ^7.8

Requires (Dev)

• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^8.5
• roave/security-advisories: dev-latest
• squizlabs/php_codesniffer: 3.6.2

MIT

• Arslan Imamutdinov

README

This package is designed for sending messages to Microsoft Teams (MS Teams) channels using webhooks (incoming webhook or connector). For more information about sending messages to MS Teams channels using web hooks see https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using?tabs=cURL.

Installation.

composer require rocketfellows/ms-teams-webhook-message-sender

Dependencies.

Current implementation dependencies:

• guzzle client - https://github.com/guzzle/guzzle - using for http request to webhook.

MS Teams webhook message sender description.

Basic package types.

Connector.

rocketfellows\MSTeamsWebhookMessageSender\configs\Connector - a class that encapsulates the connection configuration for sending a message.

Class description:

• incomingWebhookUrl - string - link to a webhook (connector) for sending a message;
• create - static function - static factory function that returns a value of type Connector;
• getIncomingWebhookUrl - function - getter that returns the value of the incomingWebhookUrl attribute.

Message.

rocketfellows\MSTeamsWebhookMessageSender\models\Message - a class that encapsulates message data to be sent via a webhook and implements the JsonSerializable interface.

Class description:

• text - string - message text to send;
• title - string | null - message title to send;
• create - static function - static factory function returning a value of type Message;
• convertToJson - function - function, returns a representation of a Message type value as a json string;
• jsonSerialize - function - implementation of the JsonSerializable interface;
• getText - function - getter returning text attribute value;
• getTitle - function - getter returning title attribute value.

Interfaces.

MSTeamsWebhookMessageSenderInterface.

rocketfellows\MSTeamsWebhookMessageSender\MSTeamsWebhookMessageSenderInterface - interface for sending a message via a webhook uses a Connector type value as a connection, and a Message type value as a message.

public function sendMessage(Connector $connector, Message $message): void;

Interface exceptions:

• EmptyIncomingWebhookUrlException - thrown if the link to the webhook is an empty string.
• InvalidIncomingWebhookUrlException - thrown if the link to the webhook is not valid (for example, the link is not an url).
• EmptyMessageException - thrown if the message text is an empty string.
• ConnectorException - thrown if an error occurred when sending a message (for example, if the HTTP response code is not 200).

Usage examples.

Send message with title:

$sender->sendMessage(Connector::create(INCOMING_WEBHOOK_URL), Message::create('Hello world!', 'Hello!'));

Result:

Send message without title:

$sender->sendMessage(Connector::create(INCOMING_WEBHOOK_URL), Message::create('Hello world!'));

Result:

MSTeamsWebhookTextSenderInterface.

rocketfellows\MSTeamsWebhookMessageSender\MSTeamsWebhookTextSenderInterface - interface for sending a message via a webhook uses a value of type Connector as a connection, and a value of type string (message text) as a message.

public function sendText(Connector $connector, string $text): void;

Interface exceptions:

• EmptyIncomingWebhookUrlException - thrown if the link to the webhook is an empty string.
• InvalidIncomingWebhookUrlException - thrown if the link to the webhook is not valid (for example, the link is not an url).
• EmptyMessageException - thrown if the message text is an empty string.
• ConnectorException - thrown if an error occurred when sending a message (for example, if the HTTP response code is not 200).

Usage examples.

Send text:

$sender->sendText(Connector::create(INCOMING_WEBHOOK_URL), 'Hello world!');

Result:

MSTeamsWebhookArrayMessageSenderInterface.

rocketfellows\MSTeamsWebhookMessageSender\MSTeamsWebhookArrayMessageSenderInterface - interface for sending a message via a webhook uses a Connector type value as a connection, and an array type value as a message.

public function sendMessageFromArray(Connector $connector, array $messageData): void;

Interface exceptions:

• EmptyIncomingWebhookUrlException - thrown if the link to the webhook is an empty string.
• InvalidIncomingWebhookUrlException - thrown if the link to the webhook is not valid (for example, the link is not an url).
• EmptyMessageDataException - thrown if the array with message data is empty.
• ConnectorException - thrown if an error occurred when sending a message (for example, if the HTTP response code is not 200).

Usage examples.

Send message with title:

$sender->sendMessageFromArray(
    Connector::create(INCOMING_WEBHOOK_URL),
    [
        'text' => 'Hello world!',
        'title' => 'Hello!',
    ]
);

Result:

Send message without title:

$sender->sendMessageFromArray(
    Connector::create(INCOMING_WEBHOOK_URL),
    [
        'text' => 'Hello world!',
    ]
);

Result:

Send message with section:

$sender->sendMessageFromArray(
    Connector::create(INCOMING_WEBHOOK_URL),
    [
        'text' => 'Hello world!',
        'sections' => [
            [
                "activityTitle" => "Larry Bryant created a new task",
                "activitySubtitle" => "On Project Tango",
                "activityImage" => "https://adaptivecards.io/content/cats/3.png",
                "facts" => [
                    [
                        "name" => "Assigned to",
                        "value" => "Unassigned",
                    ],
                    [
                        "name" => "Due date",
                        "value" => "Mon May 01 2017 17:07:18 GMT-0700 (Pacific Daylight Time)"
                    ],
                    [
                        "name" => "Status",
                        "value" => "Not started"
                    ]
                ],
                "markdown" => true,
            ]
        ],
    ]
);

Result:

MSTeamsWebhookJsonMessageSenderInterface.

rocketfellows\MSTeamsWebhookMessageSender\MSTeamsWebhookJsonMessageSenderInterface - interface for sending a message via a webhook uses a value of type Connector as a connection, and a value of type string (a json string with message data) as a message.

public function sendJsonMessage(Connector $connector, string $jsonMessage): void;

Interface exceptions:

• EmptyIncomingWebhookUrlException - thrown if the link to the webhook is an empty string.
• InvalidIncomingWebhookUrlException - thrown if the link to the webhook is not valid (for example, the link is not an url).
• EmptyMessageDataException - thrown if the array with message data is empty.
• InvalidJsonMessageException - thrown if the json string with the message data is not valid (not valid from the point of view of the json format).
• ConnectorException - thrown if an error occurred when sending a message (for example, if the HTTP response code is not 200).

Usage examples.

Send message with title:

$sender->sendJsonMessage(
    Connector::create(INCOMING_WEBHOOK_URL),
    '{"text": "Hello world!", "title": "Hello!"}'
);

Result:

Send message without title:

$sender->sendJsonMessage(
    Connector::create(INCOMING_WEBHOOK_URL),
    '{"text": "Hello world!"}'
);

Result:

Send message with sections:

$sender->sendJsonMessage(
    Connector::create(INCOMING_WEBHOOK_URL),
    '{
        "text": "Hello world!",
        "sections": [
            {
                "activityTitle": "Larry Bryant created a new task",
                "activitySubtitle": "On Project Tango",
                "activityImage": "https://adaptivecards.io/content/cats/3.png",
                "facts": [
                    {
                        "name": "Assigned to",
                        "value": "Unassigned"
                    },
                    {
                        "name": "Due date",
                        "value": "Mon May 01 2017 17:07:18 GMT-0700 (Pacific Daylight Time)"
                    },
                    {
                        "name": "Status",
                        "value": "Not started"
                    }
                ],
                "markdown": true
            }
        ]
    }'
);

Result:

Interfaces implementation.

MSTeamsWebhookMessageSender.

rocketfellows\MSTeamsWebhookMessageSender\senders\MSTeamsWebhookMessageSender - service for sending messages via a webhook.

Sender implements the following interfaces:

• rocketfellows\MSTeamsWebhookMessageSender\MSTeamsWebhookMessageSenderInterface;
• rocketfellows\MSTeamsWebhookMessageSender\MSTeamsWebhookTextSenderInterface;
• rocketfellows\MSTeamsWebhookMessageSender\MSTeamsWebhookArrayMessageSenderInterface;
• rocketfellows\MSTeamsWebhookMessageSender\MSTeamsWebhookJsonMessageSenderInterface.

GuzzleHttp Client is used to send a request with a message.

Usage examples.

Sending a Message without a title:

$sender = new MSTeamsWebhookMessageSender(new \GuzzleHttp\Client());
$sender->sendMessage(Connector::create(INCOMING_WEBHOOK_URL), Message::create('Hello world!'));

Result:

Sending a Message with a title:

$sender = new MSTeamsWebhookMessageSender(new \GuzzleHttp\Client());
$sender->sendMessage(
    Connector::create(INCOMING_WEBHOOK_URL),
    Message::create('Hello world!', 'Hello!')
);

Result:

Sending a message as a string:

$sender = new MSTeamsWebhookMessageSender(new \GuzzleHttp\Client());
$sender->sendText(
    Connector::create(INCOMING_WEBHOOK_URL),
    'Hello world!'
);

Result:

Sending a message as an array:

$sender = new MSTeamsWebhookMessageSender(new \GuzzleHttp\Client());
$sender->sendMessageFromArray(
    Connector::create(INCOMING_WEBHOOK_URL),
    [
	    'title' => 'Message title',
        'text' => 'Hello world!',
    ]
);

Result:

Sending a message as a json string:

$sender = new MSTeamsWebhookMessageSender(new \GuzzleHttp\Client());
$sender->sendJsonMessage(
    Connector::create(INCOMING_WEBHOOK_URL),
    '{"title": "Message title", "text": "Hello world!"}'
);

Result:

Contributing.

Welcome to pull requests. If there is a major changes, first please open an issue for discussion.

Please make sure to update tests as appropriate.