README

Laravel Datatable 是一个用于处理 Laravel 应用程序中 datatables 后端逻辑的包。

主要功能

• 独立的后端解决方案，用于处理类似表格的数据
• 与各种前端表格库兼容（例如，Material React Table）
• 支持多种搜索逻辑（包含、等于、大于等）以及不同数据类型（数值、文本、日期）
• 细粒度控制可搜索、可排序和可见字段
• 能够通过模型关系进行搜索
• 可自定义的搜索逻辑（即将推出！）

要求

• PHP ≥ 8.1
• Laravel ≥ 9.0

安装

您可以通过 composer 安装此包

composer require hamidrrj/laravel-datatable

安装后，使用以下方法之一发布包的服务提供者

选项 1：自动安装（推荐）

运行以下 Artisan 命令

php artisan datatable:install

选项 2：手动安装

手动发布提供者

php artisan vendor:publish --tag="datatable-provider"

然后，将以下行添加到 config/app.php 文件中的 providers 数组中

return [
    // ...
    'providers' => ServiceProvider::defaultProviders()->merge([
        // ...
        App\Providers\DatatableServiceProvider::class,
        // ...
    ])->toArray(),
    // ...
];

用法

本节涵盖了 Laravel Datatable 的各种用例和功能。从基本查询到高级过滤和关系处理，您将找到示例来帮助您充分利用此包。

目录

• 方法参数
• 过滤数组结构
• 返回数据结构
• 基本用法
• 使用查询构建器
• 高级过滤和排序
• 使用 between 搜索函数
• 过滤模型的关系

方法参数

DatatableFacade 的 run 方法接受以下参数

1. $mixed：要执行查询的模型实例或查询构建器实例。
2. $requestParameters：包含所需数据的参数，如 filter、sorting、size 和 start。
3. $allowedFilters：(可选) 指定用户可以过滤的列。
4. $allowedSortings：(可选) 指定用户可以排序的列。
5. $allowedSelects：(可选) 指定用户可以查看的列。
6. $allowedRelations：(可选) 指定用户可以过滤的模型关系。

过滤数组结构

在 filters 数组中的每个过滤器都应具有以下属性

• id：要过滤的列的名称。当过滤关系属性时，使用以下格式：relationName.attribute。（relationName 必须在基本模型中作为 HasOne 或 HasMany 关系存在，例如 User 模型）
• value：过滤器的值
  • 对于大多数过滤器类型：单个值
  • 对于 fn = 'between'：两个值的数组，例如 [min, max]
• fn：要应用的过滤器类型。可用选项包括
  • contains
  • between
  • equals
  • notEquals
  • lessThan
  • lessThanOrEqual
  • greaterThan
  • greaterThanOrEqual
• datatype：列的类型。选项包括
  • text
  • numeric
  • date

返回数据结构

run 方法返回一个具有以下结构的数组

[
    "data" => [
        // Array of matching records
    ],
    "meta" => [
        "totalRowCount" => 10 // Total count of matching records
    ]
]

基本用法

以下是一个简单的示例，请求从第 11 条记录开始的 10 个用户（即，表格的页面 2）

use \HamidRrj\LaravelDatatable\Facades\DatatableFacade;

$userModel = new User();

$requestParameters = [
    'start' => 10,
    'size' => 10,
    'filters' => [],
    'sorting' => []
];

$data = DatatableFacade::run(
    $userModel,
    $requestParameters
);

使用查询构建器

您可以使用查询构建器实例而不是模型实例

$query = User::query()->where('username', '!=', 'admin');

$data = DatatableFacade::run(
    $query,
    $requestParameters
);

高级过滤和排序

以下是一个过滤年龄大于15岁的用户，并按创建日期降序排序的示例。

$query = User::query();

$requestParameters = [
    'start' => 10,
    'size' => 10,
    'filters' => [
        [
            'id' => 'age',
            'value' => 15,
            'fn' => 'greaterThan',
            'datatype' => 'numeric'
        ]
    ],
    'sorting' => [
        [
            'id' => 'created_at',
            'desc' => true,
        ]
    ]
];

$allowedFilters = ['age'];
$allowedSortings = ['created_at'];

$data = DatatableFacade::run(
    $query,
    $requestParameters,
    $allowedFilters,
    $allowedSortings
);

注意：确保用于过滤和排序的列包含在 $allowedFilters 和 $allowedSortings 数组中，以避免出现 InvalidFilterException 和 InvalidSortingException。

使用 between 搜索功能

以下是一个过滤创建日期在两个日期之间的用户的示例

$query = User::query()

$requestParameters = [
        'start' => 0,
        'size' => 10,
        'filters' => [
            [
                'id' => 'created_at',
                'value' => ['2024-05-23 10:30:00', '2024-05-29 15:00:00'],
                'fn' => 'between',
                'datatype' => 'date'
            ]
        ],
        'sorting' => []
    ];

$allowedFilters = array('created_at');
$allowedSelects = array('username', 'age', 'created_at');

$data = (new Datatable())->run(
    $query,
    $requestParameters,
    $allowedFilters,
    allowedSelects: $allowedSelects
);

注意：使用 $allowedSelects 将只返回查询结果中指定的列

[
    "data" => [
        [
            'username' => 'mwindler'
            'age' => 49
            'created_at' => '2024-05-23T12:00:00.000000Z' 
        ],
        // more matching records
    ],
    "meta" => [
        "totalRowCount" => 10 // Total count of matching records
    ]
]

过滤模型的关系

在这个例子中，我们只过滤标题中含有 'my post' 的帖子所属的用户

$query = User::query();

$requestParameters = [
    'start' => 0,
    'size' => 10,
    'filters' => [
        [
            'id' => 'posts.title',
            'value' => 'my post',
            'fn' => 'contains',
            'datatype' => 'text'
        ]
    ],
    'sorting' => []
];

$allowedFilters = array('posts.title');
$allowedRelations = array('posts');

$data = (new Datatable())->run(
    $query,
    $requestParameters,
    $allowedFilters,
    allowedRelations: $allowedRelations
);

注意:

• 在 id 中使用 posts.title（用户模型必须在 Models/User 类中定义 posts 关联）
• 使用 $allowedRelations 在查询结果中加载每个用户的帖子

[
    "data" => [
        [
            'id' => 1,
            'username' => 'sth', 
            'posts' => [  // posts included in result
                [
                    'title' => 'wow! my post got 1k impressions!'
                ], 
                // ...
            ]
        ],
        // more matching records
    ],
    "meta" => [
        "totalRowCount" => 10 // Total count of matching records
    ]
]

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

致谢

• Hamidreza Ranjbarpour

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。