Laravel MongoDB Eloquent 模型实战指南:从 `_id`、ObjectId 转换到加密字段的完整用法
Laravel MongoDB Eloquent 模型实战指南:从 _id、ObjectId 转换到加密字段的完整用法
本文围绕 laravel-mongodb 包的 Eloquent 模型层展开,讲解如何基于 MongoDB 编写文档模型:正确选择基类与
DocumentModeltrait、理解_id与id的关系、为外键配置 ObjectId 转换、在非 MongoDB 基类上复用文档能力,以及使用encrypted转换实现字段加密。读完后,你将能独立设计、调试并产出可直接运行的 MongoDB 文档模型,并知道每个关键结论对应的源码位置。
一、为什么不能直接用标准 Eloquent 基类
MongoDB 的文档模型与 SQL 表模型有一个根本差异:标准 Eloquent 的 Illuminate\Database\Eloquent\Model 面向关系型数据库设计,不理解 BSON 类型(ObjectId、UTCDateTime、Binary、Decimal128 等)。因此,laravel-mongodb 包提供了一整套继承自 Laravel Eloquent 的模型实现,正确写法如下:
// WRONG — standard Eloquent does not understand MongoDB types
use Illuminate\Database\Eloquent\Model;
// CORRECT
use MongoDB\Laravel\Eloquent\Model;
MongoDB\Laravel\Eloquent\Model(src/Eloquent/Model.php)是一个抽象类,继承 Laravel 的 BaseModel 并 use DocumentModel trait。它在默认情况下已经做好了两件关键的事:
$keyType = 'string':主键类型默认为字符串。ObjectId 在 PHP 侧以字符串形式呈现,因此「字符串」是文档模型的主键默认形态。- 集成
HybridRelations与EmbedsRelations两个 trait(见 src/Eloquent/DocumentModel.php),分别提供跨 MongoDB/SQL 连接的混合关系与内嵌文档关系能力。
一个最小可用的文档模型长这样:
<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
final class Movie extends Model
{
protected $connection = 'mongodb';
protected $table = 'movies'; // $table not $collection
protected $keyType = 'string'; // ObjectId surfaced as string (already default)
protected $fillable = ['title', 'year', 'released_at'];
protected $casts = [
'year' => 'integer',
'released_at' => 'datetime',
// Do NOT cast native MongoDB arrays to 'array' — stored natively;
// 'array' cast triggers deprecation and may serialize as JSON.
];
}
注意 $table 而非 $collection:为了贴合 Laravel 开发者习惯,包沿用 Eloquent 的 $table 属性来指定 MongoDB 集合名。keyType 即便不写也默认是 'string',写上便于显式表达意图。
集合名与属性声明的补充:#[Table] 属性
如果你使用 Laravel 13+,DocumentModel 还会读取 Illuminate\Database\Eloquent\Attributes\Table 属性来初始化模型属性。initializeModelAttributes() 会解析 keyType 并覆盖默认值(src/Eloquent/DocumentModel.php)。测试 tests/Eloquent/ModelAttributesTest.php 覆盖了 #[Table('custom_collection')] 设置集合名、主键、keyType 等场景,并验证「显式声明的 $keyType 属性优先于 #[Table] 属性」(testKeyTypePropertyTakesPrecedenceOverTableAttribute)。这意味着:属性声明是便捷写法,但传统属性仍是权威来源。
二、_id 与 id:一个字段,两种读法
BSON 层面,文档主键字段是 _id(默认 ObjectId,但 BSON 允许任意类型作为 _id)。包在 PHP 侧同时暴露 $model->id 和 $model->_id 两种访问方式,让模型用起来更接近 SQL 习惯。
这一行为的实现位于 src/Eloquent/DocumentModel.php 的 getIdAttribute():当 id 没有对应属性值时,回退到 _id 属性;如果值是 MongoDB\BSON\ObjectID 则转换为字符串,如果是 Binary 则取出二进制数据转字符串。因此在模型代码里,$model->id 与 $model->_id 是等价的:
public function toArray(Request $request): array
{
return [
'id' => (string) $this->_id, // or $this->id — equivalent
'title' => $this->title,
];
}
为什么 API 资源里必须转字符串
在 toArray()(或 API Resource)中强制 (string) 转换非常关键:如果不转,_id 的 ObjectId 会被序列化成扩展 JSON 形态 {"$oid":"6708..."},而不是客户端期望的裸字符串 "6708..."。attributesToArray() 同样会在数组/JSON 输出时把 ObjectId 与 Binary 统一转为字符串(src/Eloquent/DocumentModel.php),与 SQL 模型输出标量的行为对齐。
主键写入时的智能转换
当给 id / _id 赋值一个恰好 24 位的十六进制字符串时,setAttribute() 会通过查询构造器的 convertKey() 把它转换为原生 ObjectID(src/Eloquent/DocumentModel.php、src/Query/Builder.php)。转换逻辑是:24 位且全部为十六进制字符 → ObjectID;16 位且含不可打印字符 → UUID Binary;其余原样保留。此外,convertKey() 内部的 assertKeyIsNotOperator() 会拒绝包含 $ 前缀键的数组作为主键,防止将 MongoDB 操作符注入文档主键(复合 _id 的普通数组仍被允许)。
三、外键与 ObjectId 转换:让 belongsTo() 稳定匹配
Eloquent 在关系匹配时会做类型强制转换(coercion),因此 belongsTo() 即使不写任何转换也能工作:$author->id 是字符串,$book->author_id 也以字符串形态参与匹配。这一点在测试中有直接体现:RelationsTest 中 Book::create(<a href="https://link.gitcode.com/i/e4e6b54db77293fb9bb8b492187116f5" target="_blank">'title' => ..., 'author_id' => $author->id]) 之后断言 $author->id === $book->author_id(见 [tests/RelationsTest.php)。
但当外键值可能来自模型属性之外(数据导入、直接拿到的原生 ObjectId)时,就需要显式声明转换,保证写入时 BSON 类型被归一化、where() 直接查询不会因类型不匹配而查不到数据:
protected $casts = [
'author_id' => 'string', // simplest: store/read as string for Eloquent matching
// OR preserve native BSON ObjectId:
// 'author_id' => MongoDB\Laravel\Eloquent\Casts\ObjectId::class,
// (use the package cast, NOT \MongoDB\BSON\ObjectId::class)
];
两种策略各有取舍:
| 策略 | $casts 声明 |
写入形态 | 适用场景 |
|---|---|---|---|
| 字符串归一化 | 'author_id' => 'string' |
字符串 | 追求与 Eloquent 匹配逻辑一致、可读性好 |
| 原生 ObjectId | 'author_id' => ObjectId::class |
BSON ObjectId | 数据来自原生 ObjectId、需要保持 BSON 原貌 |
包级 ObjectId cast 的底层行为
MongoDB\Laravel\Eloquent\Casts\ObjectId(src/Eloquent/Casts/ObjectId.php)实现了 Laravel 的 CastsAttributes 接口:
get():如果底层值已是MongoDB\BSON\ObjectId,转为字符串返回;set():如果传入的不是 ObjectId,则new BSONObjectId($value)构造原生 ObjectId 落库。
文档特别强调:必须使用包的 cast(MongoDB\Laravel\Eloquent\Casts\ObjectId::class),而不是 \MongoDB\BSON\ObjectId::class——后者只是 BSON 类型类,并不实现 Eloquent 的 cast 契约,直接使用会报错或行为不符。
配套测试 tests/Casts/ObjectIdTest.php 验证了关键行为:
- 用 ObjectId 或字符串保存,再用 ObjectId 查询都能命中(
testStoreObjectId两个用例); - 若字段以原生 ObjectId 落库,却用字符串去
firstWhere('oid', $stringObjectId)查询,会查不到结果(testQueryByStringDoesNotCast)——这正是文档「防止where()直接查询失配」的由来。测试模型 tests/Models/CastObjectId.php 中'oid' => ObjectId::class即官方用法示范。
相关:UUID 主键的 BinaryUuid cast
同类场景还包括 MongoDB\Laravel\Eloquent\Casts\BinaryUuid(src/Eloquent/Casts/BinaryUuid.php):get() 将 UUID 二进制还原成标准连字符格式,set() 把字符串或 16 字节二进制包装成 Binary::TYPE_UUID。如果需要用 UUID 而非 ObjectId 做主键,可参照 tests/Models/IdIsBinaryUuid.php 与 tests/Casts/BinaryUuidTest.php 的用法。
四、扩展非 MongoDB 基类:用 DocumentModel trait 组合复用
如果你必须继承第三方包的基类(比如自定义的审计基类、多租户基类),无法改为继承 MongoDB\Laravel\Eloquent\Model,可以退而使用 DocumentModel trait——它承载了全部 MongoDB 文档模型能力:
<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\DocumentModel;
use Vendor\Package\BaseModel;
final class AuditLog extends BaseModel
{
use DocumentModel;
protected $connection = 'mongodb';
protected $table = 'audit_logs';
protected $keyType = 'string';
}
DocumentModel 聚合了 HybridRelations、EmbedsRelations、点号嵌套属性读写、_id 别名、$unset 字段删除、push/pull 数组操作、UTC 时间戳、ObjectID/Binary 序列化、加密字段保护等全部文档模型特性(src/Eloquent/DocumentModel.php)。测试 tests/Eloquent/ModelTest.php 中 Model::isDocumentModel() 的判定逻辑也印证了这一点:一个模型要成为「文档模型」,必须是 Laravel BaseModel 的子类 并且 使用 DocumentModel trait(匿名类 new class extends BaseModel { use DocumentModel; } 判为 true,而 new class extends BaseModel {} 判为 false)。仓库内置的认证模型 src/Auth/User.php 正是「继承 Illuminate\Foundation\Auth\User + use DocumentModel」的真实范例。
五、加密转换:encrypted 与应用级 vs 服务端加密
laravel-mongodb 直接兼容 Laravel 自带的 encrypted cast,用于把字段加密后写入 MongoDB:
protected $casts = [
'ssn' => 'encrypted', // Laravel encrypted cast; use Queryable Encryption for server-side equality
];
文档特别提醒:encrypted 是应用级加密(使用 Laravel Encrypter、APP_KEY),适用于「读取时才解密」的字段;如果需要在服务端按字段值做等值查询(如按身份证号查询),则应改用 MongoDB 的 Queryable Encryption,两者用途不同。
源码印证:加密在模型中如何流转
- 加密转换的常规流转由 Laravel
HasAttributes完成;laravel-mongodb 在此基础上补充了getRawOriginal()可见的密文与Json::decode解密两种断言路径。测试 tests/Casts/EncryptionTest.php 对字符串、数组、对象、集合四种形态做了完整验证:写入后getRawOriginal($key)拿到的是密文,用Encrypter::decryptString()能还原明文,encrypted:array、encrypted:object、encrypted:collection分别对应Casting测试模型的数组/对象/集合加密(tests/Models/Casting.php)。 - 与 Queryable Encryption 的衔接由 src/Encryption/AutoEncryption.php 承担:当连接配置了
keyVaultNamespace时启用加密(isEncryptionEnabled()),并禁止应用写入服务端托管字段__safeContent__——setAttribute()与offsetUnset()都会对__safeContent__及其实点号子路径抛出MassAssignmentException(src/Eloquent/DocumentModel.php),确保该字段只能由服务端维护。 - 参考模型 tests/Models/EncryptedUser.php 展示了 Queryable Encryption 教程中的典型做法:加密字段在连接的
encryptedFieldsMap中声明(name 随机化、email/phone 等值、date_of_birth 范围),模型里只保留'password' => 'hashed'这类常规转换,并protected $hidden = ['password', 'remember_token']避免泄露。
六、常用 cast 与「数组」警告的进阶说明
文档模型对 Laravel 原生 cast 的适配是渐进的,以下几点在实操中值得注意:
- 原生数组与
'array'cast 的冲突:MongoDB 原生存储数组,如果给数组字段加'array'cast,会被序列化成 JSON 字符串而非 BSON 数组。DocumentModel::isJsonCastable()检测到arraycast 时会触发E_USER_DEPRECATED弃用警告,提示移除 cast 以存储原生 BSON 数组,或显式改用jsoncast(src/Eloquent/DocumentModel.php)。文档中Movie模型的注释即为此意。 - 需要保 BSON 数组/文档形态时,可使用包提供的 AsBsonArray 与 AsBsonDocument:它们在读写时构造
BSONArray/BSONDocument,并在 dirty 比较时按 BSON 序列化归一化(compare()),可避免因对象包装差异导致的「误判为已修改」。 - 日期与时间戳:
freshTimestamp()返回UTCDateTime,fromDateTime()把DateTimeInterface转为UTCDateTime落库,读取时asDateTime()将UTCDateTime还原为 Carbon 并转回应用时区(src/Eloquent/DocumentModel.php)。因此'released_at' => 'datetime'这类 cast 在 MongoDB 下语义与 SQL 一致,且支持datetime:Y-m-d自定义格式。 - decimal 支持:
'decimal:2'这类 cast 在写入时会被转换为原生MongoDB\BSON\Decimal128(fromDecimal(),见 src/Eloquent/DocumentModel.php),读取时还原为字符串,规避浮点精度问题。
七、模型中的文档特有操作与安全护栏
DocumentModel 还带来一批 SQL 模型没有的文档级操作,它们在编写模型代码时会经常用到:
unset($columns)(以及已弃用的drop()):标记字段在下次save()时通过$unset从文档中移除。offsetUnset()会记录到$unset列表,getDirty()会把<a href="https://link.gitcode.com/i/3bbbf9e4e6edde50c069b8ebc15aced4" target="_blank">'$unset' => [...]]并入 dirty 数据([src/Eloquent/DocumentModel.php)。push($column, $values, $unique)/pull($column, $values):直接对数组字段追加/移除元素,底层转化为查询构造器的$push/$pull操作(src/Eloquent/DocumentModel.php)。- 点号属性支持:
setAttribute()用临时键把profile.name这类点号键写入嵌套文档,getAttribute()与getAttributeFromArray()也支持点号读取(src/Eloquent/DocumentModel.php)。测试模型 tests/Models/User.php 中'entry.date' => 'datetime'即为嵌套字段 cast 的官方示例。 - 主键安全:
assertKeyIsNotOperator()拒绝$前缀键数组作为_id,从模型层杜绝 MQL 操作符注入主键(src/Query/Builder.php)。
八、快速落地:从连接配置到模型清单
要让上述模型真正跑起来,还需确认连接配置。包默认走 mongodb 连接,在 config/database.php 中注册(完整示例见 resources/boost/skills/laravel-mongodb/references/connection.md):
'connections' => [
'mongodb' => [
'driver' => 'mongodb',
'dsn' => env('MONGODB_URI', 'mongodb://localhost:27017'),
'database' => env('MONGODB_DATABASE', 'laravel'),
'options' => [
'appName' => env('APP_NAME', 'laravel'),
],
],
],
.env 中对应:
DB_CONNECTION=mongodb
MONGODB_URI="mongodb+srv://user:pass@cluster0.mongodb.net/?retryWrites=true&w=majority"
MONGODB_DATABASE=laravel
服务提供者 MongoDB\Laravel\MongoDBServiceProvider 会通过包发现自动注册(需手动注册时写入 bootstrap/providers.php)。池大小、超时与 TLS 等参数统一放入连接 URI(如 serverSelectionTimeoutMS=5000&socketTimeoutMS=30000);注意 maxPoolSize/minPoolSize 对 PHP 扩展无效——libmongoc 在单线程模式下每个服务器最多持有一个 socket、无连接池(见 resources/boost/skills/laravel-mongodb/references/connection.md)。
小结
本文从五个核心实践点出发梳理了 laravel-mongodb 的 Eloquent 模型层:选用 MongoDB\Laravel\Eloquent\Model 基类、理解 _id/id 双别名与字符串序列化、用 string 或包级 ObjectId cast 稳定外键匹配、通过 DocumentModel trait 扩展现有基类、按需使用 encrypted 或 Queryable Encryption。配合 src/Eloquent/Model.php、src/Eloquent/DocumentModel.php、src/Eloquent/Casts/ObjectId.php 及 tests/Casts/ObjectIdTest.php、tests/Casts/EncryptionTest.php、tests/Eloquent/ModelTest.php 等源码与测试,你可以逐一验证每个行为,并按本文模板直接落地自己的 MongoDB 文档模型。