acedude / mongodb
基于 MongoDB 的 Laravel Eloquent 模型和查询构建器 (Moloquent)
Requires
- illuminate/container: ^5.5
- illuminate/database: ^5.5
- illuminate/events: ^5.5
- illuminate/support: ^5.5
- mongodb/mongodb: ^1.0.0
Requires (Dev)
- doctrine/dbal: ^2.5
- mockery/mockery: ^0.9
- orchestra/testbench: ^3.1
- phpunit/phpunit: ^6.0
- satooshi/php-coveralls: ^1.0
Suggests
- jenssegers/mongodb-sentry: Add Sentry support to Laravel-MongoDB
- jenssegers/mongodb-session: Add MongoDB session support to Laravel-MongoDB
- dev-master
- 4.2.x-dev
- v3.3.1
- v3.3.0
- v3.3.0-alpha
- v3.2.4
- v3.2.3
- v3.2.2
- v3.2.1
- v3.2.0
- v3.1.4
- v3.1.3
- v3.1.2
- v3.1.1
- v3.1.0
- v3.1.0-alpha
- v3.0.2
- v3.0.1
- v3.0.0
- v3.0.0-beta
- v3.0.0-alpha
- 2.3.x-dev
- v2.3.5
- v2.3.4
- v2.3.3
- v2.3.2
- v2.3.1
- v2.3.0
- 2.2.x-dev
- v2.2.10
- v2.2.9
- v2.2.8
- v2.2.7
- v2.2.6
- v2.2.5
- v2.2.4
- v2.2.3
- v2.2.2
- v2.2.1
- v2.2.0
- 2.1.x-dev
- v2.1.9
- v2.1.8
- v2.1.7
- v2.1.6
- v2.1.5
- v2.1.4
- v2.1.3
- v2.1.2
- v2.1.1
- v2.1.0
- v2.1.0-beta
- 2.0.x-dev
- v2.0.5
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v2.0.0-alpha
- v1.4.3
- v1.4.2
- v1.4.1
- v1.4.0
- v1.3.2
- v1.3.1
- v1.3.0
- v1.2.9
- v1.2.8
- v1.2.7
- v1.2.6
- v1.2.5
- v1.2.4
- v1.2.3
- v1.2.2
- v1.2.1
- v1.2.0
- v1.1.4
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.8
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- dev-323-fixed-reminders
- dev-analysis-8AbARP
- dev-analysis-zEPlGG
- dev-develop
This package is not auto-updated.
Last update: 2024-09-29 04:48:54 UTC
README
支持 MongoDB 的 Eloquent 模型和查询构建器,使用原始 Laravel API。 这个库扩展了原始 Laravel 类,因此使用完全相同的方法。
目录
安装
请确保已安装 MongoDB PHP 驱动。您可以在 https://php.ac.cn/manual/en/mongodb.installation.php 找到安装说明。
警告:旧版 mongo PHP 驱动程序不再支持 >= 3.0 版本。
使用 composer 安装
composer require jenssegers/mongodb
Laravel 版本兼容性
并在 config/app.php
中添加服务提供者
Jenssegers\Mongodb\MongodbServiceProvider::class,
对于与 Lumen 的使用,在 bootstrap/app.php
中添加服务提供者。在此文件中,您还需要启用 Eloquent。但是,您必须确保您的 $app->withEloquent();
调用 在 注册 MongodbServiceProvider
下方。
$app->register(Jenssegers\Mongodb\MongodbServiceProvider::class); $app->withEloquent();
服务提供者将在原始数据库管理器中注册一个 mongodb 数据库扩展。无需注册额外的外观或对象。当使用 mongodb 连接时,Laravel 将自动为您提供相应的 mongodb 对象。
对于 Laravel 以外的使用,请查看 Capsule manager 并添加
$capsule->getDatabaseManager()->extend('mongodb', function($config) { return new Jenssegers\Mongodb\Connection($config); });
升级
从版本 2 升级到 3
在这个新的大版本中,我们支持新的 mongodb PHP 扩展,并将模型类的位置移动,用 trait 替换了 MySQL 模型类。
请将所有 Jenssegers\Mongodb\Model
引用更改为 Jenssegers\Mongodb\Eloquent\Model
,无论是在模型文件顶部还是在注册的别名中。
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class User extends Eloquent {}
如果您正在使用混合关系,则您的 MySQL 类现在应该扩展原始 Eloquent 模型类 Illuminate\Database\Eloquent\Model
而不是已删除的 Jenssegers\Eloquent\Model
。相反,使用新的 Jenssegers\Mongodb\Eloquent\HybridRelations
trait。这应该使事情更清晰,因为在这个包中只有一个模型类。
use Jenssegers\Mongodb\Eloquent\HybridRelations; class User extends Eloquent { use HybridRelations; protected $connection = 'mysql'; }
嵌入式关系现在返回一个 Illuminate\Database\Eloquent\Collection
而不是自定义集合类。如果您正在使用其中一些特殊方法,请将它们转换为集合操作。
$books = $user->books()->sortBy('title');
配置
在 config/database.php
中更改默认数据库连接名称
'default' => env('DB_CONNECTION', 'mongodb'),
并添加一个新的 mongodb 连接
'mongodb' => [ 'driver' => 'mongodb', 'host' => env('DB_HOST', 'localhost'), 'port' => env('DB_PORT', 27017), 'database' => env('DB_DATABASE'), 'username' => env('DB_USERNAME'), 'password' => env('DB_PASSWORD'), 'options' => [ 'database' => 'admin' // sets the authentication database required by mongo 3 ] ],
您可以使用以下配置连接到多个服务器或副本集
'mongodb' => [ 'driver' => 'mongodb', 'host' => ['server1', 'server2'], 'port' => env('DB_PORT', 27017), 'database' => env('DB_DATABASE'), 'username' => env('DB_USERNAME'), 'password' => env('DB_PASSWORD'), 'options' => [ 'replicaSet' => 'replicaSetName' ] ],
或者,您可以使用 MongoDB 连接字符串
'mongodb' => [ 'driver' => 'mongodb', 'dsn' => env('DB_DSN'), 'database' => env('DB_DATABASE'), ],
请参阅 MongoDB 官方文档以获取其 URI 格式: https://docs.mongodb.com/manual/reference/connection-string/
Eloquent
此包包含一个启用了 MongoDB 的 Eloquent 类,您可以使用它来为相应的集合定义模型。
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class User extends Eloquent {}
请注意,我们没有告诉 Eloquent 为 User
模型使用哪个集合。就像原始 Eloquent 一样,除非明确指定,否则类的名称将用作集合名称(小写复数)。您可以通过在模型上定义 collection
属性来指定自定义集合(表别名)。
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class User extends Eloquent { protected $collection = 'users_collection'; }
注意: Eloquent 还会假设每个集合都有一个名为 id 的主键列。您可以通过定义 primaryKey
属性来覆盖此约定。同样,您也可以定义 connection
属性来覆盖在利用模型时应使用的数据库连接的名称。
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class MyModel extends Eloquent { protected $connection = 'mongodb'; }
其余(应该)与原始 Eloquent 模型的工作方式相同。更多关于 Eloquent 的信息请参阅 https://laravel.net.cn/docs/eloquent
可选:别名
您还可以通过在 config/app.php
中的别名数组中添加以下内容来注册 MongoDB 模型的别名
'Moloquent' => Jenssegers\Mongodb\Eloquent\Model::class,
这将允许您像使用以下注册的别名一样使用
class MyModel extends Moloquent {}
查询构建器
数据库驱动程序直接集成到原始查询构建器中。当使用 mongodb 连接时,您将能够构建流畅的查询以执行数据库操作。为了您的方便,还有 collection
别名以及一些额外的 mongodb 特定的操作符/操作。
$users = DB::collection('users')->get(); $user = DB::collection('users')->where('name', 'John')->first();
如果您没有更改默认的数据库连接,您在查询时需要指定它。
$user = DB::connection('mongodb')->collection('users')->get();
更多关于查询构建器的信息请参阅 https://laravel.net.cn/docs/queries
模式
数据库驱动程序也提供了(有限)的架构构建器支持。您可以轻松地操作集合并设置索引
Schema::create('users', function($collection) { $collection->index('name'); $collection->unique('email'); });
支持的运算包括
- 创建和删除
- 集合
- hasCollection
- 索引和删除索引(支持复合索引)
- 唯一
- 后台、稀疏、过期、地理空间(MongoDB 特定)
所有其他(不受支持)的操作都作为虚拟透传方法实现,因为 MongoDB 不使用预定义的架构。更多关于架构构建器的信息请参阅 https://laravel.net.cn/docs/schema
地理空间索引
地理空间索引对于基于位置的文档查询非常有用。它们有两种形式:2d
和 2dsphere
。使用架构构建器将这些添加到集合中。
添加 2d
索引
Schema::create('users', function($collection) { $collection->geospatial('name', '2d'); });
添加 2dsphere
索引
Schema::create('users', function($collection) { $collection->geospatial('name', '2dsphere'); });
扩展
身份验证
如果您想使用 Laravel 的原生身份验证功能,请注册此包含的服务提供程序
'Jenssegers\Mongodb\Auth\PasswordResetServiceProvider',
此服务提供程序将略微修改内部 DatabaseReminderRepository,以添加基于 MongoDB 的密码提醒支持。如果您不使用密码提醒,您无需注册此服务提供程序,其他所有内容应该都能正常工作。
队列
如果您想将 MongoDB 作为数据库后端使用,请更改 config/queue.php
中的驱动程序
'connections' => [ 'database' => [ 'driver' => 'mongodb', 'table' => 'jobs', 'queue' => 'default', 'expire' => 60, ],
如果您想使用 MongoDB 处理失败的作业,请更改 config/queue.php
中的数据库
'failed' => [ 'database' => 'mongodb', 'table' => 'failed_jobs', ],
并在 config/app.php
中添加服务提供者
Jenssegers\Mongodb\MongodbQueueServiceProvider::class,
Sentry
如果您想使用 Sentry,请查看 https://github.com/jenssegers/Laravel-MongoDB-Sentry
会话
MongoDB 会话驱动程序可在单独的包中找到,请查看 https://github.com/jenssegers/Laravel-MongoDB-Session
示例
基本用法
检索所有模型
$users = User::all();
通过主键检索记录
$user = User::find('517c43667db388101e00000f');
Where
$users = User::where('votes', '>', 100)->take(10)->get();
Or 语句
$users = User::where('votes', '>', 100)->orWhere('name', 'John')->get();
And 语句
$users = User::where('votes', '>', 100)->where('name', '=', 'John')->get();
使用数组中的 Where In
$users = User::whereIn('age', [16, 18, 20])->get();
当使用 whereNotIn
时,如果字段不存在,则返回对象。与 whereNotNull('age')
结合使用,可以排除这些文档。
使用 Where Between
$users = User::whereBetween('votes', [1, 100])->get();
Where null
$users = User::whereNull('updated_at')->get();
Order By
$users = User::orderBy('name', 'desc')->get();
Offset & Limit
$users = User::skip(10)->take(5)->get();
Distinct
Distinct 需要一个字段,用于返回不同的值。
$users = User::distinct()->get(['name']); // or $users = User::distinct('name')->get();
Distinct 可以与 where 结合使用
$users = User::where('active', true)->distinct('name')->get();
高级 Where
$users = User::where('name', '=', 'John')->orWhere(function($query) { $query->where('votes', '>', 100) ->where('title', '<>', 'Admin'); }) ->get();
Group By
未分组的选定列将使用 $last 函数聚合。
$users = Users::groupBy('title')->get(['title', 'name']);
聚合
聚合操作仅适用于 MongoDB 版本大于 2.2 的版本。
$total = Order::count(); $price = Order::max('price'); $price = Order::min('price'); $price = Order::avg('price'); $total = Order::sum('price');
聚合操作可以与 where 结合使用
$sold = Orders::where('sold', true)->sum('price');
聚合操作也可以用于子文档
$total = Order::max('suborder.price'); ...
注意:此聚合操作仅适用于单个子文档(如 embedsOne),不适用于子文档数组(如 embedsMany)
例如
$user = Comment::where('body', 'like', '%spam%')->get();
增加或减少列的值
对指定的属性执行增加或减少操作(默认为 1)
User::where('name', 'John Doe')->increment('age'); User::where('name', 'Jaques')->decrement('weight', 50);
返回更新对象的数量
$count = User->increment('age');
您还可以指定要更新的其他列
User::where('age', '29')->increment('age', 1, ['group' => 'thirty something']); User::where('bmi', 30)->decrement('bmi', 1, ['category' => 'overweight']);
软删除
当软删除模型时,它实际上并不会从您的数据库中删除。相反,会在记录上设置一个 deleted_at 时间戳。要为模型启用软删除,请将 SoftDeletingTrait 应用于模型
use Jenssegers\Mongodb\Eloquent\SoftDeletes; class User extends Eloquent { use SoftDeletes; protected $dates = ['deleted_at']; }
有关更多信息,请参阅 https://laravel.net.cn/docs/eloquent#soft-deleting
MongoDB 特定操作符
存在
匹配具有指定字段的文档。
User::where('age', 'exists', true)->get();
全部
匹配包含查询中指定所有元素的数组。
User::where('roles', 'all', ['moderator', 'author'])->get();
大小
如果数组字段是指定的大小,则选择文档。
User::where('tags', 'size', 3)->get();
正则表达式
选择值与指定正则表达式匹配的文档。
User::where('name', 'regex', new \MongoDB\BSON\Regex("/.*doe/i"))->get();
注意:您还可以使用 Laravel 正则表达式操作。这些操作更灵活,并且会自动将您的正则表达式字符串转换为 MongoDB\BSON\Regex 对象。
User::where('name', 'regexp', '/.*doe/i'))->get();
及其相反操作
User::where('name', 'not regexp', '/.*doe/i'))->get();
类型
如果字段是指定类型,则选择文档。有关更多信息,请参阅:http://docs.mongodb.org/manual/reference/operator/query/type/#op._S_type
User::where('age', 'type', 2)->get();
模
对字段的值执行模运算,并选择具有指定结果的文档。
User::where('age', 'mod', [10, 0])->get();
接近
注意:请按以下顺序指定坐标:经度,纬度
。
$users = User::where('location', 'near', [ '$geometry' => [ 'type' => 'Point', 'coordinates' => [ -0.1367563, 51.5100913, ], ], '$maxDistance' => 50, ]);
GeoWithin
$users = User::where('location', 'geoWithin', [ '$geometry' => [ 'type' => 'Polygon', 'coordinates' => [[ [ -0.1450383, 51.5069158, ], [ -0.1367563, 51.5100913, ], [ -0.1270247, 51.5013233, ], [ -0.1450383, 51.5069158, ], ]], ], ]);
GeoIntersects
$locations = Location::where('location', 'geoIntersects', [ '$geometry' => [ 'type' => 'LineString', 'coordinates' => [ [ -0.144044, 51.515215, ], [ -0.129545, 51.507864, ], ], ], ]);
Where
匹配满足 JavaScript 表达式的文档。有关更多信息,请参阅:http://docs.mongodb.org/manual/reference/operator/query/where/#op._S_where
插入、更新和删除
插入、更新和删除记录的工作方式与原始 Eloquent 相同。
保存新的模型
$user = new User; $user->name = 'John'; $user->save();
您还可以使用 create 方法在单行中保存新的模型。
User::create(['name' => 'John']);
更新模型
要更新模型,您可以检索它,更改属性,然后使用 save 方法。
$user = User::first(); $user->email = 'john@foo.com'; $user->save();
还支持 upsert 操作,请参阅 https://github.com/jenssegers/laravel-mongodb#mongodb-specific-operations
删除模型
要删除模型,只需在实例上调用 delete 方法。
$user = User::first(); $user->delete();
或根据键删除模型
User::destroy('517c43667db388101e00000f');
有关模型操作的更多信息,请参阅 https://laravel.net.cn/docs/eloquent#insert-update-delete
日期
Eloquent 允许您使用 Carbon/DateTime 对象而不是 MongoDate 对象。内部,这些日期将在保存到数据库时转换为 MongoDate 对象。如果您希望在非默认日期字段上使用此功能,则需要手动指定,具体说明请参阅此处:https://laravel.net.cn/docs/eloquent#date-mutators
示例
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class User extends Eloquent { protected $dates = ['birthday']; }
这允许您执行类似以下查询的操作
$users = User::where('birthday', '>', new DateTime('-18 years'))->get();
关系
支持的关系包括
- hasOne
- hasMany
- belongsTo
- belongsToMany
- embedsOne
- embedsMany
示例
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class User extends Eloquent { public function items() { return $this->hasMany('Item'); } }
及其反向关系
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class Item extends Eloquent { public function user() { return $this->belongsTo('User'); } }
belongsToMany 关系不会使用一个“关联”表,而是将 ID 推送到 related_ids 属性中。这使得 belongsToMany 方法的第二个参数变得无用。如果你要为你的关系定义自定义键,请将其设置为 null
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class User extends Eloquent { public function groups() { return $this->belongsToMany('Group', null, 'user_ids', 'group_ids'); } }
其他关系尚未支持,但未来可能会添加。更多关于这些关系的信息请参阅 https://laravel.net.cn/docs/eloquent#relationships
EmbedsMany 关系
如果你想嵌入模型而不是引用它们,可以使用 embedsMany
关系。这种关系类似于 hasMany
关系,但将模型嵌入到父对象中。
记住:这些关系返回 Eloquent 集合,而不是查询构建器对象!
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class User extends Eloquent { public function books() { return $this->embedsMany('Book'); } }
你可以通过动态属性访问嵌入的模型
$books = User::first()->books;
反向关系自动可用,你不需要定义这个反向关系。
$user = $book->user;
插入和更新嵌入的模型与 hasMany
关系类似
$book = new Book(['title' => 'A Game of Thrones']); $user = User::first(); $book = $user->books()->save($book); // or $book = $user->books()->create(['title' => 'A Game of Thrones'])
你可以使用它们的 save
方法更新嵌入的模型(自 2.0.0 版本以来可用)
$book = $user->books()->first(); $book->title = 'A Game of Thrones'; $book->save();
你可以通过在关系上使用 destroy
方法或在模型上使用 delete
方法来删除嵌入的模型(自 2.0.0 版本以来可用)
$book = $user->books()->first(); $book->delete(); // or $user->books()->destroy($book);
如果你想添加或删除嵌入的模型而不接触数据库,可以使用 associate
和 dissociate
方法。要最终将更改写入数据库,请保存父对象
$user->books()->associate($book); $user->save();
与其他关系一样,embedsMany 假设基于模型名称的关系的本地键。你可以通过将第二个参数传递给 embedsMany 方法来覆盖默认的本地键
return $this->embedsMany('Book', 'local_key');
嵌入的关系将返回一个嵌入项的集合,而不是查询构建器。请查看这里可用的操作:https://laravel.net.cn/docs/master/collections
EmbedsOne 关系
embedsOne 关系类似于 EmbedsMany 关系,但仅嵌入单个模型。
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class Book extends Eloquent { public function author() { return $this->embedsOne('Author'); } }
你可以通过动态属性访问嵌入的模型
$author = Book::first()->author;
插入和更新嵌入的模型与 hasOne
关系类似
$author = new Author(['name' => 'John Doe']); $book = Books::first(); $author = $book->author()->save($author); // or $author = $book->author()->create(['name' => 'John Doe']);
你可以使用 save
方法更新嵌入的模型(自 2.0.0 版本以来可用)
$author = $book->author; $author->name = 'Jane Doe'; $author->save();
你可以像这样替换嵌入的模型为新的模型
$newAuthor = new Author(['name' => 'Jane Doe']); $book->author()->save($newAuthor);
MySQL 关系
如果你使用混合 MongoDB 和 SQL 设置,那么你很幸运!模型将根据相关模型类型自动返回 MongoDB 或 SQL 关系。当然,如果你想使此功能双向工作,你的 SQL 模型需要使用 Jenssegers\Mongodb\Eloquent\HybridRelations
特性。请注意,此功能仅适用于 hasOne、hasMany 和 belongsTo 关系。
示例 SQL 基础用户模型
use Jenssegers\Mongodb\Eloquent\HybridRelations; class User extends Eloquent { use HybridRelations; protected $connection = 'mysql'; public function messages() { return $this->hasMany('Message'); } }
以及 MongoDB 基础消息模型
use Jenssegers\Mongodb\Eloquent\Model as Eloquent; class Message extends Eloquent { protected $connection = 'mongodb'; public function user() { return $this->belongsTo('User'); } }
原始表达式
这些表达式将被直接注入到查询中。
User::whereRaw(['age' => array('$gt' => 30, '$lt' => 40)])->get();
你还可以对内部 MongoCollection 对象执行原始表达式。如果这在模型类上执行,它将返回一个模型集合。如果这在查询构建器上执行,它将返回原始响应。
// Returns a collection of User models. $models = User::raw(function($collection) { return $collection->find(); }); // Returns the original MongoCursor. $cursor = DB::collection('users')->raw(function($collection) { return $collection->find(); });
可选:如果你没有传递闭包给 raw 方法,内部 MongoCollection 对象将可访问
$model = User::raw()->findOne(['age' => array('$lt' => 18)]);
可以通过这种方式访问内部 MongoClient 和 MongoDB 对象
$client = DB::getMongoClient(); $db = DB::getMongoDB();
MongoDB 特定操作
游标超时
为了防止 MongoCursorTimeout 异常,你可以手动设置一个应用于游标的超时值
DB::collection('users')->timeout(-1)->get();
Upsert
更新或插入一个文档。更新方法的附加选项直接传递给原生更新方法。
DB::collection('users')->where('name', 'John') ->update($data, ['upsert' => true]);
投影
你可以使用 project
方法对查询应用投影。
DB::collection('items')->project(['tags' => ['$slice' => 1]])->get(); DB::collection('items')->project(['tags' => ['$slice' => [3, 7]]])->get();
带分页的投影
$limit = 25; $projections = ['id', 'name']; DB::collection('items')->paginate($limit, $projections);
Push
向数组添加项目。
DB::collection('users')->where('name', 'John')->push('items', 'boots'); DB::collection('users')->where('name', 'John')->push('messages', ['from' => 'Jane Doe', 'message' => 'Hi John']);
如果你不想有重复的项目,将第三个参数设置为 true
DB::collection('users')->where('name', 'John')->push('items', 'boots', true);
Pull
从数组中删除项目。
DB::collection('users')->where('name', 'John')->pull('items', 'boots'); DB::collection('users')->where('name', 'John')->pull('messages', ['from' => 'Jane Doe', 'message' => 'Hi John']);
Unset
从文档中删除一个或多个字段。
DB::collection('users')->where('name', 'John')->unset('note');
你也可以在模型上执行 unset 操作。
$user = User::where('name', 'John')->first(); $user->unset('note');
查询缓存
您可以使用remember方法轻松缓存查询结果。
$users = User::remember(10)->get();
来源:https://laravel.net.cn/docs/queries#caching-queries
查询日志
默认情况下,Laravel会将当前请求中运行的所有查询记录在内存中。然而,在某些情况下,例如插入大量行时,这可能会导致应用程序使用过多的内存。要禁用日志记录,您可以使用disableQueryLog
方法。
DB::connection()->disableQueryLog();