README

Laralerts

快速在您的后端设置一个或多个警报，并在前端渲染它们。

Laralerts 兼容任何前端框架，以更好地适应您的应用程序，而不是相反。

要求

• Laravel 8.x 或更高版本
• PHP 8.0 或更高版本。

对于旧版本的支持，请考虑赞助或捐赠以提供帮助。

安装

您可以通过 composer 安装此包

composer require darkghosthunter/laralerts

如果您在前端没有开始的地方，可以使用 Laravel Jetstream，或者走经典路线使用 Bootstrap，Bulma.io，UI kit，TailwindCSS 和 INK 等等。

用法

Laralerts 允许您在应用程序中设置一系列警报，并在几分钟内在前端渲染它们。

默认警报渲染器使用 Bootstrap 代码将每个警报转换为 Bootstrap Alerts。如果您不使用 Bootstrap，可以为您的特定框架 创建自己的。

快速入门

要设置前端中的警报，您可以使用 alert() 助手或 Alert Facade。使用它们的好地方是在发送浏览器响应之前，例如在您的 HTTP 控制器中。

如果您正在发送重定向，Laralerts 会自动闪现警报，以便下一个请求可以显示它。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Article;

class ArticleController extends Controller
{
    /**
     * Update the Article 
     * 
     * @param \Illuminate\Http\Request $request
     * @param \App\Article $article
     * @return \Illuminate\Http\Response
     */
    public function update(Request $request, Article $article)
    {
        $request->validate([
            'title' => 'required|string|max:255',
            'body' => 'required|string'
        ]);
        
        $article->fill($request)->save();
        
        alert('Your article has been updated!', 'success');
        
        return redirect()->action('ArticleController@edit', $article);
    }
}

alert() 助手接受 message 文本和警报的 类型。在上面的例子中，我们创建了一个 "success" 警报。

要在前端渲染它们，请使用 <x-laralerts /> Blade 组件，它将处理一切，您可以在任何想要放置的地方使用它。

<div class="header">
    <h1>Welcome to my site</h1>
    <x-laralerts />
</div>

如果至少有一个警报要渲染，上面的内容将被转换为适当的 HTML。

<div class="header">
    <h1>Welcome to my site</h1>
    <div class="alerts">
        <div class="alert alert-success" role="alert">
            Your article has been updated!
        </div>
    </div>
</div>

消息

使用 message() 方法添加警报内的文本。就是这样。

<?php

use DarkGhostHunter\Laralerts\Facades\Alert;

alert()->message('You are gonna love this! 😍')->types('success');

alert()->message('We will email you 📨 a copy!')->types('info');

<div class="alert alert-success" role="alert">
    You are gonna love this! 😍
</div>

<div class="alert alert-info" role="alert">
    We will email you 📨 a copy!
</div>

默认情况下，message() 方法会转义文本。如果您想要发送原始消息，应使用 raw()。

原始消息

由于 message() 方法为了安全起见会转义文本，您可以使用 raw() 方法输出原始字符串。这允许您在个性化消息中使用 HTML，例如添加一些 样式、链接或甚至脚本。

<?php

alert()->message('This is <strong>FUBAR</strong>.')->types('warning');

alert()->raw('But this is <strong>important</strong>.')->types('warning');

<div class="alert alert-warning" role="alert">
    This is &lt;strong&gt;FUBAR&lt;/strong&gt;.
</div>

<div class="alert alert-warning" role="alert">
    But this is <strong>important</strong>.
</div>

警告：不要使用 raw() 显示用户生成的内容。警告已发出.

警报类型

您可以通过名称设置警报 "类型"，只需使用 types() 方法设置即可。它还接受多个类型。

<?php

alert()->message('Your message was sent!')->types('primary');

alert()->message('There is an unread message.')->types('info', 'fade');

<div class="alert alert-primary" role="alert">
    Your message was sent!
</div>
<div class="alert alert-info fade" role="alert">
    There is an unread message.
</div>

类型只是自定义 CSS 类和 HTML 的别名，然后由渲染器转换为正确的代码。

渲染器接收类型列表并将其转换为相应的 CSS 类。默认的 Bootstrap 渲染器将每个未识别的类型设置为额外的 CSS 类。

本地化

要动态本地化消息，请使用 trans() 方法，它是 __() 助手的镜像。

<?php

alert()->trans('email.changed', ['email' => $email], 'es')->types('success');

<div class="alert alert-success" role="alert">
    ¡Tu email ha sido cambiado a "margarita@madrid.cl" con éxito!
</div>

您还可以使用与 trans_choice() 相同的参数使用 transChoice()。

<?php

alert()->transChoice('messages.apples', 1)->types('success');
alert()->transChoice('messages.apples', 10)->types('success');

<div class="alert alert-success" role="alert">
    ¡Ahora tienes 1 manzana! 
</div>

<div class="alert alert-success" role="alert">
    ¡Ahora tienes 10 manzanas! 
</div>

关闭

大多数前端框架都有可关闭的警报或通知，但需要添加多个类才能允许交互。您可以使用 dismiss() 设置警报为可关闭。

alert()->message('You can disregard this')->type('success')->dismiss();

如果您想改变主意，可以使用 dismiss(false)

alert()->message('You can disregard this')->type('success')->dismiss(false);

可关闭警报转换为代码的方式取决于渲染器本身。默认的 Bootstrap 渲染器会自动添加适当的 CSS 类和关闭按钮。

<div class="alert alert-success alert-dismissible fade show" role="alert">
  You can disregard this
  <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
</div>

条件警报

您也可以通过使用 when() 和 unless() 分别将条件评估为真或假来推送警报。进一步的方法调用将发送到空值。

<?php

use Illuminate\Support\Facades\Auth;

alert()->when(Auth::check())
    ->message('You are authenticated')
    ->types('success');

alert()->unless(Auth::user()->mailbox()->isNotEmpty())
       ->message('You have messages in your inbox')
       ->types('warning');

持久性警报

警报仅持续当前请求。在重定向时，这些将 闪入会话，因此它们在下一个请求（重定向目标）中可用。

要使任何警报持久，您可以使用带有标识警报的键的 persistAs() 方法。

alert()->message('Your disk size is almost full')->types('danger')->persistAs('disk.full');

设置持久性警报会替换具有相同键的任何先前的设置。

完成后，您可以直接从助手使用持久性警报的键删除持久性警报，使用 abandon()。如果找到持久性警报，它将返回 true，如果没有找到，则返回 false。例如，如果磁盘不再满，我们可以放弃之前的警报。

if ($disk->notFull()) {
    alert()->abandon('disk.full');
}

链接

设置警报的链接不必麻烦。您可以使用 to()、route()、action() 和 away() 简单地替换消息中花括号之间的字符串。

<?php

alert()->message('Remember, you can follow your order in your {dashboard}.')
    ->types('success')
    ->to('dashboard', '/dashboard/orders')

链接也可以在翻译的消息中工作，只要这些消息中有花括号的单词。

<?php
// You can see your package status in the {tracking}.

alert()->trans('user.dashboard.tracking.order', ['order' => $order->tracking_number])
    ->types('success')
    ->route('tracking', 'orders.tracking', ['order' => 45])

如果您有多个链接，可以将多个链接链接到消息。

<?php

alert()->trans('Your {product} is contained in this {order}.')
    ->types('success')
    ->action('product', [\App\Http\Controllers\Product::class, 'show'], ['product' => 180])
    ->to('order', '/dashboard/order/45')

链接字符串区分大小写，并替换所有相同的字符串出现。如果您不希望这样做，可以创建自己的渲染器。

标签

有时您可能需要在您的网站上的多个地方放置警报，如一个用于全局警报，另一个用于小型用户警报。标签可以用来过滤您想要渲染的警报。

您可以使用 tag() 方法设置警报的标签。

alert()->message('Maintenance is scheduled for tomorrow')
    ->type('warning')
    ->tag('user', 'admin')

使用 Laralerts 指令，您可以通过 :tags 插槽按标签名称筛选要渲染的警报。

<!-- Render the Alerts in the default list -->
<x-laralerts :tags="'default'" />

<!-- Here we will render alerts for users and admins. -->
<x-laralerts :tags="['user', 'admin']" />

配置

Laralerts 默认情况下与一些常见默认值一起使用，但如果您需要为您的特定应用程序提供一个更好的方法，您可以配置一些参数。首先，发布配置文件。

php artisan vendor:publish --provider="DarkGhostHunter\Laralerts\LaralertsServiceProvider" --tag="config"

让我们来检查配置数组，它相当简单

<?php 

return [
    'renderer' => 'bootstrap',
    'key' => '_alerts',
    'tags' => 'default',
];

渲染器

<?php 

return [
    'renderer' => 'bootstrap',
];

这选择用于将警报转换为 HTML 的渲染器。

此软件包包含 Bootstrap 5 渲染器，但您可以为其他前端框架如 Bulma.io、UI kit、TailwindCSS 和 INK 或您自己的自定义前端框架创建自己的渲染器。

会话键

<?php 

return [
    'key' => '_alerts',
];

当警报被闪存或持久化时，这些将通过一个给定的键存储在会话中，默认为 _alerts。如果您使用此键名用于其他事情，您可能想要更改它。

此键也用于 发送 JSON 警报。

默认标签列表

<?php 

return [
    'tags' => ['user', 'admin'],
];

这包含要在创建警报时注入到所有警报中的默认标签列表。如果您不使用 标签，您可以保留此设置。

渲染器

渲染器接收警报的集合，并将其转换为 HTML 字符串。这使得更换前端框架变得更容易，并在渲染 HTML 时提供更大的灵活性。

创建自定义渲染器

您可以使用 Renderer 合同创建自己的，并将其注册到 AppServiceProvider 中的 RendererManager 中。您可以将 BootstrapRenderer 作为起点。

<?php

use DarkGhostHunter\Laralerts\RendererManager;
use App\Alerts\Renderers\TailwindRenderer;

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot(RendererManager $alert)
{
    $alert->extend('tailwind', function ($app) {
        return new TailwindRenderer($app['blade.compiler']);
    });
}

然后，在您的配置文件中，将渲染器设置为已注册的渲染器。

// config/laralerts.php

return [
    'renderer' => 'tailwind'
    
    // ...
];

当您发布警报时，警报将使用您自己的自定义渲染器进行渲染。

<?php

alert()->message('Popping colors!')->types('primary');

<div class="notification type-primary">
    Popping colors!
</div> 

警报容器 HTML

当渲染器收到要渲染的警报时，它将调用一个“容器”视图，通过循环渲染所有警报。

例如，包含的 BootstrapRenderer 调用 laralerts::bootstrap.container。

@if($alerts->isNotEmpty())
    <div class="alerts">
        @each('laralerts::bootstrap.alert', $alerts, 'alert')
    </div>
@endif

您可能正在使用不同于 Bootstrap 5 的其他前端框架，或者您可能希望更改 HTML 以更好地适应您的应用程序设计。在任何情况下，您都可以覆盖 views/vendor/laralerts 中的视图文件。

• container.blade.php：包含所有警报的 HTML。
• alert.blade.php：单个警报的 HTML。

alert.blade.php 视图接收的变量由渲染器设置。对于包含的 Bootstrap 渲染器，这些是：

• $alert->message：要在警报内部显示的消息。
• $alert->classes：要应用到 Alert 上的 CSS 类。
• $alert->dismissible：一个布尔值，用于设置 Alert 是否可关闭。

正如你所猜想的，你可以发布视图并覆盖它们以适应你的需求。

php artisan vendor:publish --provider="DarkGhostHunter\Laralerts\LaralertsServiceProvider" --tag="views"

JSON Alerts

接收 JSON Alerts

有时你的应用程序可能通过这个包从外部服务接收 JSON Alert。你可以使用 fromJson() 方法快速将此 JSON 添加到应用程序的 Alert 中。

{
    "alert": {
        "message": "Email delivered",
        "types": [
            "success",
            "important"
        ],
        "dismissible": false
    }
}

alert()->fromJson($json);

只要 JSON 中有包含 Alert 中要包含的文本的 message 键，就可以这样工作。此外，你可以添加 types 和 dismiss 键来添加 Alert，之后还可以覆盖它们。

发送 JSON Alerts

这个库提供了一种方便的方法将 Alerts 添加到你的 JSON 响应中。这可以非常有用，例如将 Alerts 添加到发送到浏览器的每个响应中，比如与 Laravel Jetstream 结合使用。

只需简单地将 laralerts.json 中间件 添加到你的 api 路由中，或者如果你使用 Laravel Jetstream 或类似框架，可以作为 全局中间件。

当你向浏览器返回 JsonResponse 时，中间件将使用配置中定义的相同 会话键（默认为 _alerts）将 alert 作为 JSON 附加。它还接受 key 参数，用作替代，兼容于 点表示法。以下是一个示例

<?php

use Illuminate\Support\Facades\Route;

Route::group('api', function () {
    
    Route::post('create')->uses('UserController@create');
    Route::post('update')->uses('UserController@update');
    
})->middleware('laralerts.json:_status.alerts');

当你收到 JSON 响应时，你将看到 alert 被附加到你发出的任何键下。使用上面的示例，我们应该在 _status 键下看到 alerts 键

{
    "resource": "users",
    "url": "/v1/users",
    "_status": {
        "timestamp":  "2019-06-05T03:47:24Z",
        "action" : "created",
        "id": 648,
        "alerts": [
            {
                "message": "The user has been created!",
                "types" : ["success", "important"],
                "dismiss": true
            }
        ]
    }
}

如果你的键已经在 JSON 响应中存在，Laralerts 不会覆盖键值。请确保键永远不会出现在响应中。

测试

要测试是否生成了 alert，你可以使用 Alert::fake()，它像任何其他伪造服务一样工作。它返回一个伪造的 Alert Bag，其中包含所有生成的 alert 的副本，并公开一些方便的断言方法。

use \DarkGhostHunter\Laralerts\Facades\Alert;

public function test_alert_sent()
{
    $alerts = Alert::fake();
    
    $this->post('/comment', ['body' => 'cool'])->assertOk();
    
    $alerts->assertHasOne();
}

以下是一些可用的断言

断言特定的 alert

伪造的 Alert bag 允许使用 assertAlert() 构建条件，以检查具有特定属性的 alert 的存在（或不存在）。

一旦构建了条件，你可以使用 exists() 检查是否有任何 alert 匹配，或使用 missing() 检查没有 alert 应该匹配。

$bag->assertAlert()->withMessage('Hello world!')->exists();

$bag->assertAlert()->withTypes('danger')->dismissible()->missing();

或者，如果您期望匹配特定数量的警报，可以使用 count()，或者使用 unique() 来匹配单个警报。

$bag->assertAlert()->persisted()->count(2);

$bag->assertAlert()->notDismissible()->withTag('toast')->unique();

以下条件可用

安全

如果您发现任何与安全相关的问题，请通过电子邮件发送到 darkghosthunter@gmail.com，而不是使用问题跟踪器。

许可证

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