README

此包使您能够使用Laravel 10和11轻松通过Webex发送通知。

/**
 * Get the Webex Message representation of the notification.
 *
 * @return \NotificationChannels\Webex\WebexMessage
 *
 * @throws \NotificationChannels\Webex\Exceptions\CouldNotCreateNotification
 */
public function toWebex(mixed $notifiable)
{
    return (new WebexMessage)
        ->text('The message, in plain text.')
        ->markdown('# The message, in Markdown format.')
        ->file(function (WebexMessageFile $file) {
            $file->path('https://www.webex.com/content/dam/wbx/global/images/webex-favicon.png');
        });
}

内容

安装
- 使用Composer安装此包
- 添加Webex的服务配置
用法
- 格式化Webex通知
- 路由Webex通知
可用方法
变更日志
测试
安全
贡献
致谢
许可证

安装

要使用此包，您需要将其作为依赖项添加到您的项目中，并配置必要的设置。

使用Composer安装此包

使用Composer轻松引入和管理Webex通知包

composer require laravel-notification-channels/webex

添加Webex的服务配置

您还需要将Webex服务配置添加到应用程序中。为此，编辑config/services.php文件，并添加以下内容，或者如果已存在webex键，则合并以下内容：

'webex' => [
    'notification_channel_url' => env('WEBEX_NOTIFICATION_CHANNEL_URL', 'https://webexapis.com/v1/messages'),
    'notification_channel_id' => env('WEBEX_NOTIFICATION_CHANNEL_ID'),
    'notification_channel_token' => env('WEBEX_NOTIFICATION_CHANNEL_TOKEN')
],

使用WEBEX_NOTIFICATION_CHANNEL_ID和WEBEX_NOTIFICATION_CHANNEL_TOKEN 环境变量来定义您的Webex ID和令牌。获取这些值的一种方法是通过创建一个新的Webex机器人。

用法

如果您是Laravel通知的新手，我强烈建议您阅读官方文档，该文档介绍了生成和发送通知的基本知识。下面的指南假定您已成功生成一个带有via方法的通知类，其返回值包括'webex'或NotificationChannels\Webex\WebexChannel::class。例如

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Notifications\Notification;
use NotificationChannels\Webex\WebexChannel;

class InvoicePaid extends Notification
{
    use Queueable;

    // ...

    /**
     * Get the notification's delivery channels.
     */
    public function via(mixed $notifiable): array
    {
        return [WebexChannel::class];
    }

    // ...
}

要在Webex上发送通知，请在通知类上定义一个toWebex方法，并在可通知实体上定义一个routeNotificationForWebex方法。以下步骤将在下面讨论。

格式化Webex通知

如果通知支持作为Webex消息发送，您应该在通知类上定义一个toWebex方法。此方法将接收一个$notifiable实体，并应返回一个\NotificationChannels\Webex\WebexMessage实例。Webex消息可以包含文本内容以及最多一个文件或一个附件（用于按钮和卡片）。

纯文本消息

让我们看看一个基本的toWebex示例，我们可以将其添加到上面的InvoicePaid类中。

public function toWebex(mixed $notifiable): WebexMessage
{
    return (new WebexMessage)
        ->text('Invoice Paid!');
}

富文本消息

通过markdown方法使用Markdown标记语言格式化发送丰富文本通知消息。

public function toWebex(mixed $notifiable): WebexMessage
{
    return (new WebexMessage)
        ->markdown('# Invoice Paid!');
}

回复父消息

通过parentId方法回复父消息并开始或推进线程。

public function toWebex(mixed $notifiable): WebexMessage
{
    $messageId = "Y2lzY29zcGFyazovL3VybjpURUFNOnVzLXdlc3QtMl9yL01FU1NBR0UvNGY0ZGExOTAtOGUyMy0xMWVjLTljZWQtNmZkZWE5MjMxNmNj"

    return (new WebexMessage)
        ->parentId($messageId)
        ->text("Invoice Paid!" . "\n"
               "No Further action required at this time");
}

包含文件

通知消息最多可以包含一个文件，您可以通过file辅助方法包含该文件。调用file方法时，应提供文件的路径。文件路径可以是本地的，也可以是“scheme://...”的形式，即对您的应用程序可访问。可选地，您还可以提供要在Webex客户端上显示的名称和MIME类型。

public function toWebex(mixed $notifiable): WebexMessage
{
    $filePath = 'storage/app/invoices/uwnQ0uAXzq.pdf';
    
    return (new WebexMessage)
        ->file(function (WebexMessageFile $file) use ($filePath){
            $file->path($filePath)          // required
                ->name('invoice.pdf')       // optional
                ->type('application/pdf');  // optional
        });
}

注意

同一消息中包含多个文件不受file辅助方法的支持。
同一消息中包含文件和附件不受file辅助方法的支持。
有关支持的MIME类型和文件大小限制，请参阅Webex HTTP API文档。

包含附件

通知消息最多可以包含一个附件，您可以通过attachment辅助方法包含该附件。调用attachment方法时，应提供附件的内容。附件内容必须是自适应卡的PHP数组表示形式。可选地，您还可以提供内容类型。

public function toWebex(mixed $notifiable): WebexMessage
{
    $invoicePaidCard = json_decode('{
        "type": "AdaptiveCard",
        "version": "1.0",
        "body": [
            {
                "type": "TextBlock",
                "text": "Invoice Paid!",
                "size": "large"
            }
        ],
        "actions": [
            {
                "type": "Action.OpenUrl",
                "url": "https://example.com/invoices/uwnQ0uAXzq.pdf",
                "title": "View Invoice"
            }
        ]
    }');

    return (new WebexMessage)
        ->attachment(function (WebexMessageAttachment $attachment) use ($invoicePaidCard) {
            $attachment->content($invoicePaidCard)                          // required
                ->contentType('application/vnd.microsoft.card.adaptive');   // optional
        });
}

注意

同一消息中包含多个附件不受attachment辅助方法的支持。
同一消息中包含附件和文件不受attachment辅助方法的支持。
有关支持的附件类型，请参阅Webex HTTP API文档。

房间/空间链接

要链接到房间/空间，请使用其Webex协议处理程序，例如webexteams://im?space=<space_id>。

public function toWebex(mixed $notifiable): WebexMessage
{
    return (new WebexMessage)
        ->markdown('We are in the webexteams://im?space=f58064a0-8e21-11ec-9d53-739134f9a8eb space.');
}

用户和群组提及

要在群组房间/空间中提及某人，请使用他们的注册Webex电子邮件地址或Webex HTTP API标识符，如下所示。

public function toWebex(mixed $notifiable): WebexMessage
{
    $mentionPersonEmail = 'baburao@example.com';
    
    return (new WebexMessage)
        ->markdown("Hello <@personEmail:$mentionPersonEmail|Babu Bhaiya>! Your invoice is ready for payment.");
}

public function toWebex(mixed $notifiable): WebexMessage
{
    $mentionPersonId = 'Y2lzY29zcGFyazovL3VzL1BFT1BMRS85OTRmYjAyZS04MWI1LTRmNDItYTllYy1iNzE2OGRlOWUzZjY';

    return (new WebexMessage)
        ->markdown("Hello <@personId:$mentionPersonId|Babu Bhaiya>! Your invoice is ready for payment.");
}

要在群组房间/空间中提及所有人，请使用<@all>标签。

public function toWebex(mixed $notifiable): WebexMessage
{
    return (new WebexMessage)
        ->markdown('Hello <@all>! An invoice is ready for payment.');
}

路由Webex通知

为了将Webex通知路由到正确的Webex用户或房间/空间，请在您的可通知实体上定义一个routeNotificationForWebex方法。这应该返回一个Webex注册的电子邮件地址或一个Webex HTTP API资源标识符，用于指定应将通知发送到的用户或房间/空间。

<?php
 
namespace App\Models;
 
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
 
class User extends Authenticatable
{
    use Notifiable;
 
    /**
     * Route notifications for the Webex channel.
     *
     * @param  \Illuminate\Notifications\Notification  $notification
     * @return string|null
     */
    public function routeNotificationForWebex($notification): string|null
    {
        if (!empty($this->email)) {             // a Webex registered email address
            return $this->email;
        } else if (!empty($this->personId)) {   // a Webex HTTP API resource identifier for a user
            return $this->personId;
        } else if (!empty($this->roomId)) {     // a Webex HTTP API resource identifier for a room/space
            return $this->roomId;
        }

        return null;                            // don't route notification for Webex channel
    }
}

可用方法

所有消息类都在\NotificationChannels\Webex命名空间下。

Webex消息方法

WebexMessage类的公共方法

text(string $content): WebexMessage：设置消息的纯文本内容并返回当前实例，其中$text属性已设置。
markdown(string $content): WebexMessage：设置消息的Markdown内容并返回当前实例，其中$markdown属性已设置。
parentId(string $id): WebexMessage：设置要回复的父消息。如果提供的Webex HTTP API资源标识符无效，则抛出CouldNotCreateNotification异常。返回当前实例，其中$parentId属性已更新。
file(Closure $callback): WebexMessage：向消息添加文件。如果已存在文件或附件，则抛出CouldNotCreateNotification异常。返回当前实例，其中$files属性已设置。
attachment(Closure $callback): WebexMessage：向消息添加附件。如果已存在附件或文件，则抛出CouldNotCreateNotification异常。返回当前实例，其中$attachments属性已设置。
to(string $recipient): WebexMessage: 设置消息的接收者。此方法自动确定接收者是一个个人/机器人（即直接1:1房间/空间）还是群组房间/空间。如果提供的接收者是一个有效的电子邮件地址，则设置$toPersonEmail。如果是有效的Webex HTTP API资源标识符，则为个人/机器人设置$toPersonId，为房间/空间设置$roomId。如果提供的接收者既不是电子邮件，也不是有效的Webex HTTP API资源标识符，则抛出CouldNotCreateNotification异常。返回设置了一个且仅有一个$toPersonEmail、$toPersonId或$roomId的当前实例。

Webex消息文件方法

WebexMessageAttachment类的公共方法

path(string $path): WebexMessageFile: 设置文件的路径，并返回具有设置$path属性的当前实例。
name(string $name): WebexMessageFile: 设置用户提供的文件名称，并返回具有可选$name属性的当前实例。
type(string $type): WebexMessageFile: 设置用户提供的文件MIME类型，并返回具有可选$type属性的当前实例。

Webex消息附件方法

WebexMessageFile类的公共方法

contentType(string $contentType): WebexMessageAttachment: 设置附件的内容类型，并返回具有设置$contentType属性的当前实例。
content(mixed $content): WebexMessageAttachment: 设置附件的内容，并返回具有设置$content属性的当前实例。

接口方法实现

此外，还有一些用于转换Webex消息实例的方法，这些方法用于内部创建请求有效负载以用于Webex HTTP API

toArray(): array: 将当前实例转换为适合multipart/form-data请求的数组；由WebexMessage、WebexMessageFile和WebexMessageAttachment三个类实现。
jsonSerialize(): array:: 将当前实例转换为适合application/json请求或传递给json_encode的数组；由WebexMessage和WebexMessageAttachment类实现。
toJson($options = 0): string: 使用PHP的json_encode函数将当前实例转换为JSON字符串，内部调用jsonSerialize以获取序列化数据。接受一个可选参数$options来指定JSON编码选项；由WebexMessage和WebexMessageAttachment类实现。

变更日志

请参阅变更日志以获取有关最近更改的更多信息。

测试

$ composer test

安全

如果您发现任何安全问题，请通过电子邮件ask@mrsinh.com报告，而不是使用问题跟踪器。

laravel-notification-channels / webex

维护者

详情