README

使用此包，您可以快速添加一个聊天气泡，该气泡可在任何页面上打开支持表单。它附带电池

内置TailwindCSS样式
如果有登录用户，则不会询问用户信息
包括一些元数据，如URL和IP地址
可以通过自定义视图、语言文件和事件监听器轻松扩展
包含蜜罐并设置以防止垃圾邮件发送者

您可以在下面的Flare和Oh Dear上看到它的实际应用！

支持我们

我们投入了大量资源来创建最佳的开源包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从您的家乡寄来明信片，说明您正在使用我们的哪些包。您可以在我们的联系页面上找到我们的地址。我们将在我们的虚拟明信片墙上发布所有收到的明信片。

您是视觉学习者吗？

在这个YouTube直播中，您将看到如何安装该包，以及它是如何在幕后工作的。

安装

您可以通过composer安装此包

composer require spatie/laravel-support-bubble

包含TailwindCSS

此包中包含的视图都使用TailwindCSS类。我们坚持使用默认的Tailwind配置类。如果您还没有使用TailwindCSS，您可以从他们的CDN轻松包含它

<link href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css" rel="stylesheet">

如果您使用Tailwind 即时模式，您应该在您的tailwind.config.js文件中添加以下这些附加行

content: [
    './vendor/spatie/laravel-support-bubble/config/**/*.php',
    './vendor/spatie/laravel-support-bubble/resources/views/**/*.blade.php',
    // other places
],

这样，Tailwind JIT将构建您的样式，包括用于支持气泡的属性。

将组件添加到您的视图中

安装包后，您需要将此Blade组件添加到您的相关视图文件中

<x-support-bubble />

如果您希望它在所有页面上显示，您可以将其添加到您的layout.blade.php文件中。

接下来，您需要注册支持表单的路由。在您的routes/api.php文件中添加以下宏

Route::supportBubble();

这将注册一个位于/support-bubble的路由

⚠️ 此包不使用CSRF令牌，因此请确保您已将路由宏添加到您的应用程序API路由中或添加到VerifyCsrfToken中间件的排除中。

// in app/Http/Middleware/VerifyCsrfToken.php

namespace App\Http\Middleware;

use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;

class VerifyCsrfToken extends Middleware
{
    protected $except = [
        'support-bubble',
        // other entries
    ];
    
    // ...
}

在Laravel 11中，这可以在bootstrap/app.php中完成

->withMiddleware(function (Middleware $middleware) {
        $middleware->validateCsrfTokens(except: [
			'support-bubble',
		]);
    })

配置消息目标

最后，您需要确定您想要将支持气泡的提交发送到何处。

默认情况下，该包可以将提交通过电子邮件发送到指定的电子邮件地址。要采取此路线，发布配置文件，并在mail_to中输入电子邮件。

或者，您可以注册一个事件监听器来监听Spatie\SupportBubble\Events\SupportBubbleSubmittedEvent事件并自行处理。此事件具有提交表单值的公共属性。

可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Spatie\SupportBubble\SupportBubbleServiceProvider" --tag="support-bubble-config"

这是已发布配置文件的默认内容

<?php

return [
    /*
     * Enable or disable fields in the support bubble.
     * Keep in mind that `name` and `email` will be hidden automatically
     * when a logged in user is detected and `prefill_logged_in_user` is set.
     */
    'fields' => [
        'name' => true,
        'email' => true,
        'subject' => true,
        'message' => true,
    ],
    
    /*
     * We'll send any chat bubble responses to this e-mail address.
     *
     * Set this to
     */
    'mail_to' => null,

    /*
     * When set to true we'll use currently logged in user to fill in
     * the name and email fields. Both fields will also be hidden.
     */
    'prefill_logged_in_user' => true,

    /*
     * The TailwindCSS classes used on a couple of key components.
     *
     * To customize the components further, you can publish
     * the views of this package.
     */
    'classes' => [
        'container' => 'text-base items-end z-10 flex-col m-4 gap-3',
        'bubble' => 'hidden sm:block | bg-purple-400 rounded-full shadow-lg w-14 h-14 text-white p-4',
        'input' => 'bg-gray-100 border border-gray-200 w-full max-w-full p-2 rounded-sm shadow-input text-gray-800 text-base',
        'button' => 'inline-flex place-center px-4 py-3 h-10 border-0 bg-purple-500 hover:bg-purple-600 active:bg-purple-600 overflow-hidden rounded-sm text-white leading-none no-underline',
    ],
    
    /*
     * The default route and controller will be registered using this route name.
     * This is a good place to hook in your own route and controller if necessary.
     */
    'form_action_route' => 'supportBubble.submit',

     /**
     * The positioning of the bubble and the form, change this between right-to-left and left-to-right, if you want to use RTL, you must have your layout set to RTL like this 
     * <html lang="ar-TN" dir="rtl">
     * By default, the value of this is LTR
     */
    'direction' => 'left-to-right',
];

自定义选项

支持气泡默认看起来应该很不错。然而，我们已经记录了自定义标签、文本、视图和功能的一些方法。

自定义表单字段

目前无法向支持气泡的表单添加新字段。但是，您可以在配置文件中禁用您不喜欢的任何字段。

自定义文本/本地化

如果您只是想自定义字段标签、介绍文本或提交成功后的文本，您可以发布包的语言文件。

php artisan vendor:publish --provider="Spatie\SupportBubble\SupportBubbleServiceProvider" --tag=support-bubble-translations

这些已发布的文件可以在 resources/lang/vendor/laravel-support-bubble/en/ 中找到并更改。

自定义样式

您可以通过更改 support-bubble.class 配置键来自定义用于气泡弹出、输入字段和提交按钮的 TailwindCSS 类。这是更改气泡默认紫色颜色或使用您自己的 .input 或 .button 类的理想位置。

如果您想更改更多高级样式，请继续阅读，了解如何发布和自定义支持气泡组件中使用的 Blade 视图。

自定义视图

您可以发布并更改此包中的所有视图（包括 JavaScript 代码）。

php artisan vendor:publish --provider="Spatie\SupportBubble\SupportBubbleServiceProvider" --tag=support-bubble-views

这些已发布的视图可以在 resources/views/vendor/laravel-support-bubble/ 中找到并更改。

请注意，添加新字段到支持气泡是不可能的（或者至少非常困难且复杂）。

自定义支持表单目的地

如果您不想将支持消息发送到配置文件中配置的 mail_to 电子邮件，您可以定义自己的事件监听器并监听 Spatie\SupportBubble\Events\SupportBubbleSubmittedEvent。该事件包含支持表单中提交的所有数据，可用于，例如，向 Freshdesk 发起 API 请求。

提交后的自定义行为（高级）

如果您真的想这样做，可以将提交的表单数据发送到您的端点。支持表单使用在 support-bubble.form_action_route 配置键中配置的路线。您可以通过从您的路由文件中删除 Route::supportBubble() 宏并将 form_action_route 设置为应用程序中的任何其他路由名称来覆盖此路线。

此路由上的传入请求将是 \Spatie\SupportBubble\Http\Requests\SupportBubbleRequest。

测试

composer test

变更日志

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

贡献

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

安全漏洞

请查看我们关于如何报告安全漏洞的安全策略。

鸣谢

替代方案

如果您需要更多支持气泡的选项，请考虑使用以下之一

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。

spatie / laravel-support-form

维护者

详细信息