README

用于Laravel 5.0及以上版本的Composer包，允许在应用程序内进行反馈和支持请求。

此包默认提供接受反馈和支持提交的能力，无需进行大量代码更新。消息中还将包含当前认证用户的信息。

默认启用MySQL数据库功能，以促进发送的消息的存储和持久化。然而，此功能是可选的，因此此包无需数据库即可执行发送请求。

注意：此包依赖于Laravel提供的邮件功能，设置可能因Laravel版本而异。请确保您的.env文件中的邮件设置有效。

目录

• 安装
  • Composer、环境和服务提供者
    • Composer
    • 环境
    • 服务提供者
  • 路由安装
    • Laravel 5.1及以上
    • Laravel 5.0
  • 发布所有内容
• 必需的环境变量
• 可选的环境变量
• 路由
  • 显示反馈表单
  • 处理反馈表单
  • 显示支持请求表单
  • 处理支持请求表单
• 迁移
  • 反馈提交
  • 支持请求提交
• 模型
  • 反馈提交
  • 支持请求提交
• 自定义消息
• 自定义表单请求
  • 反馈表单请求
    • 验证规则
    • 验证消息
  • 支持表单请求
    • 验证规则
    • 验证消息
• 发送邮件
  • 自定义可邮寄实例
    • 反馈可邮寄
    • 支持请求可邮寄
  • 邮件外观Fallback
• 控制器
  • 反馈控制器
  • 支持请求控制器
• 视图
  • 电子邮件
  • 表单
• 资源
  • 邮件文档
  • 队列文档
  • 本地化文档
  • 表单请求验证文档

安装

Composer、环境和服务提供者

Composer

要从Composer安装，请使用以下命令

composer require csun-metalab/laravel-support

环境

现在，将以下行添加到您的.env文件中

FEEDBACK_RECIPIENT=
SUPPORT_RECIPIENT=

您还可以选择将以下可选行添加到您的.env文件中，以进一步自定义功能。这些值显示为它们的默认值。它们在下面的可选环境变量部分中进行了详细说明

FEEDBACK_FROM_ADDR=donotreply@example.com
FEEDBACK_FROM_NAME="Do Not Reply"

SUPPORT_FROM_ADDR=donotreply@example.com
SUPPORT_FROM_NAME="Do Not Reply"

FEEDBACK_TITLE="New Feedback Submission"
SUPPORT_TITLE="New Support Request"

SUBMITTER_ID_ATTR=id
SUBMITTER_NAME_ATTR=name
SUBMITTER_EMAIL_ATTR=email

ALLOW_APPLICATION_NAME_OVERRIDE=false
SEND_COPY_TO_SUBMITTER=false

FEEDBACK_TYPE=text
SUPPORT_TYPE=text

SUPPORT_ENABLE_DB=true

如果您希望保留给定值的默认值，则无需在您的.env文件中包含它们。

服务提供者

将服务提供者添加到Laravel的config/app.php中的providers数组中，如下所示

'providers' => [
   //...

   CSUNMetaLab\Support\Providers\SupportServiceProvider::class,

   // You can also use this based on Laravel convention:
   // 'CSUNMetaLab\Support\Providers\SupportServiceProvider',

   //...
],

路由安装

现在您需要添加该包的各种路由。它们是命名路由，因为您可以根据自己的应用程序自定义路由路径。在执行操作时，包将使用路由名称而不是路径。

Laravel 5.1及以上

将以下组添加到您的routes.php或routes/web.php文件中，具体取决于Laravel版本，以启用路由

Route::group(['middleware' => ['auth']], function () {
  Route::get('support', '\CSUNMetaLab\Support\Http\Controllers\SupportController@create')->name('support.create');
  Route::post('support', '\CSUNMetaLab\Support\Http\Controllers\SupportController@store')->name('support.store');

  Route::get('feedback', '\CSUNMetaLab\Support\Http\Controllers\FeedbackController@create')->name('feedback.create');
  Route::post('feedback', '\CSUNMetaLab\Support\Http\Controllers\FeedbackController@store')->name('feedback.store');
});

Laravel 5.0

将以下组添加到您的routes.php文件中，以启用路由

Route::group(['middleware' => ['auth']], function () {
  Route::get('support', [
    'uses' => '\CSUNMetaLab\Support\Http\Controllers\SupportController@create',
    'as' => 'support.create',
  ]);
  Route::post('support', [
    'uses' => '\CSUNMetaLab\Support\Http\Controllers\SupportController@store',
    'as' => 'support.store',
  ]);
  Route::get('feedback', [
    'uses' => '\CSUNMetaLab\Support\Http\Controllers\FeedbackController@create',
    'as' => 'feedback.create',
  ]);
  Route::post('feedback', [
    'uses' => '\CSUNMetaLab\Support\Http\Controllers\FeedbackController@store',
    'as' => 'feedback.store',
  ]);
});

发布所有内容

最后，运行以下Artisan命令来发布所有内容

php artisan vendor:publish

以下是一些已发布的资源

• 配置（标记为config） - 这些将放入您的config目录中
• 迁移（标记为migrations） - 这些将放入您的database/migrations目录中
• 模型（标记为models） - 这些将放入您的app目录中
• 消息（标记为 lang） - 这些将被放入你的 resources/lang/en 目录下的 support.php 文件中
• 视图（标记为 views） - 这些将被放入你的 resources/views/vendor/support 目录

必需的环境变量

你在 .env 文件中添加了两个环境变量，用于控制通过电子邮件发送消息。

FEEDBACK_RECIPIENT

用作反馈电子邮件的收件人地址。如果用竖线字符分隔，可以指定多个收件人。

示例（单个）：feedback@example.com

示例（多个）：info@example.com|feedback@example.com

SUPPORT_RECIPIENT

用作支持请求电子邮件的收件人地址。如果用竖线字符分隔，可以指定多个收件人。

示例（单个）：support@example.com

示例（多个）：help@example.com|support@example.com

可选的环境变量

有几个可选的环境变量可以添加，以进一步定制包的功能。

FEEDBACK_FROM_ADDR

发送反馈消息时用作发件人的电子邮件地址。

如果没有指定此值，将使用 .env 中的 MAIL_FROM 值。如果没有可用的 MAIL_FROM 值作为后备，则在发送反馈消息时将抛出异常。

默认值是 MAIL_FROM 值或 null。

FEEDBACK_FROM_NAME

发送反馈消息时用作电子邮件显示名称。

默认是 Do Not Reply。

SUPPORT_FROM_ADDR

发送支持请求消息时用作发件人的电子邮件地址。

如果没有指定此值，将使用 .env 中的 MAIL_FROM 值。如果没有可用的 MAIL_FROM 值作为后备，则在发送支持请求消息时将抛出异常。

默认值是 MAIL_FROM 值或 null。

SUPPORT_FROM_NAME

发送支持请求消息时用作电子邮件显示名称。

“发件人”地址将由此包之外的环境值 MAIL_FROM 确定。

默认是 Do Not Reply。

FEEDBACK_TITLE

发送反馈消息时电子邮件的标题。

默认是 New Feedback Submission。

SUPPORT_TITLE

发送支持请求消息时电子邮件的标题。

默认是 New Support Request。

SUBMITTER_ID_ATTR

在配置的 User 模型中用作主键的属性。

默认是 id。

SUBMITTER_NAME_ATTR

在配置的 User 模型中用作可读显示名称的属性。

在发送电子邮件消息时将包含此值。

默认是 name。

SUBMITTER_EMAIL_ATTR

在配置的 User 模型中用作电子邮件地址的属性。

在发送电子邮件消息时将包含此值。

默认是 email。

ALLOW_APPLICATION_NAME_OVERRIDE

确定消息中报告的应用程序名称是否可以被具有名称 application_name 的请求输入值覆盖。

如果设置为 true，则可以促进创建一个中央支持请求系统，使用户可以选择问题出现的应用程序，例如。如果请求值不存在，则将使用 app.name 配置条目的值。

默认值是 false。

SEND_COPY_TO_SUBMITTER

布尔值，描述提交者是否应收到发送的消息的副本。

默认是 false。

FEEDBACK_TYPE

确定要发送的反馈电子邮件消息的类型。有效值是 text 和 html。

默认值是 text。

SUPPORT_TYPE

确定要发送的支持请求电子邮件消息的类型。有效值是 text 和 html。

默认值是 text。

SUPPORT_ENABLE_DB

MySQL数据库支持默认开启，因此您需要拥有有效的数据库连接。可以通过将该值设置为false来禁用数据库支持。即使禁用了数据库支持，此包仍然可以执行发送电子邮件消息的操作。

存储反馈和支持提交的数据库表由已发布的模型决定。

在执行任何数据库查询之前必须运行迁移。

默认值为true。

路由

对于此包公开的所有路由，您有权修改路由的路径，但请记住以下两个约束：

1. 请不要修改路由的HTTP方法，除非您也打算修改已发布的视图。
2. 请不要修改路由名称，因为底层的控制器功能和已发布的视图都使用它们。

显示反馈表单

• 路径：/feedback
• HTTP方法：GET
• 路由名称：feedback.create

处理反馈表单

• 路径：/feedback
• HTTP方法：POST
• 路由名称：feedback.store

显示支持请求表单

• 路径：/support
• HTTP方法：GET
• 路由名称：support.create

处理支持请求表单

• 路径：/support
• HTTP方法：POST
• 路由名称：support.store

迁移

此包包含两个迁移。它们旨在存储从应用程序接收到的反馈和支持请求提交的信息。

在两种情况下，还存储了提交消息的应用程序名称以及认证用户的ID。

您也不必使用这些迁移。关联的模型可以指向任何与相同结构的数据库表。

反馈提交

表名是feedback_submissions。

• submission_id：自动递增的整数主键
• application_name：可空的应用程序名称，从提交消息的地方；默认为app.name配置元素的值
• user_id：提交消息的认证用户的ID
• content：反馈消息的正文文本
• created_at：描述消息发送时间的戳记
• updated_at：可空的描述消息何时更新的时间戳，如果有的话

支持请求提交

表名是support_submissions。

• submission_id：自动递增的整数主键
• application_name：可空的应用程序名称，从提交消息的地方；默认为app.name配置元素的值
• user_id：提交消息的认证用户的ID
• impact：导致请求的问题的影响（例如，可以是低、中或高）
• content：支持请求消息的正文文本
• created_at：描述消息发送时间的戳记
• updated_at：可空的描述消息何时更新的时间戳，如果有的话

模型

用于存储反馈和支持请求提交的模型可以在发布于config/support.php文件中的database.models部分进行配置。

当在控制器中使用时，如果找不到模型，将抛出异常。然而，电子邮件消息本身仍然会发送出去。

还可以在模型本身中配置每个模型的表和主键。

反馈提交

模型的完整命名空间是CSUNMetaLab\Support\Models\FeedbackSubmission。

• 表：feedback_submissions
• 主键：submission_id
• 可填充：application_name、user_id、content

可能抛出的异常是CSUNMetaLab\Support\Exceptions\FeedbackModelNotFoundException的一个实例。

支持请求提交

模型的完整命名空间是CSUNMetaLab\Support\Models\Supportubmission。

• 表：support_submissions
• 主键：submission_id
• 可填充：application_name、user_id、impact、content

可能抛出的异常是CSUNMetaLab\Support\Exceptions\SupportModelNotFoundException的一个实例。

自定义消息

此包的默认自定义消息可以在resources/lang/en/support.php中找到。需要时也可以覆盖这些消息。

您还可以将该文件中的消息翻译成其他语言以促进本地化。

该包从该文件（使用配置的区域设置）读取，以显示给用户的所有消息或写入任何日志。

自定义表单请求

控制器利用自定义表单请求类来接受和处理输入。每个表单请求都公开自定义验证规则和错误消息。

反馈表单请求

该类命名空间为 CSUNMetaLab\Support\Http\Requests\FeedbackFormRequest。

大多数处理所需的数据将由匹配的控制器添加，因此此请求的验证规则不多。

验证规则

• content.required：请求中的 content 字段必须有一个非空值

验证消息

• support.errors.v.feedback.content.required：未输入 content 字段

支持表单请求

该类命名空间为 CSUNMetaLab\Support\Http\Requests\SupportFormRequest。

验证规则

• impact.required：请求中的 impact 字段必须有一个非空值
• impact.in：impact 字段的值必须在 config/support.php 中 impact 键的数组值内
• content.required：请求中的 content 字段必须有一个非空值

验证消息

• support.errors.v.support.impact.required：未输入 impact 字段
• support.errors.v.support.impact.in：impact 字段的值无效
• support.errors.v.support.content.required：未输入 content 字段

发送邮件

根据安装包的 Laravel 版本，反馈和支持请求消息的发送方式可能会有所不同。

然而，在所有情况下，消息都要求排队，因此可以根据需要与 某种 Laravel 队列 一起使用。

自定义可邮寄实例

请注意，如果存在 Illuminate\Mail\Mailable 类，则将仅使用自定义的队列实例。

因此，这些实例仅用于 Laravel 5.3 及以上版本。

反馈可邮寄

该类命名空间为 CSUNMetaLab\Support\Mail\FeedbackMailMessage。

构建此邮件时，将在 resources/views/vendor/support 目录中使用 emails.feedback 视图。

以下变量通过类的公共属性暴露给视图

• $submitter_name：提交消息的个人的姓名
• $submitter_email：提交消息的个人的电子邮件地址
• $application_name：提交消息的应用程序的名称
• $content：消息的主体内容

支持请求可邮寄

该类命名空间为 CSUNMetaLab\Support\Mail\SupportMailMessage。

构建此邮件时，将在 resources/views/vendor/support 目录中使用 emails.support 视图。

以下变量通过类的公共属性暴露给视图

• $submitter_name：提交消息的个人的姓名
• $submitter_email：提交消息的个人的电子邮件地址
• $application_name：提交消息的应用程序的名称
• $impact：导致支持请求的问题的影响
• $content：消息的主体内容

邮件外观Fallback

在 Laravel 5.0 - 5.2 中，将使用 Mail 门面及其 queue() 方法，因为当时还没有 mailables 的概念。

控制器

反馈控制器

该类命名空间为 CSUNMetaLab\Support\Http\Controllers\FeedbackController。

显示反馈表单

create() 方法在 resources/views/vendor/support/forms 目录中显示 feedback.blade.php 视图。

处理反馈数据

store() 方法执行以下步骤以处理反馈提交

1. 检查有效的发送者地址。如果没有，将抛出一个 CSUNMetaLab\Support\Exceptions\InvalidFeedbackSenderException 实例。
2. 动态解析当前认证用户的 ID、姓名和电子邮件地址。
3. 根据是否存在 Illuminate\Mail\Mailable 类做出决定。
   • 如果存在该类，则解析反馈 mailable 的一个实例，并使用该实例发送消息。
   • 如果该类不存在，则直接使用 Mail 门面发送消息。
4. 向指定的收件人发送反馈电子邮件消息
5. 如果启用了数据库支持，则执行以下步骤
   1. 检查有效的反馈提交模型。如果该模型不存在，将抛出 CSUNMetaLab\Support\Exceptions\FeedbackModelNotFoundException 实例。
   2. 在模型上调用 create() 方法以将提交的数据保存到数据库
6. 使用 redirect()->back() 方法重定向回并添加一个名为 success 的闪存消息，该消息表示成功消息的文本。

支持请求控制器

显示支持请求表单

create() 方法在 resources/views/vendor/support/forms 目录内的 support.blade.php 视图。

处理支持请求数据

store() 方法执行以下步骤以处理支持请求提交

1. 检查有效的发送者地址。如果不存在，将抛出 CSUNMetaLab\Support\Exceptions\InvalidSupportSenderException 实例。
2. 动态解析当前认证用户的 ID、姓名和电子邮件地址。
3. 根据是否存在 Illuminate\Mail\Mailable 类做出决定。
   • 如果该类存在，它解析一个 支持请求可邮寄类 的实例，并使用它发送消息。
   • 如果该类不存在，则直接使用 Mail 门面发送消息。
4. 向指定的收件人发送支持请求消息
5. 如果启用了数据库支持，则执行以下步骤
   1. 检查有效的支持提交模型。如果该模型不存在，将抛出 CSUNMetaLab\Support\Exceptions\SupportModelNotFoundException 实例。
   2. 在模型上调用 create() 方法以将提交的数据保存到数据库
6. 使用 redirect()->back() 方法重定向回并添加一个名为 success 的闪存消息，该消息表示成功消息的文本。

视图

电子邮件

反馈

反馈电子邮件模板存在于 resources/views/vendor/support/emails 目录内的 feedback.blade.php。以下变量通过可邮寄类或直接在 Mail 门面方法上调用方法暴露给视图。

• $submitter_name：提交消息的个人的姓名
• $submitter_email：提交消息的个人的电子邮件地址
• $application_name：提交消息的应用程序的名称
• $content：消息的主体内容

模板仅作为文本模板结构（默认情况下不包含HTML）以促进发送到某种类型的自动化问题跟踪系统。当然，您可以根据需要修改模板。

支持请求

反馈电子邮件模板存在于 resources/views/vendor/support/emails 目录内的 support.blade.php。以下变量通过可邮寄类或直接在 Mail 门面方法上调用方法暴露给视图。

• $submitter_name：提交消息的个人的姓名
• $submitter_email：提交消息的个人的电子邮件地址
• $application_name：提交消息的应用程序的名称
• $impact：导致支持请求的问题的影响
• $content：消息的主体内容

模板仅作为文本模板结构（默认情况下不包含HTML）以促进发送到某种类型的自动化问题跟踪系统。当然，您可以根据需要修改模板。

表单

反馈

反馈表单模板存在于 resources/views/vendor/support/forms 目录内的 feedback.blade.php。以下变量通过匹配控制器暴露给视图。

• $submitter_name：提交消息的个人的姓名
• $submitter_email：提交消息的个人的电子邮件地址
• $application_name：提交消息的应用程序的名称

模板结构为一个使用 Bootstrap 4 的原始 HTML 文档。当然，您可以根据需要修改模板以匹配您的应用程序。

支持请求

支持请求表单模板存在于 resources/views/vendor/support/forms 目录内的 support.blade.php。以下变量通过匹配控制器暴露给视图。

• $submitter_name：提交消息的个人的姓名
• $submitter_email：提交消息的个人的电子邮件地址
• $application_name：提交消息的应用程序的名称
• $impact：一个关联数组，允许个人描述问题的严重性

模板结构为一个使用 Bootstrap 4 的原始 HTML 文档。当然，您可以根据需要修改模板以匹配您的应用程序。

资源

邮件文档

• Laravel 5.0 中的邮件
• Laravel 5.1 中的邮件
• Laravel 5.2 中的邮件
• Laravel 5.3 中的邮件
• Laravel 5.4 中的邮件
• Laravel 5.5 中的邮件

队列文档

• Laravel 5.0 中的队列
• Laravel 5.1 中的队列
• Laravel 5.2 中的队列
• Laravel 5.3 中的队列
• Laravel 5.4 中的队列
• Laravel 5.5 中的队列

本地化文档

• Laravel 5.0 中的本地化
• Laravel 5.1 中的本地化
• Laravel 5.2 中的本地化
• Laravel 5.3 中的本地化
• Laravel 5.4 中的本地化
• Laravel 5.5 中的本地化

表单请求验证文档

• Laravel 5.0 中的表单请求验证
• Laravel 5.1 中的表单请求验证
• Laravel 5.2 中的表单请求验证
• Laravel 5.3 中的表单请求验证
• Laravel 5.4 中的表单请求验证
• Laravel 5.5 中的表单请求验证