README

将任何 Eloquent 模型转换为列表！

感谢您的兴趣。我不再使用 PHP 或 Laravel，也没有足够的时间维护这个包。

描述

Listify 提供了对列表中的多个对象进行排序和重新排列的功能。具有此指定的类需要在映射的数据库表上定义一个 position 列作为整数。 Listify 是非常有用的 Ruby 钩子 acts_as_list 的 Eloquent 版本（https://github.com/swanandp/acts_as_list）。

• 需求
• 安装
• 快速开始
• 概述
• 配置
• 注意
• 未来计划
• 贡献
• 版权

需求

• Listify 当前需要 php >= 5.5（Listify 通过使用特性实现）。
• Laravel 5.0 或更高版本

对于 Laravel 4 的使用，请使用版本 1.0.6。

安装

Listify 以 composer 包的形式分发，这是在您的应用程序中使用它的方式。

使用 Composer 安装此包。编辑您的项目 composer.json 文件以需要 lookitsatravis/listify。

  "require": {
    "laravel/framework": "~5.0",
    "lookitsatravis/listify": "~1.2"
  }

完成此操作后，最后一步是添加服务提供程序。打开 app/config/app.php，并在提供程序数组中添加一个新项目。

    'Lookitsatravis\Listify\ListifyServiceProvider'

可选地，您可以定义 Listify 特性的别名。打开 app/config/app.php，并在别名数组中添加一个新项目。

    'Listify' => 'Lookitsatravis\Listify\Listify'

快速开始

首先，您需要添加一个列来存储位置。从命令行使用迁移生成器

php artisan listify:attach {table_name} {position_column_name}
php artisan migrate

{table_name} 是必选参数。{position_column_name} 是可选的，默认值为 "position"。

然后，在您的模型中

class User extends Eloquent
{
    use \Lookitsatravis\Listify\Listify;

    public function __construct(array $attributes = array(), $exists = false) {

        parent::__construct($attributes, $exists);

        $this->initListify();
    }
}

确保在您的模型中调用 initListify() 方法后调用 parent::__construct()。

这就是获取 Listify 热度所需的所有内容。

概述

添加到 Eloquent 模型的实例方法

您将为添加 Listify 的每个 Eloquent 模型实例添加多个方法。

在 Listify 中，“更高”意味着列表上（较低的 position），而“更低”意味着列表下（较高的 position）。这可能会令人困惑，因此可能需要添加测试来验证您是否根据上下文正确地使用了方法。

更改位置和重新排列列表的方法

• eloquentModel.insertAt(2)
• eloquentModel.moveLower() 如果项目是最低的项目，将不会执行任何操作
• eloquentModel.moveHigher() 如果项目是最高项目，将不会执行任何操作
• eloquentModel.moveToBottom()
• eloquentModel.moveToTop()
• eloquentModel.removeFromList()

不立即重新排序列表的更改位置的方法

注意：一旦模型保存，更改的位置仍将触发列表中其他项目的更新

• eloquentModel.incrementPosition()
• eloquentModel.decrementPosition()
• eloquentModel.setListPosition(3)

返回项目列表位置属性的方法

• eloquentModel.isFirst()
• eloquentModel.isLast()
• eloquentModel.isInList()
• eloquentModel.isNotInList()
• eloquentModel.isDefaultPosition()
• eloquentModel.higherItem()
• eloquentModel.higherItems() 将返回列表中 eloquentModel 之上所有的项目（按位置升序排列）
• eloquentModel.lowerItem()
• eloquentModel.lowerItems() 将返回列表中 eloquentModel 之下所有的项目（按位置升序排列）

##配置

有一些可用的配置选项。您需要将这些选项作为数组参数传递给在模型构造函数中调用的 initListify()。以下是选项：

• top_of_list 设置列表顶部的整数位置（默认：1）。
• column 设置您在安装期间选择的名称作为位置列（默认：'position'）。
• add_new_at 设置您在安装期间选择的名称作为位置列（默认：'bottom'，选项：'top' 或 'bottom'）。
• scope 允许您对列表中的项目进行范围限制。这需要一些解释。接受三个可能值：
  • 字符串
  • Illuminate\Database\Eloquent\Relations\BelongsTo 对象
  • Illuminate\Database\Query\Builder 对象

###字符串

如果传递了 string，则将原始字符串作为 whereRaw 传递给范围。这允许您执行类似 'custom_foreign_key = 42' 的操作，并使所有项目都限于该结果集。您可以传递复杂的 where 子句，它将直接传递到每个数据库操作中。

示例

class User extends Eloquent
{
    use \Lookitsatravis\Listify\Listify;

    public function __construct(array $attributes = array(), $exists = false) {

        parent::__construct($attributes, $exists);

        $this->initListify([
            'scope' => 'answer_to_ltuae = 42'
        ]);
    }
}

结果为一个范围

WHERE answer_to_ltuae = 42

###Illuminate\Database\Eloquent\Relations\BelongsTo

如果传递了 Illuminate\Database\Eloquent\Relations\BelongsTo，则 Listify 将将范围的外键与模型实例对应的外键的值相匹配。

示例

class ToDoListItem extends Eloquent
{
    use \Lookitsatravis\Listify\Listify;

    public function __construct(array $attributes = array(), $exists = false) {

        parent::__construct($attributes, $exists);

        $this->initListify([
            'scope' => $this->toDoList()
        ]);
    }

    public function toDoList()
    {
        $this->belongsTo('ToDoList');
    }
}

结果为一个范围

WHERE to_do_list_id = {{value of toDoListItem.to_do_list_id}}

###Illuminate\Database\Query\Builder

最后，如果传递了 Illuminate\Database\Query\Builder，则 Listify 将提取构建器的 where 子句并将其用作 Listify 项目的范围。此范围类型是在尝试保持 acts_as_list 版本和 Listify 之间的兼容性时添加的；然而，由于语言和 ActiveRecord 与 Eloquent 之间的差异，这目前是一个有限的实现，需要改进以更加灵活和安全。这是一个很大的限制，将在即将发布的版本中首先解决。

这很棘手，因为为了使其工作，查询对象的 where 数组在外部 PDO 中准备好了绑定，然后作为原始字符串传递。因此，请记住，如果不小心构建对象，此方法可能会使您的应用程序容易受到滥用。如果您使用直接的用户输入，请在将其用作 Listify 的范围之前对数据进行清理。

示例

class ToDoListItem extends Eloquent
{
    use \Lookitsatravis\Listify\Listify;

    public function __construct(array $attributes = array(), $exists = false) {

        parent::__construct($attributes, $exists);

        $this->initListify([
            'scope' => DB::table($this->getTable())->where('type', '=', 'Not A List of My Favorite Porn Videos')
        ]);
    }
}

结果为一个范围

to_do_list_items.type = 'Not A List of My Favorite Porn Videos'

修改配置

您还可以在运行时通过使用 $this->setListifyConfig('key', 'value'); 来修改任何配置值。例如，要更改作用域，您可以这样做

$this->setListifyConfig('scope', 'what_does_the_fox_say = "ring ding ding ding"');

在处理更新时，将使用原始作用域从该列表中删除记录，并将其插入到新的作用域列表中。请注意。在处理过程中修改配置可能会产生不可预测的影响。

注意

在特性方法内部的所有 position 查询（选择、更新等）都是在不使用默认作用域的情况下执行的，这可以防止当默认作用域与 Listify 作用域不同时出现棘手的问题。

在调用验证后设置 position 列，因此您不应该在 position 列上放置 presence 验证。

未来计划

• 增加支持使用闭包作为作用域
• 更新 Illuminate\Database\Query\Builder 作用域以使其更安全且更具灵活性
• 安装命令的附加功能。例如
  • 自动更新模型（包括构造函数中的初始化方法）
  • 为 Listify 的每个公共方法生成（或添加）控制器，包括添加必要的路由。这将使得通过 AJAX-y 前端调用类似 http://localhost:8000/foos/1/move_lower 的操作变得简单。

除此之外，我还希望根据需要保持与 Ruby gem acts_as_list (https://github.com/swanandp/acts_as_list) 的一致性。

为 Listify 做贡献

• 查看最新主分支以确保功能尚未实现或错误尚未修复
• 查看问题跟踪器以确保尚未有人提出请求并/或做出贡献
• 分支项目
• 开始一个功能/错误修复分支
• 提交并推送，直到您对您的贡献满意
• 确保为它添加测试。这很重要，这样我就不会无意中在未来版本中破坏它。
• 请尽量不修改 Composer.json、版本或历史记录。如果您想有自己的版本，或者在其他情况下是必要的，那是可以的，但请将其隔离到自己的提交中，这样我就可以在它周围 cherry-pick。
• 我建议在 pull request 之前使用 Laravel 5.0 及更高版本进行测试。

版权

版权所有 (c) 2013-2017 Travis Vignon，在 MIT 许可下发布