README

FlexyField 是一个用于 Laravel 的动态字段包，允许开发者在不修改数据库模式的情况下，为模型定义灵活和可自定义的字段。

它支持即时定义字段、字段类型、验证和值分配，为需要灵活内容结构的项目提供完美解决方案。

主要功能

• 动态添加任何 Eloquent 模型中的字段。
• 支持字段类型：字符串、整数、小数、日期、布尔型和日期时间。
• 使用 Laravel 的验证规则进行字段级别验证。
• 使用 Elequent 的原生方法按灵活字段值查询模型。
• 通过枢纽视图支持多个字段类型和数据存储。
• 完全集成 Laravel 的原生模型结构。

安装

要使用 Composer 安装包，请运行

composer require aurorawebsoftware/flexyfield

安装后，运行提供的迁移以创建必要的表

php artisan migrate

数据库结构

该包创建两个主要表和一个视图

• ff_shapes：存储字段的形状定义、验证规则和验证消息
• ff_values：存储分配给模型灵活字段的实际值。
• ff_values_pivot_view：将所有值作为枢纽表查看

快速入门

将 Flexy 字段添加到模型中

要开始使用 Flexy 字段，只需在您的模型中包含 Flexy 特性并实现 FlexyModelContract。

use AuroraWebSoftware\FlexyField\Contracts\FlexyModelContract;
use AuroraWebSoftware\FlexyField\Traits\Flexy;
use Illuminate\Database\Eloquent\Model;

class Product extends Model implements FlexyModelContract {
    use Flexy;
    
    // your class implementation
}

这使模型能够支持动态分配的字段。

设置和检索 Flexy 字段

设置模型后，您可以定义并将灵活字段分配给它。字段通过 flexy 属性分配。

$product = Product::create(['name' => 'Training Shoes']);

// Set flexy fields
$product->flexy->color = 'blue'; // string
$product->flexy->price = 49.90; // decimal value
$product->flexy->size = 42; // integer
$product->flexy->gender = 'man'; // string
$product->flexy->in_stock = true; // boolean
$product->flexy->availables_coupons = ['summer15', 'white_saturday']; // array, json
$product->save();

// Retrieve the flexy fields using flexy attribute
echo $product->flexy->color; // Outputs 'blue'
echo $product->flexy->size; // Outputs 42`
echo $product->flexy->in_stock; // Outputs true`
echo $product->flexy->availables_coupons; // json string, must be decoded

// or retrieve the flexy fields using default models' attribute with flexy_ prefix
echo $product->flexy_color; // Outputs 'blue'
echo $product->flexy_size; // Outputs 42`
echo $product->flexy_in_stock; // Outputs true`

为验证定义模型形状

形状是具有类型和验证规则的字段定义。每个模型可以有一个形状。您可以使用 setFlexyShape() 动态定义形状以应用验证。

use AuroraWebSoftware\FlexyField\Enums\FlexyFieldType;

Product::setFlexyShape('color', FlexyFieldType::STRING, 1, 'required');
Product::setFlexyShape('size', FlexyFieldType::INTEGER, 2, 'numeric|min:20');
Product::setFlexyShape('in_stock', FlexyFieldType::BOOLEAN, 3, 'required|bool');
Product::setFlexyShape('availables_coupons', FlexyFieldType::JSON, 3, 'required');

这确保在保存 color 字段时它必须为必填，并且 size 字段必须是大于或等于 20 的数字。

所有可用的验证规则：https://laravel.net.cn/docs/11.x/validation#available-validation-rules

检索和删除模型形状

Product::getFlexyShape('color'); // returns Shape model
Product::deleteFlexyShape('color');

带有验证保存模型

定义了具有验证规则的形状后，保存包含无效数据的模型将抛出 ValidationException。

use Illuminate\Validation\ValidationException;

try {
    $product->flexy->size = 'invalid-size';
    $product->save(); // Throws ValidationException
} catch (ValidationException $e) {
    // Handle the exception
    echo "Validation failed: " . $e->getMessage();
}

高级用法

按动态字段查询模型

FlexyField 允许您根据模型的灵活字段值查询模型。以下是如何使用 Flexy 字段过滤模型的示例

// Find all blue products
$products = Product::where('flexy_color', 'blue')->get();

// or dynamic where
$products = Product::whereFlexyColor('blue')->get();

// Find models with multiple conditions on flexy fields
$models = Product::where('flexy_color', 'blue 1')
    ->where('flexy_price', '<',  100)
    ->where('flexy_in_stock', true)
    ->get();

动态验证

可以使用您定义的形状验证 Flexy 字段。例如，您可以设置验证规则如

use AuroraWebSoftware\FlexyField\Enums\FlexyFieldType;

User::setFlexyShape('username', FlexyFieldType::STRING, 1, 'required|max:20');
User::setFlexyShape('score', FlexyFieldType::INTEGER, 2, 'numeric|min:0|max:100');
User::setFlexyShape('banned', FlexyFieldType::BOOLEAN, 3, 'bool');

如果用户尝试保存无效数据，Laravel 的原生验证系统将启动并阻止保存

$user->flexy->username = 'too_long_username_exceeding_the_limit';
$user->flexy->score = 120;
$user->flexy->banned = false;
$user->save(); // ValidationException thrown due to invalid data`

使用日期和日期时间

FlexyField 支持处理 date 和 datetime 字段类型。

use Carbon\Carbon;

$flexyModel->flexy->event_date = Carbon::now(); // Save current date as a flexy field
$flexyModel->save();

echo $flexyModel->flexy->event_date; // Output the saved date`

动态字段排序

FlexyField 允许您使用 sort 参数指定字段的排序顺序

ExampleFlexyModel::setFlexyShape('sorted_top_field', FlexyFieldType::STRING, 1);
ExampleFlexyModel::setFlexyShape('sorted_bottom_field', FlexyFieldType::STRING, 10);

这控制了检索或显示时字段的排序方式。

配置

您可以将包配置为使用不同的数据库驱动程序（例如 MySQL 或 PostgreSQL）用于灵活字段枢纽表。

贡献

请随时通过提交拉取请求或打开问题来为 FlexyField 的开发做出贡献。我们始终欢迎贡献以增强此包。

运行测试

在提交任何更改之前，请确保运行测试以确认一切按预期工作。

您可以使用 Pest 运行提供的测试，以确保一切按预期工作。

./vendor/bin/pest

代码风格

./vendor/bin/pint

静态分析

./vendor/bin/phpstan analyse

许可

FlexyField 软件包是开源软件，许可协议为 MIT 许可。