MongoDB Laravel Eloquent 模型类深度解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00136/article/details/148464844

MongoDB Laravel Eloquent 模型类深度解析

laravel-mongodb A MongoDB based Eloquent model and Query builder for Laravel (Moloquent) 项目地址: https://gitcode.com/gh_mirrors/la/laravel-mongodb

概述

在 Laravel 生态系统中，Eloquent ORM 是处理关系型数据库的核心组件。而 MongoDB Laravel 扩展包则让开发者能够使用熟悉的 Eloquent 语法来操作 MongoDB 文档数据库。本文将深入探讨如何定义和定制 Eloquent 模型类以适配 MongoDB 的特性。

基础模型定义

要创建一个 MongoDB 兼容的 Eloquent 模型，需要继承特定的基类：

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Planet extends Model
{
    // 模型逻辑
}

关键点说明：

必须继承 MongoDB\Laravel\Eloquent\Model 而非 Laravel 默认的 Eloquent 模型
模型默认对应集合名称为类名的蛇形复数形式（如 Planet → planets）
使用项目配置中指定的 MongoDB 数据库连接

认证模型定制

MongoDB 也可以作为 Laravel 的用户认证存储：

namespace App\Models;

use MongoDB\Laravel\Auth\User as Authenticatable;

class User extends Authenticatable
{
    // 认证相关逻辑
}

这种模型支持 Laravel 的所有认证功能，包括密码重置、记住我等特性。

模型高级定制

集合名称自定义

覆盖 $table 属性可指定自定义集合名称：

protected $table = 'celestial_body';

主键设置

MongoDB 默认使用 _id 作为主键，但可以自定义：

protected $primaryKey = 'name';
protected $keyType = 'string';  // 必须设置为字符串类型

软删除实现

通过引入 SoftDeletes trait 实现软删除：

use MongoDB\Laravel\Eloquent\SoftDeletes;

class Planet extends Model
{
    use SoftDeletes;
}

软删除后文档不会被真正删除，而是设置 deleted_at 时间戳。

数据类型转换

MongoDB 的 BSON 类型与 PHP 类型间的自动转换：

protected $casts = [
    'discovery_dt' => 'datetime',
    'is_habitable' => 'boolean'
];

特别说明：从 v5.0 开始，日期类型会自动转换为 Carbon 实例。

批量赋值保护

防止不安全的大规模属性赋值：

protected $fillable = ['name', 'gravitational_force'];
// 或
protected $guarded = ['secret_field'];

安全建议：优先使用 $fillable 白名单方式。

第三方模型集成

通过 DocumentModel trait 可以让第三方模型兼容 MongoDB：

use ThirdPartyPackage\CelestialBody;
use MongoDB\Laravel\Eloquent\DocumentModel;

class Planet extends CelestialBody
{
    use DocumentModel;
    protected $keyType = 'string'; // 必须设置
}

数据清理策略

可清理模型

定期清理过期数据的实现方式：

use MongoDB\Laravel\Eloquent\Prunable;

class Planet extends Model
{
    use Prunable;
    
    public function prunable()
    {
        return static::where('created_at', '<=', now()->subYears(1));
    }
}

批量清理模型

更高效的直接删除方式：

use MongoDB\Laravel\Eloquent\MassPrunable;

class Planet extends Model
{
    use MassPrunable;
}

模式版本控制

处理集合结构演变的解决方案：

use MongoDB\Laravel\Eloquent\HasSchemaVersion;

class PlanetV2 extends Model
{
    use HasSchemaVersion;
    
    const SCHEMA_VERSION = 2;
    
    public function migrateSchema()
    {
        if ($this->schema_version < 2) {
            $this->galaxy = 'Milky Way';
        }
    }
}

版本控制流程：