README

在您的后端设置多个警报，使用任何HTML在前端渲染它们。

alert('This is awesome! 😍', 'success')

<div class="alert alert-success" role="alert">
    This is awesome! 😍
</div>

成为赞助商

您的支持使我能够保持此包免费、更新和可维护。或者，您也可以 传播信息！

要求

Laravel 10 或更高版本

安装

您可以通过composer安装此包

composer require laragear/alerts

如果您的前端没有开始的东西，您可以使用 Laravel Jetstream，或者采用经典方式使用 Bootstrap，Bulma.io，UI kit，TailwindCSS 和 INK 等众多其他工具。

用法

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

默认渲染器使用 Bootstrap 5 样式将每个警报转换为警报。如果您使用 Tailwind CSS，您可以通过更改配置使用包含的Tailwind渲染器。或者，您可以为特定的框架创建自己的渲染器。

快速入门

要在前端设置警报，您可以使用更简洁的语法 alert() 辅助函数，或者使用 Alert 门面，具体取决于您的喜好。使用它们的好地方是在发送响应到浏览器之前，比如在您的HTTP控制器中。

如果您发送重定向，警报将神奇地闪现，以便下一个请求可以显示它们。

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 文本和警报的类型。在上面的示例中，我们创建了一个简单的“成功”警报。

要渲染前端的警报，请使用 <x-alerts-container /> Blade 组件，它将在任何您想要放置的地方处理这些操作。

<div class="header">
    <h1>Welcome to my site</h1>
    <x-alerts-container />
</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>

或者，您可以直接从 Alert 门面或 alert() 辅助函数使用 type($message) 语法。

use Laragear\Alerts\Facades\Alert;

alert()->success('This was a triumph!');

Alert::info("I'm making a note here: huge success.");

<div class="alert alert-success" role="alert">
    This was a triumph!
</div>

<div class="alert alert-info" role="alert">
    I'm making a note here: huge success.
</div>

消息

您可以使用 type($message) 语法，或者采用经典方式，通过使用 message() 方法在警报中添加文本。

use Laragear\Alerts\Facades\Alert;

Alert::success('You are gonna love this! 😍');

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为个性化消息添加一些样式、链接，甚至是脚本。

use Laragear\Alerts\Facades\Alert;

Alert::warning('This is <strong>FUBAR</strong>.');

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()方法。

use Laragear\Alerts\Facades\Alert;

Alert::primary('Your message was sent!');

Alert::message('There is an unread message.')->types('info', 'cool');

<div class="alert alert-primary" role="alert">
    Your message was sent!
</div>

<div class="alert alert-info cool" role="alert">
    There is an unread message.
</div>

这些类型就像底层渲染器使用的关键字，它们会将警报转换为适当的HTML代码。

注意

默认的Bootstrap渲染器会将每个未识别的类型设置为额外的CSS类。

本地化

要动态本地化消息，请使用trans()方法，这是__()辅助函数的镜像，详情请参考这里。

use Laragear\Alerts\Facades\Alert;

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

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

您还可以使用具有相同参数的transChoice()，如trans_choice()。

use Laragear\Alerts\Facades\Alert;

Alert::transChoice('messages.apples', 1)->success();

Alert::transChoice('messages.apples', 10)->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()设置一个可关闭的警报，向渲染器发出信号进行必要的修改。

use Laragear\Alerts\Facades\Alert;

Alert::success('You can disregard this')->dismiss();

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

use Laragear\Alerts\Facades\Alert;

Alert::success('You can disregard this')->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()分别将条件评估为真或假来推送警报。进一步的方法调用将被发送到空值。

use Illuminate\Support\Facades\Auth;
use Laragear\Alerts\Facades\Alert;

Alert::when(Auth::check())
    ->success('You are authenticated');

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

持久性警报

警报只持续实际发送的响应。在重定向时，这些将闪入会话，因此这些在下一个请求（重定向目标）中可用。

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

use Laragear\Alerts\Facades\Alert;

Alert::danger('Your disk size is almost full')->persistAs('disk.full');

注意

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

完成后，您可以直接从辅助函数中使用持久性警报的键删除持久性警报，使用abandon()方法。例如，如果磁盘不再满，我们可以放弃先前的警报。

use Laragear\Alerts\Facades\Alert;

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

链接

为警报设置链接不必繁琐。您可以使用to()、route()、action()和away()轻松地将消息中的大括号内的字符串替换为链接。

use Laragear\Alerts\Facades\Alert;

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

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

use Laragear\Alerts\Facades\Alert;

// 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])

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

use Laragear\Alerts\Facades\Alert;

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')

重要

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

配置

警报将与一些常见默认值一起直接工作，但如果您需要针对特定应用程序的更好方法，您可以配置一些参数。首先，发布配置文件。

php artisan vendor:publish --provider="Laragear\Alerts\AlertsServiceProvider" --tag="config"

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

<?php 

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

渲染器

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

这选择在将警报元数据转换为HTML时使用的渲染器。

本软件包附带Bootstrap 5和Tailwind CSS渲染器，但您可以为Bulma.io、UI kit、INK甚至您自己的自定义前端框架等创建自己的渲染器。

会话密钥

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

当警报被闪现或持久化时，这些警报将存储在会话中，默认密钥为_alerts。如果您正在使用此密钥名进行其他操作，您可能需要更改它。

此密钥还用于发送JSON警报时。

默认标签列表

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

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

渲染器

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

创建自定义渲染器

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

<?php

use Laragear\Alerts\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->make('blade.compiler');
    });
}

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

// config/alerts.php

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

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

use Laragear\Alerts\Facades\Alert;

Alert::default('Popping colors!');

<div class="bg-slate-100 rounded-xl p-8 dark:bg-slate-800">
    Popping colors!
</div>

警报容器HTML

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

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

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

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

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

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

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

如您所怀疑的，您可以发布视图并覆盖它们以适应您的需求。

php artisan vendor:publish --provider="Laragear\Alerts\AlertsServiceProvider" --tag="views"

JSON警报

接收JSON警报

有时，您的应用程序可能会从使用此软件包的外部服务接收JSON警报。您可以使用fromJson()方法快速将此JSON添加为警报到您的应用程序中。

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

use Laragear\Alerts\Facades\Alert;

Alert::fromJson($json);

只要JSON有包含要包含在警报中的文本的message键，这将起作用。此外，您可以添加types和dismiss键来添加警报，并且可以在之后覆盖它们。

警告

JSON的消息设置为raw。

发送JSON警报

此库有一个方便的方法可以将警报添加到您的JSON响应中。这对于将警报添加到发送到浏览器的每个响应中非常有用，例如与Laravel Jetstream结合使用。

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

当您向浏览器返回 JsonResponse 时，中间件将使用在配置中定义的相同会话键将警报追加为 JSON，默认为 _alerts。它还接受 key 参数作为替代，兼容 点表示法。

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\UserController;

Route::prefix('api')
    ->middleware('alerts.json:_status.alerts')
    ->controller(UserController::class, function () {
    
        Route::post('user/create', 'create');
        Route::post('user/{user}/update', 'update');
        
    });

当您收到 JSON 响应时，您将看到附加到您发出的任何键的警报。使用上面的示例，我们应该在 _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 响应中，该键将被覆盖。

测试

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

use \Laragear\Alerts\Facades\Alert;

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

以下是一些可用的断言

断言特定警报

模拟 Alert Bag 允许通过使用 assertAlert() 来构建具有特定属性的警报（或不存在）的存在（或不存在）的条件。

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

use \Laragear\Alerts\Facades\Alert;

$alert = Alert::fake();

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

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

或者，如果您期望特定数量的警报匹配给定的条件，可以使用 count()，或者使用 unique() 来确保只匹配一个警报。

use \Laragear\Alerts\Facades\Alert;

$bag = Alert::fake();

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

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

以下是一些可用的条件

Laravel Octane 兼容性

与渲染器相关的类被注册为单例。
在启动时扩展 RendererManager 是安全的。
Bag 被注册为单例。您不应该在启动时解析它。
Bag 包含应用程序配置的过时版本。您不应该更改配置。
在请求过程中没有写入静态属性。

如果您按预期使用此包，则使用此包与 Laravel Octane 一起使用时应该没有问题。

安全

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

许可证

此特定包版本根据在发布时的条款和条件在 MIT 许可证下授权。

laragear / alerts

维护者

详细信息