README

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

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

您可以使用配置选项自定义表名。关于这一点将在稍后讨论。

示例 - 调查应用

出于文档的目的，让我们以构建调查应用的示例。管理员可能使用后端创建充满问题的 调查，而最终用户随后可以填写这些调查，生成 调查响应。

准备您的模型

添加自定义字段

为了添加基本的自定义字段支持，只需在您的模型顶部添加 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函数可以接受Request或数组。

$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。

givebutter / laravel-custom-fields

维护者

详细信息