README

⚠️ 警告：这些文档是不完整的，可能引用了不受支持的函数。这是一个预发布版本，目前尚未准备好用于生产使用。

仅为 Laravel 8 标签的 givebutter/laravel-custom-fields 的一个分支

Laravel Custom Fields 是一个允许您向任何 Laravel 模型添加自定义字段，并将这些字段与其它模型关联响应的软件包。

安装

要开始使用，请将 givebutter/laravel-custom-fields 软件包添加到您的 composer.json 文件中，并更新您的依赖项

composer require givebutter/laravel-custom-fields

发布迁移

php artisan vendor:publish --provider="Givebutter\LaravelCustomFields\LaravelCustomFieldsServiceProvider" --tag="migrations"

运行迁移

php artisan migrate

您可以使用配置选项自定义表名。更多内容稍后介绍。

示例 - 问卷调查应用

出于文档的目的，让我们以一个问卷调查构建应用为例。管理员可能使用后端创建包含问题的 Surveys，然后最终用户填写这些调查，生成 SurveyResponses。

准备您的模型

添加自定义字段

要添加基本的自定义字段支持，只需在您的模型顶部添加 HasCustomFields 特性

use Illuminate\Database\Eloquent\Model;
use Givebutter\LaravelCustomFields\Traits\HasCustomFields;

class Survey extends Model
{
    use HasCustomFields;

    // ...
}

添加自定义字段响应

接下来，我们添加存储自定义字段响应的支持。我们将在 SurveyResponse 模型的顶部简单地引入 HasCustomFieldResponses 特性。

use Illuminate\Database\Eloquent\Model;
use Givebutter\LaravelCustomFields\Traits\HasCustomFieldResponses;

class SurveyResponse extends Model
{
    use HasCustomFieldResponses;

    // ...
}

基本用法

创建字段

您可以将字段添加到模型，如下所示

$survey->customFields()->create([
    'title' => 'What is your name?',
    'type' => 'text'
]);

每个字段可以包含以下内容：（更多内容稍后介绍）

title : 自定义字段的标题 / 问题。 description : 字段的描述。对于填写字段的用户来说，这有助于提供更多的上下文。 type : 您要创建的字段类型。下文将概述可用的类型。 required : 表示字段是否必填的布尔值。 answers : 对于具有用户选择的字段，一个表示可接受值的数组。

创建字段响应

要存储字段的响应，您可以这样做

$field->responses()->create([
    'value' => 'John Doe'
]);

检索字段

要检索自定义字段，请使用 customFields 关系

$survey->customFields()->get();

检索字段响应

要检索字段上的响应，请使用 responses() 关系

$field->responses()->get();

自定义字段类型

自定义字段可以是以下 5 种类型之一

text : 自由输入字段，存储为字符串。用于简单的输入，最大长度为 255 个字符。
textarea : 自由输入字段，存储为文本列。用于可能不适合 text 字段的较长的文本。
radio : 这是多选字段，需要您传递一个 answers 属性。
select : 这是多选字段，需要您传递一个 answers 属性。
checkbox : 布尔字段。

通常，这些字段类型对应于它们的相应 HTML 元素。将来，我们可能会提供这些字段的客户端脚手架，但现在这取决于您。

**radio 和 select 字段类型需要您在字段上填写 answers 属性。这是一个简单的字符串数组，它们是该字段的有效响应。例如

$survey->customFields()->create([
   'title' => 'What is your favorite color?',
   'type' => 'select',
   'answers' => ['Red', 'Green', 'Blue', 'Yellow'], 
]);

验证响应

验证辅助工具

在大多数情况下，您在保存之前会想验证自定义字段的响应。您可以通过在模型上调用 validateCustomFields() 函数来完成此操作

$responses = [
    '1' => "John Doe",
    '2' => "Blue"
];
$survey->validateCustomFields($responses);

您还可以传入一个 Request 对象

use Request;

class FooController extends Controller {

    public function index(Request $request) 
    {
        $validation = $survey->validateCustomFields($request);

        // ...
    }

}

<form>
    <input type="text" name="custom_fields[]" />
</form>

当使用 Request 对象时，输入键应为一个值数组

隐式验证规则

上面提到的5种支持的字段类型自动应用以下验证规则

text : string|max:255
textarea : string
radio : string|max:255|in:answers
select: string|max:255|in:answers
checkbox: in:0,1

重要：当使用复选框时，您还需要POST未选中的复选框，否则您的响应数据可能不完整。

必填字段

由于它们很常见，必填字段在此包中具有原生支持。要标记字段为必填，只需在创建自定义字段时将 required 设置为 true。

$survey->customFields()->create([
    'title' => 'Do you love Laravel?',
    'type' => 'radio',
    'answers' => ['Yes', 'YES'],
    'required' => true
]);

自定义验证规则

除了内置验证规则外，您还可以将自定义规则应用于任何自定义字段。例如，如果您想要验证一个字段是介于1到10之间的整数，您可以执行以下操作

$survey->customFields()->create([
    'title' => 'Pick a number 1-10',
    'type' => 'text',
    'validation_rules' => 'integer|min:1|max:10'
]);

记住，validation_rules 支持Laravel中的任何可用验证规则。

验证规则集

-> nah？在某些情况下，定义验证规则集更容易也更实用。例如，在我们的调查应用中，如果我们想要提供一个

保存响应

要存储自定义字段的响应，只需调用 saveCustomFields() 并传入一个值数组

saveCustomFields 函数可以接受请求或数组。

$surveyResponse->saveCustomFields(['
   
']);

如果您正在提交表单请求，可以轻松地

Use App\...
$surveyResponse->saveCustomFields($request->input);

查询响应

您可以使用 WhereCustomField() 范围查询任何字段的响应。该函数接受字段对象和您要查找的值。有关查询范围的信息，请访问此链接。

例如，如果您想找到所有 SurveyResponses 有大号T恤的，执行以下查询

Use App\Models\SurveyResponse;
Use App\Models\SurveyResponse;

$field = 

SurveyResponse::WhereCustomField($field, 'large')->get();

排序

您可以使用 order 函数更改模型上自定义字段的顺序。传入一个数组或 Collection 的ID。字段的索引位置代表其顺序位置。

$survey->orderCustomFields([2, 4, 5]); // Field with id 2 will be ordered first.

您还可以手动更改 order 列的值

$field->order = 3; 
$field->save();

默认情况下，通过关系检索时，自定义字段以升序返回

$survey->customFields()->get(); // Returned in ascending order.

配置

要发布配置文件，请运行以下命令

php artisan vendor:publish --provider="Givebutter\LaravelCustomFields\LaravelCustomFieldsServiceProvider" --tag="config"

现在配置文件应该已发布到 config/custom-fields.php。可用选项及其使用说明在发布的文件中。

许可证

在 MIT 许可下发布。有关更多信息，请参阅 LICENSE。

ipop / laravel-custom-fields

维护者

详细信息