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 模型表上定义的字段
user_id 是表示 post 模型外键的字段
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 模型上有一个求和缓存。因此，每当添加、修改或删除项目时，求和缓存行为将更新适当订单的项目求和缓存。在这种情况下，它将更新 Order 模型上的 item_total。

上述示例使用了以下约定：

item_total 是 Order 模型表上定义的字段
total 是 Item 模型表上定义的字段（我们正在对其进行求和的列）
order_id 是表示 item 模型外键的字段
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 是另一种行为，允许轻松添加模型别名。要使用，实现 Sluggable 特性

class User extends Eloquent {
    use Sluggable;

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

在上面的示例中，将根据用户模型的用户名字段创建一个别名。然而，还有两个其他别名也是支持的。

id 和
uuid

这两个之间的唯一区别是，如果您使用 UUID，别名将在保存之前根据 uuid 字段生成。对于通常是自增策略的 id，别名必须在记录保存后生成，这会导致对数据库的二次保存调用。

就是这样！简单吧？

变更日志

8.0.0

版本号提升以匹配 Laravel
支持 Laravel 7.3+
修复了由 Eloquent 中的新 guarded 属性逻辑导致的 bug

4.0.1

修复了由 Eloquent 中的新 guarded 属性逻辑导致的 bug

4.0.0

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

3.0.0

Laravel 6 支持
更好的别名创建和处理

2.0.7

在创建基于 id 的别名时检查别名的唯一性。

2.0.6

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

2.0.3

别名现在实现 Jsonable，使其在 API 响应中更容易处理
新增 artisan 命令用于重建缓存（beta，使用风险自担）

2.0.2

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

2.0.0

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

1.4.0

从模型检索别名时现在返回 Slug 值对象。

1.3.4

基于 id 策略的别名更随机、更不可预测

1.3.3

修复了无法通过模型属性访问关系的问题

1.3.2

Slugged 行为
修复了 fillable 属性的问题

1.3.1

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

1.3.0

添加了 Count cache 模型行为
修复了多对多关系的 casing 问题
修复了使用 ::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

修复了依赖项 bug

1.1.0

添加了 UUIDModel trait
添加了 CamelCaseModel trait
更新了模型类以使用 CamelCaseModel trait - 已弃用，仅提供向后兼容支持
Eloquence 现在其自己的命名空间（破坏性更改）
EloquenceServiceProvider 添加，如果您想自动覆盖基础模型，请使用此服务提供者（对于 pivot 模型 camel casing 是必需的）

1.0.2

关系现在支持 camelCasing 以进行检索（感谢 @linxgws）

1.0.1

修复了依赖项解析问题

1.0.0

初始实现
模型属性的 camel casing 现在对于设置器和获取器都是可用的

许可

Laravel 框架是开源软件，许可协议为 MIT 协议。

xetaio / eloquence

维护者

详细信息