README

Megaphone 是一个基于 Laravel Livewire 的组件，它利用 Laravel 内置的通知系统，允许您向应用程序添加“铃铛图标通知系统”。

Megaphone 还附带一个管理表单组件，允许您一次性向所有用户发送通知。非常适合宣布新功能或计划维护！

演示

在开始使用 Megaphone 之前，您可以查看并尝试 Bell Icon 组件和管理组件的演示。除了对管理组件进行了一些小的样式调整以更好地适应布局外，所有内容都是“开箱即用”，安装 Megaphone 时将保持原样。

从 1.x 升级

Megaphone 已更新以支持 Livewire 3。这也意味着 PHP 要求已更新以匹配 Livewire 3 的要求，这意味着您需要运行 PHP 8.1 或更高版本（PHP 7.4 和 8.0 不再受支持）。然后请确保您遵循Livewire 升级指南。

在终端运行以下命令，将 Megaphone 的要求更新到 2.*。

    composer require mbarlow/megaphone "^2.0"

AlpineJS

如果您之前专门为了 Megaphone 包含了 AlpineJS，那么现在您可以将其从 JS 包含中删除，因为现在它已包含在 Livewire 中。

模板更改

如果您正在使用管理组件，并且已将 Megaphone 视图发布到资源文件夹中，您可能希望进行以下手动更改。

所有更改都是在 create-announcement.blade.php 中进行的，如果已发布，应位于 resources/views/vendor/megaphone/admin/create-announcement.blade.php。

找到 wire:model="type" 并将其替换为 wire:model.live="type"。

找到所有 wire:model.lazy 实例并将其替换为 wire:model.blur。

安装

有关 Megaphone 2 版本的 Livewire 版本，请参阅 Megaphone 的 1.x 版本和1.x 分支。

只需通过 composer 在您的 Laravel 应用中引入此包。

composer require mbarlow/megaphone

如果您尚未在应用程序中使用 Laravel Livewire，Megaphone 应通过其依赖关系包含该包。Composer 安装完成后，请确保您已运行Livewire 安装步骤。

安装 Livewire 后，如果您尚未安装，请确保Laravel 数据库通知已安装到您的应用程序中。

php artisan notifications:table
 
php artisan migrate

这将创建用于存储通知的数据库表。接下来，请确保您的 User 模型（或相关的替代模型）已添加了Laravel 文档中提到的 notifiable 特性，并添加 Megaphone 提供的 HasMegaphone 特性。

<?php
 
namespace App\Models;
 
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use MBarlow\Megaphone\HasMegaphone;
 
class User extends Authenticatable
{
    use Notifiable;
    use HasMegaphone;
}

最后，发布 Megaphone 资产。这应会发布配置文件以及模板和样式表。您可以在 resources/views/vendor/megaphone 中找到已发布的模板。

php artisan vendor:publish --provider="MBarlow\Megaphone\MegaphoneServiceProvider"

如果您不是使用位于 App\Models\User 的默认用户模型，您需要修改 megaphone.php 配置文件中定义的 model 属性的值。只需将值更改为您的 User 模型的路径。

使用 Megaphone

要开始使用扩音器，请将Megaphone Livewire组件拖放到您的模板中。

<livewire:megaphone />

这将渲染一个铃铛图标，图标放置的位置。点击后，将在屏幕右侧出现一个静态侧边栏，显示用户的所有现有和新通知。

样式

默认情况下，Megaphone使用TailwindCSS来样式化铃铛图标和通知侧边栏。如果您没有使用Tailwind，您可能需要将Megaphone CSS包含到您的模板中。将以下blade指令添加到您的站点<head></head>部分。

@megaphoneStyles

如果您正在使用TailwindCSS，请确保将Megaphone视图添加到任何Tailwind配置中，以确保正确编译类。

如果您希望重新编译Megaphone样式表，请确保您已安装node和npm，并运行npm install。然后，根据Larave Mix文档运行npx mix。

发送通知

默认情况下，Megaphone只会加载在Megaphone配置文件中注册的通知。随Megaphone一起发货的通知将在config('megaphone.types')中。这将与config('megaphone.customTypes')的键值合并，以创建支持的通知列表。

这意味着，您可以使用Laravel通知系统处理系统其他部分，而它们不会出现在Megaphone通知列表中。

要发送Megaphone通知，请实例化一个新的通知，该通知扩展自MBarlow\Megaphone\Types\BaseAnnouncement。Megaphone提供了3个默认类型，分别是MBarlow\Megaphone\Types\General、MBarlow\Megaphone\Types\Important和MBarlow\Megaphone\Types\NewFeature。

$notification = new \MBarlow\Megaphone\Types\Important(
    'Expected Downtime!', // Notification Title
    'We are expecting some downtime today at around 15:00 UTC for some planned maintenance. Read more on a blog post!', // Notification Body
    'https://example.com/link', // Optional: URL. Megaphone will add a link to this URL within the Notification display.
    'Read More...' // Optional: Link Text. The text that will be shown on the link button.
);

现在，按照Laravel文档中的说明，简单地将通知发送给所需用户。

$user = \App\Models\User::find(1);

$user->notify($notification);

下次用户ID 1访问您的应用程序时，他们的铃铛图标将显示一个带有“1”的红色指示器，表示有1条新的未读通知。

自定义通知

如前所述，您可以向Megaphone添加自己的通知类型。为此，首先在您的应用程序中创建一个新的类，并确保它扩展自MBarlow\Megaphone\Types\BaseAnnouncement，例如

<?php

namespace App\Megaphone;

use MBarlow\Megaphone\Types\BaseAnnouncement;

class MyCustomNotification extends BaseAnnouncement
{
}

接下来，您需要创建Megaphone应如何渲染该通知的视图文件。为了帮助您开始，您可以使用General、Important和New Feature通知使用的基模板。例如，在resources/views/megaphone/my-custom-notification.blade.php中创建一个新的视图。

@include('megaphone::types.base', ['icon' => 'ICON SVG HERE'])

简单地在blade包含参数数组中添加一个与您的通知相关的SVG图标，然后您就完成了。

最后，您需要告诉Megaphone有关此通知的信息。打开Megaphone配置文件config/megaphone.php，找到customTypes属性。这应该是一个关联数组，其中通知类的FQDN作为键，视图的路径作为值。例如

    /*
     * Custom notification types specific to your App
     */
    'customTypes' => [
        /*
            Associative array in the format of
            \Namespace\To\Notification::class => 'path.to.view',
         */
        \App\Megaphone\MyCustomNotification::class => 'megaphone.my-custom-notification', 
    ],

现在，您可以触发通知，用户将通过他们的铃铛图标接收到它。

$notification = new \App\Megaphone\MyCustomNotification(
    'Hello World',
    'This is a custom notification, hope you like our app!'
);

$user = \App\Models\User::find(1);

$user->notify($notification);

管理员面板

到目前为止展示的使用方法非常适合自动流程，例如，让用户知道后台操作已完成，“您的文件已准备好下载”，“您的服务器设置完成”，等等。但有时您可能想大量发送通知。

您可能希望通知用户即将进行维护或新功能已推出。为了覆盖这些情况，Megaphone提供了一个管理员组件，该组件提供了一个表单，可以发送通知给所有用户。

要使用组件，请在管理员区域创建一个新的页面，或者创建一个密码保护的页面，只有您作为应用程序所有者可以访问，然后将此Livewire组件拖放到该页面。

<livewire:megaphone-admin></livewire:megaphone-admin>

访问您的页面，您将看到一个表单，首先选择通知类型，然后填写标题、正文、链接和链接文本。填写完所有内容后，点击发送即可将通知推送给所有用户。

该表单已使用TailwindCSS进行样式设计，如果看起来没有正确应用样式，请确保在显示管理员组件的页面中包含TailwindCSS。或者，视图文件将与其他Megaphone资源一起发布，因此您可以在resources/views/vendor/megaphone/admin/create-announcement.blade.php中自定义表单样式。

通知类型列表

默认情况下，通知类型列表是通过合并config('megaphone.types')中的默认通知数组和位于config('megaphone.customTypes')中的自定义类型数组的键值来创建的。

如果您添加了许多自定义类型，或者有一些系统通知不应从此类列表中选择，您可以在Megaphone配置中的adminTypeList属性内构建自己的类型列表。

只需创建一个数组，包含您希望在下拉列表中可用的所有通知类。

'adminTypeList' => [
    \MBarlow\Megaphone\Types\NewFeature::class,
    \App\Megaphone\MyCustomNotification::class,
],

此示例意味着只有默认的新功能通知和您的自定义通知将在下拉菜单中可用。

类型列表 - 通知名称

下拉菜单中显示的每个通知的名称是从所有Megaphone通知扩展的BaseAnnouncement类中的类名计算得出的。如果Megaphone无法正确计算自定义通知的名称，或者您希望在管理员组件类型列表中不同地标记它，您可以在您的通知中定义一个name()方法。Megaphone将使用此方法来显示标签。

<?php

namespace App\Megaphone;

use MBarlow\Megaphone\Types\BaseAnnouncement;

class MyCustomNotification extends BaseAnnouncement
{
    public static function name(): string
    {
        return 'Awesome Notification';
    }
}

清除旧通知

为了帮助保持您的数据库和用户通知的整洁，Megaphone还附带了一个控制台命令，可以添加到您应用的计划中，以清除旧通知。

只需将以下内容添加到您的Console/Kernal.php文件中的schedule()方法。

$schedule->command('megaphone:clear-announcements')->daily();

这将清除任何“已读”的、超过两周的Megaphone通知。这允许任何可能已经几周未登录的用户在通知被清除之前查看通知。

旧通知的两周时间限制是通过Megaphone配置文件config('megaphone.clearAfter')控制的。因此，如果您希望更改此截止点，只需更改此值以延长或缩短截止点。

更改可通知模型

由于通知可以通过Notifiable特性附加到任何模型，因此Megaphone也可以附加到任何模型，前提是这个模型也附加了Notifiable特性。

默认情况下，Megaphone假设您将将其附加到标准Laravel用户模型，并在加载通知时，它将尝试从请求对象中检索已登录用户的ID。

如果您希望将Megaphone附加到团队模型（例如），则更改已发布Megaphone配置文件megaphone.php中的model属性。

当渲染Megaphone组件时，您需要将可通知模型的ID传递给组件，以便Megaphone可以加载正确的通知。

<livewire:megaphone :notifiableId="$user->team->id"></livewire:megaphone>

测试

如果您想运行测试，请克隆出仓库。

    git clone git@github.com:mikebarlow/megaphone.git

切换到仓库的根目录并运行composer install以安装开发依赖项。

    cd megaphone
    composer install

在composer.json中定义了一个脚本，用于运行代码审查器和单元测试。

    composer run test

或者根据需要单独运行它们。

    ./vendor/bin/pest
    ./vendor/bin/phpcs --standard=PSR2 src

变更日志

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

贡献

有关详细信息，请参阅贡献指南。

许可证

MIT许可（MIT）。请参阅许可文件获取更多信息。

mbarlow / megaphone

维护者

详细信息