mshamaseen / laravel-mongodb
基于MongoDB的Eloquent模型和查询构建器,用于Laravel(Moloquent)
Requires
- illuminate/container: ^10.0
- illuminate/database: ^10.0
- illuminate/events: ^10.0
- illuminate/support: ^10.0
- mongodb/mongodb: ^1.15
Requires (Dev)
- mockery/mockery: ^1.4.4
- orchestra/testbench: ^8.0
- phpunit/phpunit: ^9.5.10
Suggests
- jenssegers/mongodb-sentry: Add Sentry support to Laravel-MongoDB
- jenssegers/mongodb-session: Add MongoDB session support to Laravel-MongoDB
This package is auto-updated.
Last update: 2024-09-15 21:48:30 UTC
README
此包向MongoDB的Eloquent模型和查询构建器添加功能,使用原始的Laravel API。 此库扩展了原始的Laravel类,因此使用完全相同的方法。
安装
确保您已安装MongoDB PHP驱动程序。您可以在https://php.ac.cn/manual/en/mongodb.installation.php找到安装说明。
Laravel版本兼容性
通过Composer安装包
$ composer require mshamaseen/laravel-mongodb
Laravel
如果您的Laravel版本不自动加载包,请将服务提供者添加到config/app.php
Jenssegers\Mongodb\MongodbServiceProvider::class,
Lumen
对于与Lumen一起使用,请在bootstrap/app.php
中添加服务提供者。在此文件中,您还需要启用Eloquent。但是,您必须确保对$app->withEloquent();
的调用在注册MongodbServiceProvider
之后。
$app->register(Jenssegers\Mongodb\MongodbServiceProvider::class); $app->withEloquent();
服务提供者将注册一个MongoDB数据库扩展到原始数据库管理器。不需要注册额外的外观或对象。
当使用MongoDB连接时,Laravel将自动为您提供相应的MongoDB对象。
非Laravel项目
对于Laravel之外的使用,请查看Capsule管理器并添加
$capsule->getDatabaseManager()->extend('mongodb', function($config, $name) { $config['name'] = $name; return new Jenssegers\Mongodb\Connection($config); });
测试
要为此包运行测试,请运行
docker-compose up
数据库测试
要测试后重置数据库,请添加
use Illuminate\Foundation\Testing\DatabaseMigrations;
同样,在测试类的内部,请添加
use DatabaseMigrations;
请注意,这些特性目前尚不支持
use Database Transactions;
use RefreshDatabase;
配置
要配置新的MongoDB连接,请在config/database.php
中添加新的连接条目
'mongodb' => [ 'driver' => 'mongodb', 'dsn' => env('DB_DSN'), 'database' => env('DB_DATABASE', 'homestead'), ],
dsn
键包含用于连接您的MongoDB部署的连接字符串。格式和可用选项在MongoDB文档中有记录。
您还可以使用host
和port
配置选项来创建连接字符串,而不使用连接字符串。
'mongodb' => [ 'driver' => 'mongodb', 'host' => env('DB_HOST', '127.0.0.1'), 'port' => env('DB_PORT', 27017), 'database' => env('DB_DATABASE', 'homestead'), 'username' => env('DB_USERNAME', 'homestead'), 'password' => env('DB_PASSWORD', 'secret'), 'options' => [ 'appname' => 'homestead', ], ],
连接配置中的options
键对应于uriOptions
参数。
Eloquent
扩展基本模型
本软件包包括一个启用了MongoDB的Eloquent类,您可以使用它来定义对应集合的模型。
use Jenssegers\Mongodb\Eloquent\Model; class Book extends Model { // }
与普通模型一样,MongoDB模型类会根据模型名称知道使用哪个集合。对于Book
,将使用集合books
。
要更改集合,请传递$collection
属性
use Jenssegers\Mongodb\Eloquent\Model; class Book extends Model { protected $collection = 'my_books_collection'; }
注意: MongoDB文档会自动存储一个唯一的ID,该ID存储在_id
属性中。如果您希望使用自己的ID,请替换$primaryKey
属性并将其设置为您的自己的主键属性名称。
use Jenssegers\Mongodb\Eloquent\Model; class Book extends Model { protected $primaryKey = 'id'; } // MongoDB will also create _id, but the 'id' property will be used for primary key actions like find(). Book::create(['id' => 1, 'title' => 'The Fault in Our Stars']);
同样,您可以定义一个connection
属性来覆盖在利用模型时应使用的数据库连接名称。
use Jenssegers\Mongodb\Eloquent\Model; class Book extends Model { protected $connection = 'mongodb'; }
扩展Authenticatable基础模型
本软件包包括一个MongoDB Authenticatable Eloquent类Jenssegers\Mongodb\Auth\User
,您可以使用它来替换默认的Authenticatable类Illuminate\Foundation\Auth\User
,以用于您的User
模型。
use Jenssegers\Mongodb\Auth\User as Authenticatable; class User extends Authenticatable { }
软删除
当软删除模型时,实际上并没有从数据库中删除。相反,会在记录上设置一个deleted_at时间戳。
要启用模型的软删除,请将Jenssegers\Mongodb\Eloquent\SoftDeletes
特性应用于模型
use Jenssegers\Mongodb\Eloquent\SoftDeletes; class User extends Model { use SoftDeletes; }
有关更多信息,请查看Laravel关于软删除的文档。
保护属性
在选择保护属性或标记某些属性为可填充时,Taylor Otwell更倾向于填充方式。这基于此处描述的最近的安全问题。
请记住,保护仍然有效,但您可能会遇到意外行为。
日期
Eloquent允许您使用Carbon或DateTime对象而不是MongoDate对象。在内部,这些日期将在保存到数据库时转换为MongoDate对象。
use Jenssegers\Mongodb\Eloquent\Model; class User extends Model { protected $casts = ['birthday' => 'datetime']; }
这允许您执行如下查询
$users = User::where( 'birthday', '>', new DateTime('-18 years') )->get();
基本用法
检索所有模型
$users = User::all();
通过主键检索记录
$user = User::find('517c43667db388101e00000f');
Where
$posts = Post::where('author.name', 'John') ->take(10) ->get();
OR语句
$posts = Post::where('votes', '>', 0) ->orWhere('is_approved', true) ->get();
AND语句
$users = User::where('age', '>', 18) ->where('name', '!=', 'John') ->get();
whereIn
$users = User::whereIn('age', [16, 18, 20])->get();
当使用whereNotIn
时,如果字段不存在,则将返回对象。结合使用whereNotNull('age')
可以排除那些文档。
whereBetween
$posts = Post::whereBetween('votes', [1, 100])->get();
whereNull
$users = User::whereNull('age')->get();
whereDate
$users = User::whereDate('birthday', '2021-5-12')->get();
用法与whereMonth
/ whereDay
/ whereYear
/ whereTime
相同
高级Where
$users = User::where('name', 'John') ->orWhere(function ($query) { return $query ->where('votes', '>', 100) ->where('title', '<>', 'Admin'); })->get();
orderBy
$users = User::orderBy('age', 'desc')->get();
Offset & Limit(跳过 & 拿取)
$users = User::skip(10) ->take(5) ->get();
groupBy
未分组的选择列将使用$last
函数进行聚合。
$users = Users::groupBy('title') ->get(['title', 'name']);
Distinct
Distinct需要一个字段,用于返回唯一值。
$users = User::distinct()->get(['name']); // Equivalent to: $users = User::distinct('name')->get();
Distinct可以与where
结合使用
$users = User::where('active', true) ->distinct('name') ->get();
Like
$spamComments = Comment::where('body', 'like', '%spam%')->get();
聚合
聚合仅适用于MongoDB版本大于2.2.x的版本
$total = Product::count(); $price = Product::max('price'); $price = Product::min('price'); $price = Product::avg('price'); $total = Product::sum('price');
聚合可以与where
结合使用
$sold = Orders::where('sold', true)->sum('price');
聚合也可以用于子文档
$total = Order::max('suborder.price');
注意:此聚合仅适用于单个子文档(如EmbedsOne
),不适用于子文档数组(如EmbedsMany
)。
增加/减少列的值
对指定的属性执行增加或减少操作(默认为1)
Cat::where('name', 'Kitty')->increment('age'); Car::where('name', 'Toyota')->decrement('weight', 50);
返回已更新的对象数量
$count = User::increment('age');
您还可以指定要更新的其他列
Cat::where('age', 3) ->increment('age', 1, ['group' => 'Kitty Club']); Car::where('weight', 300) ->decrement('weight', 100, ['latest_change' => 'carbon fiber']);
MongoDB特定的运算符
Exists
匹配具有指定字段的文档。
User::where('age', 'exists', true)->get();
All
匹配包含查询中指定所有元素的数组。
User::where('roles', 'all', ['moderator', 'author'])->get();
Size
选择数组字段是指定大小的文档。
Post::where('tags', 'size', 3)->get();
Regex
选择与指定正则表达式匹配的文档。
use MongoDB\BSON\Regex; User::where('name', 'regex', new Regex('.*doe', 'i'))->get();
注意:您还可以使用Laravel正则表达式操作。这些操作更灵活,并且会自动将您的正则表达式字符串转换为MongoDB\BSON\Regex
对象。
User::where('name', 'regexp', '/.*doe/i')->get();
正则表达式的逆操作
User::where('name', 'not regexp', '/.*doe/i')->get();
Type
如果字段是指定的类型,则选择文档。有关更多信息,请查看: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();
MongoDB特定的地理空间运算
近
$bars = Bar::where('location', 'near', [ '$geometry' => [ 'type' => 'Point', 'coordinates' => [ -0.1367563, // longitude 51.5100913, // latitude ], ], '$maxDistance' => 50, ])->get();
GeoWithin
$bars = Bar::where('location', 'geoWithin', [ '$geometry' => [ 'type' => 'Polygon', 'coordinates' => [ [ [-0.1450383, 51.5069158], [-0.1367563, 51.5100913], [-0.1270247, 51.5013233], [-0.1450383, 51.5069158], ], ], ], ])->get();
GeoIntersects
$bars = Bar::where('location', 'geoIntersects', [ '$geometry' => [ 'type' => 'LineString', 'coordinates' => [ [-0.144044, 51.515215], [-0.129545, 51.507864], ], ], ])->get();
GeoNear
您可以在mongoDB上执行geoNear
查询。您不需要指定模型上的自动字段。返回的实例是一个集合。因此,您可以对集合进行操作。只需确保您的模型有一个location
字段,并且有一个2ndSphereIndex。在location
字段中的数据必须保存为GeoJSON。location
点必须以WGS84参考系统保存,以便进行几何计算。这意味着,基本上,您需要按照特定顺序保存经度和纬度
,以便计算距离,您需要以相同的方式进行操作。
Bar::find("63a0cd574d08564f330ceae2")->update(
[
'location' => [
'type' => 'Point',
'coordinates' => [
-0.1367563,
51.5100913
]
]
]
);
$bars = Bar::raw(function ($collection) {
return $collection->aggregate([
[
'$geoNear' => [
"near" => [ "type" => "Point", "coordinates" => [-0.132239, 51.511874] ],
"distanceField" => "dist.calculated",
"minDistance" => 0,
"maxDistance" => 6000,
"includeLocs" => "dist.location",
"spherical" => true,
]
]
]);
});
插入、更新和删除
插入、更新和删除记录的工作方式与原始Eloquent相同。请查阅Laravel文档的Eloquent部分。
在此,仅指定MongoDB特定的操作。
MongoDB特定操作
原始表达式
这些表达式将被直接注入到查询中。
User::whereRaw([ 'age' => ['$gt' => 30, '$lt' => 40], ])->get(); User::whereRaw([ '$where' => '/.*123.*/.test(this.field)', ])->get(); User::whereRaw([ '$where' => '/.*123.*/.test(this["hyphenated-field"])', ])->get();
您还可以在内部MongoCollection对象上执行原始表达式。如果在模型类上执行,它将返回一个模型集合。
如果在查询构建器上执行,它将返回原始响应。
光标超时
为了防止MongoCursorTimeout
异常,您可以手动设置一个将应用于光标的超时值
DB::collection('users')->timeout(-1)->get();
Upsert
更新或插入文档。更新方法的附加选项直接传递给本地更新方法。
// Query Builder DB::collection('users') ->where('name', 'John') ->update($data, ['upsert' => true]); // Eloquent $user->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'); $user->push('items', 'boots');
DB::collection('users') ->where('name', 'John') ->push('messages', [ 'from' => 'Jane Doe', 'message' => 'Hi John', ]); $user->push('messages', [ 'from' => 'Jane Doe', 'message' => 'Hi John', ]);
如果您不想添加重复的项目,将第三个参数设置为true
DB::collection('users') ->where('name', 'John') ->push('items', 'boots', true); $user->push('items', 'boots', true);
Pull
从数组中删除一个项目。
DB::collection('users') ->where('name', 'John') ->pull('items', 'boots'); $user->pull('items', 'boots');
DB::collection('users') ->where('name', 'John') ->pull('messages', [ 'from' => 'Jane Doe', 'message' => 'Hi John', ]); $user->pull('messages', [ 'from' => 'Jane Doe', 'message' => 'Hi John', ]);
Unset
从文档中删除一个或多个字段。
DB::collection('users') ->where('name', 'John') ->unset('note'); $user->unset('note');
关系
基本用法
仅有的可用关系是
- hasOne
- hasMany
- belongsTo
- belongsToMany
MongoDB特定的关系是
- embedsOne
- embedsMany
以下是一个小示例
use Jenssegers\Mongodb\Eloquent\Model; class User extends Model { public function items() { return $this->hasMany(Item::class); } }
hasMany
的反向关系是belongsTo
use Jenssegers\Mongodb\Eloquent\Model; class Item extends Model { public function user() { return $this->belongsTo(User::class); } }
belongsToMany和pivot
belongsToMany关系将不会使用“枢纽”表,而是将id推送到related_ids
属性。这使得belongsToMany方法的第二个参数变得无用。
如果您想为关系定义自定义键,将其设置为null
use Jenssegers\Mongodb\Eloquent\Model; class User extends Model { public function groups() { return $this->belongsToMany( Group::class, null, 'user_ids', 'group_ids' ); } }
注意:将外键命名为与关系名称相同将阻止在动态属性上调用关系,例如,在上面的示例中,如果您将group_ids
替换为groups
,则调用$user->groups
将返回列而不是关系。
EmbedsMany关系
如果您想嵌入模型而不是引用它们,可以使用embedsMany
关系。这种关系类似于hasMany
关系,但将模型嵌入到父对象中。
记住:这些关系返回Eloquent集合,它们不返回查询构建器对象!
破坏性更改从v10.0开始,您需要为EmbedsOne和EmbedsMany关系定义返回类型才能使其正常工作
use Jenssegers\Mongodb\Eloquent\Model; use Jenssegers\Mongodb\Relations\EmbedsMany; class User extends Model { public function books(): EmbedsMany { return $this->embedsMany(Book::class); } }
您可以通过动态属性访问嵌入的模型
$user = User::first(); foreach ($user->books as $book) { // }
反向关系是自动魔法般可用的。您不需要定义此反向关系。
$book = Book::first(); $user = $book->user;
嵌入模型插入和更新与hasMany
关系类似
$book = $user->books()->save( new Book(['title' => 'A Game of Thrones']) ); // 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->delete(); // Similar operation $user->books()->destroy($book);
如果您想在不接触数据库的情况下添加或删除嵌入模型,可以使用associate
和dissociate
方法。
要将更改最终写入数据库,请保存父对象
$user->books()->associate($book); $user->save();
与其他关系一样,embedsMany假设基于模型名称的关系本地键。您可以通过传递第二个参数给embedsMany方法来覆盖默认的本地键
use Jenssegers\Mongodb\Eloquent\Model; use Jenssegers\Mongodb\Relations\EmbedsMany; class User extends Model { public function books(): EmbedsMany { return $this->embedsMany(Book::class, 'local_key'); } }
嵌入式关系将返回嵌入项的集合而不是查询构建器。在此查看可用操作:https://laravel.net.cn/docs/master/collections
EmbedsOne关系
embedsOne关系与embedsMany关系类似,但只嵌入单个模型。
破坏性更改从v10.0开始,您需要为EmbedsOne和EmbedsMany关系定义返回类型才能使其正常工作
use Jenssegers\Mongodb\Eloquent\Model; use Jenssegers\Mongodb\Relations\EmbedsOne; class Book extends Model { public function author(): EmbedsOne { return $this->embedsOne(Author::class); } }
您可以通过动态属性访问嵌入的模型
$book = Book::first(); $author = $book->author;
嵌入模型插入和更新与hasOne
关系类似
$author = $book->author()->save( new Author(['name' => 'John Doe']) ); // Similar $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);
查询构建器
基本用法
数据库驱动程序直接连接到原始查询构建器。
当使用MongoDB连接时,您将能够构建流畅的查询以执行数据库操作。
为了方便起见,还有一个collection
别名用于table
,以及一些额外的MongoDB特定操作符/操作。
$books = DB::collection('books')->get(); $hungerGames = DB::collection('books') ->where('name', 'Hunger Games') ->first();
如果您熟悉Eloquent Queries,功能相同。
可用操作
要查看可用操作,请查看Eloquent部分。
事务
事务需要MongoDB版本^4.0以及副本集或分片集群的部署。您可以在MongoDB文档中找到更多信息在这里
基本用法
DB::transaction(function () { User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); DB::collection('users')->where('name', 'john')->update(['age' => 20]); DB::collection('users')->where('name', 'john')->delete(); });
// begin a transaction DB::beginTransaction(); User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); DB::collection('users')->where('name', 'john')->update(['age' => 20]); DB::collection('users')->where('name', 'john')->delete(); // commit changes DB::commit();
要中止事务,在任何事务期间调用rollBack
方法
DB::beginTransaction(); User::create(['name' => 'john', 'age' => 19, 'title' => 'admin', 'email' => 'john@example.com']); // Abort the transaction, discarding any data created as part of it DB::rollBack();
注意:MongoDB中的事务不能嵌套。DB::beginTransaction()函数将在新创建的或现有的会话中启动新事务,并在事务已存在时引发RuntimeException。更多信息请参见MongoDB官方文档事务和会话
DB::beginTransaction(); User::create(['name' => 'john', 'age' => 20, 'title' => 'admin']); // This call to start a nested transaction will raise a RuntimeException DB::beginTransaction(); DB::collection('users')->where('name', 'john')->update(['age' => 20]); DB::commit(); DB::rollBack();
模式
数据库驱动程序还具有(有限的)架构构建器支持。您可以轻松操作集合并设置索引。
基本用法
Schema::create('users', function ($collection) { $collection->index('name'); $collection->unique('email'); });
您还可以将MongoDB文档中指定的所有参数传递给$option参数
Schema::create('users', function ($collection) { $collection->index( 'username', null, null, [ 'sparse' => true, 'unique' => true, 'background' => true, ] ); });
继承的操作
- 创建和删除
- 集合
- hasCollection
- 索引和删除索引(支持复合索引)
- 唯一
MongoDB特定操作
- 后台
- 稀疏
- 过期
- 地理空间
所有其他(不支持)操作都作为虚拟透传方法实现,因为MongoDB不使用预定义的架构。
有关架构构建器的更多信息,请参阅Laravel 文档
地理空间索引
地理空间索引对于查询基于位置的文档非常有用。
它们有两种形式:2d
和2dsphere
。使用架构构建器将这些添加到集合中。
Schema::create('bars', function ($collection) { $collection->geospatial('location', '2d'); });
要添加2dsphere
索引
Schema::create('bars', function ($collection) { $collection->geospatial('location', '2dsphere'); });
扩展
跨数据库关系
如果您使用的是混合MongoDB和SQL设置,可以在它们之间定义关系。
模型将自动返回基于相关模型类型的MongoDB相关或SQL相关关系。
如果您想使此功能双向工作,您的SQL模型需要使用Jenssegers\Mongodb\Eloquent\HybridRelations
特质。
此功能仅适用于hasOne
、hasMany
和belongsTo
。
MySQL模型应使用HybridRelations
特质
use Jenssegers\Mongodb\Eloquent\HybridRelations; class User extends Model { use HybridRelations; protected $connection = 'mysql'; public function messages() { return $this->hasMany(Message::class); } }
在您的MongoDB模型中,您应该定义关系
use Jenssegers\Mongodb\Eloquent\Model; class Message extends Model { protected $connection = 'mongodb'; public function user() { return $this->belongsTo(User::class); } }
身份验证
如果您想使用Laravel的本地Auth功能,请注册此包含的服务提供程序
Jenssegers\Mongodb\Auth\PasswordResetServiceProvider::class,
此服务提供程序将稍微修改内部的DatabaseReminderRepository以添加基于MongoDB的密码提醒支持。
如果您不使用密码提醒,您不需要注册此服务提供程序,其他一切应该都能正常工作。
队列
如果您想将MongoDB用作数据库后端,请更改config/queue.php
中的驱动程序
'connections' => [ 'database' => [ 'driver' => 'mongodb', // You can also specify your jobs specific database created on config/database.php 'connection' => 'mongodb-job', 'table' => 'jobs', 'queue' => 'default', 'expire' => 60, ], ],
如果您想使用MongoDB处理失败的任务,请更改config/queue.php
中的数据库
'failed' => [ 'driver' => 'mongodb', // You can also specify your jobs specific database created on config/database.php 'database' => 'mongodb-job', 'table' => 'failed_jobs', ],
Laravel特定
在config/app.php
中添加服务提供程序
Jenssegers\Mongodb\MongodbQueueServiceProvider::class,
Lumen特定
使用Lumen时,请将服务提供程序添加到bootstrap/app.php
。但是,您必须确保在添加MongodbServiceProvider
注册之后添加以下内容。
$app->make('queue'); $app->register(Jenssegers\Mongodb\MongodbQueueServiceProvider::class);
升级
从版本2升级到3
在这个支持新MongoDB PHP扩展的新主要版本中,我们还移动了Model类的位置,并用特性替换了MySQL模型类。
请将所有Jenssegers\Mongodb\Model
引用更改为Jenssegers\Mongodb\Eloquent\Model
,无论是在您的模型文件顶部还是您的注册别名中。
use Jenssegers\Mongodb\Eloquent\Model; class User extends Model { // }
如果您使用混合关系,您的MySQL类现在应该扩展原始的Eloquent模型类Illuminate\Database\Eloquent\Model
,而不是已删除的Jenssegers\Eloquent\Model
。
相反,使用新的Jenssegers\Mongodb\Eloquent\HybridRelations
特性。这应该使事情更加清晰,因为这个包中只有一个单一的模型类。
use Jenssegers\Mongodb\Eloquent\HybridRelations; class User extends Model { use HybridRelations; protected $connection = 'mysql'; }
嵌入式关系现在返回一个Illuminate\Database\Eloquent\Collection
而不是自定义的集合类。如果您使用过这些特殊方法之一,请将它们转换为集合操作。
$books = $user->books()->sortBy('title')->get();
安全联系信息
要报告安全漏洞,请遵循这些步骤。