README

Eloquence是一个扩展Laravel基础Eloquent模型和功能的包。

它提供了一些实用工具和类，以新的和有用的方式使用Eloquent，例如驼峰命名属性（用于JSON API）、计数缓存、UUIDs等。

安装

通过composer安装此包

composer require kirkbushell/eloquence:~4.0

对于Laravel 6，请安装

composer require kirkbushell/eloquence:~3.0

对于Laravel 5，请安装2.0系列版本。

composer require kirkbushell/eloquence:~2.0

对于Laravel 4，请安装1.1.5版本。请注意，这已不再受支持。

composer require kirkbushell/eloquence:1.1.5

使用

首先，将eloquence服务提供者添加到您的config/app.php文件中

'Eloquence\EloquenceServiceProvider',

请注意，这将自动重新绑定Eloquent使用的多对多关系的Model类。这是必要的，因为在实例化Pivot模型时，我们需要它使用父模型的信息和可能需要的特性。

现在您可以使用模型了。

将所有内容转换为驼峰命名！

对于那些喜欢在整个应用程序中使用单一编码标准的人，使用CamelCaseModel特性将确保所有属性、关系以及从Eloquent模型关联的数据都通过API以驼峰命名的方式持久化。这对于正在编写也使用camelCase的前端应用程序非常重要。这可以在我们的应用程序中实现更好的标准。要使用

use \Eloquence\Behaviours\CamelCasing;

将上述行放入您的模型中，就可以了。

注意！

Eloquence不会改变您编写模式迁移的方式。您仍然应在数据库模式迁移中设置字段和表时使用snake_case。这是一个好事 - 字段名称的snake_case是Laravel社区中的事实标准 :)

UUIDs

Eloquence自带UUID功能，您可以在模型中使用。

简单包含Uuid特性

use Eloquence\Behaviours\Uuid;

然后禁用自动递增ID

public $incrementing = false;

这将关闭模型中的ID自动递增，并为ID字段自动生成UUID4值。一个好处是，您实际上可以在记录保存之前就了解其ID！

您必须确保ID列已设置以处理UUID值。可以通过创建具有以下属性的迁移来完成此操作

$table->char('id', $length = 36)->index();

请注意，在您使用UUID功能并确定它适用于您之前，您应该进行一些研究。UUID字段搜索的速度比索引整数字段（如自动递增ID字段）慢得多。

自定义UUIDs

如果您需要自定义UUID解决方案（即，也许您不想使用UUID4 ID），您可以直接在ID字段上定义所需的值。UUID模型特性不会设置ID，如果它已经被定义。然而，在这种情况下，使用Uuid特性可能不是很好，因为这个场景中它几乎是无用的。

行为

Eloquence提供了一套设置行为（即，实际上是您可以与Eloquent模型一起使用的小型库）的系统。第一个就是计数缓存。

计数缓存

计数缓存是指缓存相关表记录计数的操作结果。一个简单的例子是，一个用户拥有许多帖子。在这个例子中，你可能想定期统计一个用户拥有的帖子数量——甚至按这个数量排序。在 SQL 中，按计数字段排序很慢，且无法索引。你可以通过在用户记录中缓存用户创建的帖子数量来解决这个问题。

要使此功能正常工作，你需要执行两个步骤

在模型上使用 Countable 特性
配置计数缓存设置

配置计数缓存

为了设置计数缓存配置，我们需要让模型使用 Countable 特性，如下所示

class Post extends Eloquent {
    use Countable;
    
    public function countCaches() {
        return [User::class];
    }
}

这告诉计数缓存，Post 模型在 User 模型上有一个计数缓存。因此，每当添加、修改或删除帖子时，计数缓存行为将更新相应用户帖子数量的缓存。在这种情况下，它将更新用户模型上的 post_count。

上述示例使用了以下标准约定

post_count 是用户模型表上定义的字段
user_id 是表示帖子模型外键的字段
id 是用户模型表上的主键

然而，这些是可配置的

class Post extends Eloquent {
    use Countable;
    
    public function countCaches() {
        return [
            'num_posts' => ['User', 'users_id', 'id']
        ];
    }
}

此示例使用 num_posts 和 users_id 分别自定义了计数缓存字段和相关的外键。

或者，你可以非常明确地配置（如果你在多个表上使用计数缓存并且每个表上使用相同的列名，这很有用）

class Post extends {
    use Countable;
    
    public function countCaches() {
        return [
            [
                'model'      => 'User',
                'field'      => 'num_posts',
                'foreignKey' => 'users_id',
                'key'        => 'id'
            ]
        ];
    }
}

如果使用显式配置，至少需要定义 "model" 参数。如果省略，则 "countField"、"foreignKey" 和 "key" 参数将使用上述提到的标准约定进行计算。

现在，配置设置已经设置好——你可以开始了！

总和缓存

总和缓存与计数缓存类似，不同之处在于它缓存的不是相关表记录的计数，而是特定字段上的总和。一个简单的例子是，一个订单有多个项目。使用总和缓存，你可以缓存所有项目价格的总额，并将该总额存储在订单表中。

要使此功能正常工作——就像计数缓存一样——你需要执行两个步骤

在模型上使用 Summable 特性
为任何总和缓存配置模型

配置总和缓存

要设置总和缓存配置，只需执行以下操作

class Item extends Eloquent {
    use Summable;
    
    public function sumCaches() {
        return [Order::class];
    }
}

这告诉总和缓存管理器，Item 模型在 Order 模型上有一个总和缓存。因此，每当添加、修改或删除项目时，总和缓存行为将更新相应订单的项目总和缓存。在这种情况下，它将更新订单模型上的 item_total。

上述示例使用了以下约定

item_total 是订单模型表上定义的字段
total 是项目模型表上定义的字段（我们正在求和的列）
order_id 是表示项目模型外键的字段
id 是订单模型表上的主键

然而，这些是可配置的

class Item extends Eloquent {
    use Summable;
    
    public function sumCaches() {
        return [
            'item_total' => ['Order', 'total', 'order_id', 'id']
        ];
    }
}

或者使用详细语法

class Item extends Eloquent {
    use Summable;
    
    public function sumCaches() {
        return [
            [
                'model'       => 'Order',
                'columnToSum' => 'total',
                'field'       => 'item_total'
                'foreignKey'  => 'order_id',
                'key'         => 'id'
            ]
        ];
    }
}

这两个示例都实现了默认设置。

配置这些设置后，每次添加、更新或删除项目时，你将看到相关模型的总和缓存更新。

可滑动模型

Sluggable 是另一种行为，允许轻松添加模型别名。要使用，实现 Sluggable 特性

class User extends Eloquent {
    use Sluggable;

    public function slugStrategy() {
        return 'username';
    }
}

在上面的示例中，将基于用户模型的用户名字段创建一个短链接。然而，还有两种其他短链接也被支持。

id和
uuid

这两者之间的唯一区别是，如果你使用UUID，则短链接将在保存之前基于uuid字段生成。对于通常采用自增策略的ids，短链接必须在记录保存之后生成，这会导致对数据库的二次保存调用。

就是这样！容易吗？

更新日志

8.0.0

版本号提升以匹配Laravel
支持Laravel 7.3+
修复了由Eloquent中的新受保护属性逻辑导致的错误

4.0.1

修复了由Eloquent中的新受保护属性逻辑导致的错误

4.0.0

Laravel 7支持（感谢，@msiemens！）

3.0.0

Laravel 6支持
更好的短链接创建和处理

2.0.7

在创建基于id的短链接时检查短链接的唯一性。

2.0.6

修复了在恢复模型时导致计数缓存值不正确的问题。

2.0.3

短链接现在实现Jsonable，使得它们在API响应中更容易处理
新增 artisan 命令用于重建缓存（beta，请自行承担风险）

2.0.2

更新PHP依赖到5.6+
通过服务层支持CountCache和SumCache行为

2.0.0

添加了Sum缓存模型行为
通过Laravel trait 启动行为
简化所有行为及其用法
更新了readme/配置指南

1.4.0

从模型检索短链接现在返回短链接值对象。

1.3.4

为id策略提供更多随机、更不可预测的短链接。

1.3.3

修复了关系不可通过模型属性访问的问题。

1.3.2

Slugged行为
修复了fillable属性问题

1.3.1

关系修复
修复fillable属性问题
修复了更改关系的计数缓存更新问题
实现计数缓存观察者的小更新

1.3.0

添加了计数缓存模型行为
修复了多对多关系的大小写问题
修复了使用 ::create 时的问题

1.2.0

Laravel 5支持
readme更新

1.1.5

UUID模型trait现在支持自定义UUID（而不仅仅是为你生成它们）

1.1.4

UUID修复

1.1.3

从服务提供者中移除了模式绑定

1.1.2

通过自定义蓝图移除了uuid列的创建

1.1.1

修复了依赖性问题

1.1.0

添加UUIDModel trait
添加CamelCaseModel trait
模型类更新为使用CamelCaseModel trait - 已弃用，仅提供向后兼容支持
Eloquence现在是其自己的命名空间（破坏性更改）
EloquenceServiceProvider添加使用此服务提供者以自动覆盖基本模型（对于需要使用小驼峰命名的pivot模型是必需的）

1.0.2

关系现在支持小驼峰命名检索（感谢 @linxgws）

1.0.1

修复了依赖解析问题

1.0.0

初始实现
模型属性的小驼峰命名现在可用于设置器和获取器

许可证

Laravel框架是开源软件，使用MIT许可证授权。

rdallimore / eloquence

维护者

详细信息