README

⚠️ 注意：这些文档可能不完整并可能引用不受支持的函数。这是一个预发布版本，目前还不适合生产使用。

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

安装

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

composer require givebutter/laravel-custom-fields

发布迁移

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

运行迁移

php artisan migrate

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

示例 - 问卷调查应用

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

准备您的模型

添加自定义字段

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

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

class Survey extends Model
{
    use HasCustomFields;

    // ...
}

添加自定义字段响应

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

use Illuminate\Database\Eloquent\Model;
use Birdboar\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恤尺码为 large 的响应，请执行以下查询

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="Birdboar\LaravelCustomFields\LaravelCustomFieldsServiceProvider" --tag="config"

配置文件现在应该发布在 config/custom-fields.php 中。该文件中解释了可用选项及其用法。

许可证

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

birdboar / laravel-custom-fields

维护者

详细信息