README

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

它提供了一系列实用工具和属性，以新的和有用的方式处理 Eloquent，例如驼峰式属性（例如用于 JSON API 和代码风格一致性）、数据聚合等。

安装

通过 composer 安装软件包

composer require kirkbushell/eloquence

用法

Eloquence 会被 Laravel 自动发现，无需额外步骤。对于使用早期版本 Laravel 的用户，您可以在 config/app.php 文件中按常规添加软件包

'Eloquence\EloquenceServiceProvider',

服务提供者没有做什么，除了配置查询日志。

所有驼峰命名！

对于那些喜欢在整个应用程序中使用单一编码风格的人来说，使用 CamelCased 特性可以确保您确实可以做到这一点。它会实时将所有属性访问从 camelCase 转换为 snake_case，为您应用程序提供统一的编码风格。这意味着从属性访问到 JSON API 响应的所有内容都将被驼峰命名。要使用，只需将 CamelCased 特性添加到您的模型中

use \Eloquence\Behaviours\HasCamelCasing;

注意！

Eloquence 不会更改 您编写模式迁移的方式。您仍然应在数据库模式迁移中设置列和表时使用 snake_case。这是一个好事 - 列名称的 snake_case 是 Laravel 社区的默认标准，并在数据库模式中得到广泛使用。

行为

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

计数缓存

计数缓存是在相关模型的记录上对计数进行缓存。一个简单的例子是，您有属于作者的帖子。在这种情况下，您可能想要经常计算作者拥有的帖子数量，甚至按此数量排序。在 SQL 中，按聚合值排序无法索引，因此 - 慢。您可以通过在作者的模型记录上缓存作者创建的帖子数量来解决这个问题。

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

在子模型（在此例中为 Post）上使用 HasCounts 特性
通过使用 CountedBy 属性配置计数缓存设置

配置计数缓存

要设置计数缓存配置，我们添加 HasCounts 特性，并设置 CountedBy 属性

use Eloquence\Behaviours\CountCache\CountedBy;
use Eloquence\Behaviours\CountCache\HasCounts;
use Illuminate\Database\Eloquent\Model;

class Post extends Model {
    use HasCounts;

    #[CountedBy]
    public function author(): BelongsTo
    {
        return $this->belongsTo(Author::class);
    }
}

这告诉计数缓存行为该模型在 Author 模型上有一个聚合计数缓存。因此，每当添加、修改或删除帖子时，计数缓存行为将更新相应作者的帖子计数缓存。在这种情况下，它会更新作者模型上的 post_count 字段。

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

post_count 是用户模型表上定义的字段

它使用您自己的关系来查找相关记录，因此不需要其他配置！

当然，如果您有不同的设置或不同的字段名称，您可以通过定义适当的字段来更改计数缓存行为，以便更新

class Post extends Model {
    use HasCounts;

    #[CountedBy(as: 'total_posts')]
    public function author(): BelongsTo
    {
        return $this->belongsTo(Author::class);
    }
}

当设置as:值（在此使用PHP 8.0中的命名参数进行说明，以提高可读性）时，您正在告诉计数缓存，Author模型上的聚合字段实际上是total_posts。

HasCounts不仅仅局限于只有一个计数缓存配置。您可以为每个BelongsTo关系定义任意多个，如下所示

#[CountedBy(as: 'total_posts')]
public function author(): BelongsTo
{
    return $this->belongsTo(Author::class);
}

#[CountedBy(as: 'num_posts')]
public function category(): BelongsTo
{
    return $this->belongsTo(Category::class);
}

求和缓存

求和缓存与计数缓存类似，但不同之处在于，它缓存的是子模型对象上的特定字段的总和，而不是相关模型对象的计数。一个简单的例子是，您有一个具有多个项目的订单。使用求和缓存，您可以缓存所有项目的价格总和，并将其作为缓存的总和存储在Order模型上。

要实现这一点——就像计数缓存一样——您需要进行两个步骤

将HasSums添加到您的子模型中，并且
将SummedBy属性添加到每个需要它的关系方法中。

配置求和缓存

要设置求和缓存配置，请执行以下操作

use Eloquence\Behaviours\SumCache\HasSums;
use Eloquence\Behaviours\SumCache\SummedBy;
use Illuminate\Database\Eloquent\Model;

class Item extends Model {
    use HasSums;

    #[SummedBy(from: 'amount', as: 'total_amount')]
    public function order(): BelongsTo
    {
        return $this->belongsTo(Order::class);
    }
}

与可以假设有合理默认值的计数缓存不同，求和缓存需要更多的指导。上面的示例告诉求和缓存，在Item上有一个需要累加到Order上的total_amount字段的amount字段。

缓存建议

由于缓存系统直接与其他模型对象交互，并且需要多次写入数据库，因此强烈建议您将使用缓存的模型保存操作包裹在事务中。在Postgres这样的数据库中，这是自动的，但对于MySQL这样的数据库，您需要确保您正在使用InnoDB这样的事务性数据库引擎。

需要事务的原因是，如果任何查询失败，您的缓存将变得不一致。整个操作失败比这种情况更好。下面是使用Laravel的DB外观进行数据库事务的示例

DB::transaction(function() {
    $post = new Post;
    $post->authorId = $author->id;
    $post->save();
});

如果我们回到上面关于帖子有作者的例子——如果这个保存操作没有包裹在事务中，并且帖子被创建，但出于某种原因数据库立即失败，您将永远不会看到父Author模型中计数缓存的更新，您最终会得到一些难以调试的错误数据。

可生成短链接

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

class User extends Model {
    use HasSlugs;

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

在上面的示例中，将根据User模型的username字段创建一个短链接。还有另外两个支持的短链接

id和
uuid

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

就是这样！简单吧？

从v10升级

Eloquence的版本11是一个完全重建，并从原始代码库中分离出来，而是利用PHP 8.1属性，并在可能的情况下避开特性/类扩展。这意味着在某些项目中，许多更新需要确保您的Eloquence使用继续工作。

1. 类重命名

Camelcasing已重命名为HasCamelCasing
Sluggable已重命名为HasSlugs

2. 缓存工作方式的更新

您需要对上面的指南进行修改，以修改所有缓存实现。但简而言之，您需要导入并应用提供的属性到需要聚合缓存值的模型上的关系方法。

关于Eloquence新架构的最好之处在于，您可以按照自己的意愿定义关系！如果您有自定义的WHERE子句或其他限制关系的条件，Eloquence会尊重这一点。这使得Eloquence现在比以往任何时候都更强大，更能支持个别领域需求。

让我们用一个真实案例来说明。这是旧的方法，以Countable为例

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

要将它迁移到v11，我们会做以下操作

use Eloquence\Behaviours\CountCache\CountedBy;

class Post extends Model
{
    use \Eloquence\Behaviours\CountCache\HasCounts;
    
    #[CountedBy(as: 'num_posts')]
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

请注意，所需的配置几乎没有。同样适用于求和的行为 - 简单地将您的配置从缓存函数迁移到您希望有聚合缓存值的关系的上方属性。

变更日志

11.0.3

修复了删除关系时计数缓存的错误（#118）
已识别并应用了一个类似的修复程序，用于修复求和缓存

11.0.2

修复了关系未返回的bug

11.0.1

修复了依赖错误，以支持Laravel 11

11.0.0

Eloquent库的全面重写 - 版本11不兼容回退
UUID支持已移除 - 现在Laravel原生支持UUID和ULID，并且已经支持一段时间了
缓存系统现在直接与模型及其关系一起工作，允许对它所工作的模型进行细粒度控制
已删除控制台命令 - 如果有问题，可以使用Model::rebuildCache()重建模型缓存
修复了计数缓存和求和缓存中的多个bug
将CamelCasing重命名为CamelCased
语法、风格和标准都进行了现代化

10.0.0

版本号提升以匹配Laravel
支持Laravel 10.0+
将日期转换替换为标准的Laravel转换（https://laravel.net.cn/docs/10.x/upgrade#model-dates-property）

9.0.0

版本号提升以匹配Laravel
支持Laravel 9.0+
更新为要求PHP 8.1+
解决了方法弃用警告

8.0.0

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

4.0.1

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

4.0.0

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

3.0.0

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

2.0.7

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

2.0.6

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

2.0.3

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

2.0.2

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

2.0.0

添加了Sum缓存模型行为
现在通过Laravel特质引导来引导行为
简化了所有行为及其使用
更新了README/配置指南

1.4.0

从模型检索的slugs现在返回Slug值对象。

1.3.4

为id策略提供更多随机、更不可预测的slugs

1.3.3

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

1.3.2

Slugged行为
修复了fillable属性

1.3.1

修复了关系
修复了fillable属性bug
修复了更改关系时计数缓存更新的bug
实现计数缓存观察器的微小更新

1.3.0

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

1.2.0

支持Laravel 5
更新了README

1.1.5

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

1.1.4

修复了UUID

1.1.3

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

1.1.2

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

1.1.1

修复了依赖bug

1.1.0

添加了UUIDModel特质
添加了CamelCaseModel特质
将模型类更新为使用CamelCaseModel特质 - 已弃用，仅提供回退兼容性支持
Eloquence现在是自己的命名空间（破坏性更改）
EloquenceServiceProvider已添加，如果您想自动覆盖基础模型（对于复杂数据模型需要驼峰命名），请使用此功能。

1.0.2

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

1.0.1

修复了依赖解析问题

1.0.0

初始实现
模型属性的驼峰命名现在对setter和getter都适用

许可证

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

kirkbushell / eloquence

维护者

详细信息