目錄
- 安裝 Installation
- 升級 Upgrading
- 配置 Configuration
- Eloquent
- 可選: Alias
- 查詢器 Query Builder
- 構建器 Schema
- Extensions
- 樣例 Examples
安裝 Installation
確保安裝了MongoDB PHP驅動程序。您可以在 http://php.net/manual/en/mongodb.installation.php找到安裝說明
警告：版本> = 3.0時不再支持舊的mongo PHP驅動程序。
使用composer安裝：
composer require jenssegers/mongodbLaravel版兼容性
| Laravel | Package |
|---|---|
| 4.2.x | 2.0.x |
| 5.0.x | 2.1.x |
| 5.1.x | 2.2.x or 3.0.x |
| 5.2.x | 2.3.x or 3.0.x |
| 5.3.x | 3.1.x or 3.2.x |
| 5.4.x | 3.2.x |
| 5.5.x | 3.3.x |
| 5.6.x | 3.4.x |
並添加服務提供商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管理器並添加：
$capsule->getDatabaseManager()->extend('mongodb', function($config) { return new Jenssegers\Mongodb\Connection($config); });升級 Upgrading
從版本2升級到3
在這個支持新mongodb PHP擴展的新主要版本中，我們還移動了Model類的位置，並用特征替換了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特性。這應該使事情更清楚，因為此包中只有一個單一的模型類。
use Jenssegers\Mongodb\Eloquent\HybridRelations; class User extends Eloquent { use HybridRelations; protected $connection = 'mysql'; }嵌入式關系現在返回一個Illuminate\Database\Eloquent\Collection而不是自定義Collection類。如果您使用的是一種可用的特殊方法，請將它們轉換為Collection集合操作。
$books = $user->books()->sortBy('title');測試 Testing
要運行此程序包的測試，請運行：
docker-compose up 配置 Configuration
更改您的默認數據庫連接名稱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'), ],有關其URI格式，請參閱MongoDB官方文檔：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模型一樣工作。在http://laravel.com/docs/eloquent上閱讀有關Eloquent的更多信息
可選項：別名 Alias
您還可以通過將以下內容添加到別名數組中來注冊MongoDB模型的別名config/app.php：
'Moloquent' => Jenssegers\Mongodb\Eloquent\Model::class,
這將允許您使用注冊的別名，如：
class MyModel extends Moloquent {}查詢生成器 Query Builder
數據庫驅動程序直接插入原始查詢構建器。使用mongodb連接時，您將能夠構建流暢的查詢來執行數據庫操作。為方便起見，還有一個collection別名table以及一些額外的mongodb特定操作符/操作。
$users = DB::collection('users')->get(); $user = DB::collection('users')->where('name', 'John')->first();如果未更改默認數據庫連接，則需要在查詢時指定它。
$user = DB::connection('mongodb')->collection('users')->get();在http://laravel.com/docs/queries上閱讀有關查詢構建器的更多信息
構建器 Schema
數據庫驅動程序還具有（有限的）架構構建器支持。您可以輕松地操作集合並設置索引：
Schema::create('users', function($collection) { $collection->index('name'); $collection->unique('email'); });支持的操作如下：
- create 和 drop
- collection
- hasCollection
- index 和 dropIndex (compound indexes supported as well)
- unique
- background, sparse, expire, geospatial (MongoDB specific)
所有其他（不支持的）操作都實現為虛擬傳遞方法，因為MongoDB不使用預定義的模式。在http://laravel.com/docs/schema上閱讀有關架構構建器的更多信息
地理空間索引
2dsphere。使用模式構建器將這些添加到集合中。
Schema::create('users', function($collection) { $collection->geospatial('name', '2d'); });添加 2dsphere index:
Schema::create('users', function($collection) { $collection->geospatial('name', '2dsphere'); });擴展 Extensions
認證
如果您想使用Laravel的本機Auth功能，請注冊此包含的服務提供商：
'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
如果您想將此庫與https://github.com/jenssegers/Laravel-MongoDB-Sentry
Sessions
MongoDB會話驅動程序在單獨的包中提供，請查看https://github.com/jenssegers/Laravel-MongoDB-Session
例子 Examples
基本用法
檢索所有模型
$users = User::all();通過主鍵檢索記錄
$user = User::find('517c43667db388101e00000f');Wheres
$users = User::where('votes', '>', 100)->take(10)->get();Or Statements
$users = User::where('votes', '>', 100)->orWhere('name', 'John')->get();And Statements
$users = User::where('votes', '>', 100)->where('name', '=', 'John')->get();Using Where In With An Array
$users = User::whereIn('age', [16, 18, 20])->get();whereNotIn如果字段不存在，將返回使用對象。結合使用whereNotNull('age')可以省去這些文件。
Using 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();自定義 Wheres
$users = User::where('name', '=', 'John')->orWhere(function($query) { $query->where('votes', '>', 100) ->where('title', '<>', 'Admin'); }) ->get();Group By
$users = Users::groupBy('title')->get(['title', 'name']);聚合查詢 Aggregation
聚合僅適用於大於2.2的MongoDB版本。
$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'); ...注意：此aggreagtion僅適用於單個子文檔（如embedsOne）而非子文檔數組（如embedsMany）
Like
$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']; }有關更多信息，請訪問http://laravel.com/docs/eloquent#soft-deleting
MongoDB特殊運算
exists
匹配具有指定字段的文檔。
User::where('age', 'exists', true)->get();All
匹配包含查詢中指定的所有元素的數組。
User::where('roles', 'all', ['moderator', 'author'])->get();Size
如果數組字段是指定大小，則選擇文檔。
User::where('tags', 'size', 3)->get();Regex
選擇值與指定正則表達式匹配的文檔。
User::where('name', 'regex', new \MongoDB\BSON\Regex("/.*doe/i"))->get();注意：您還可以使用Laravel regexp操作。這些更靈活，會自動將正則表達式字符串轉換為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();Mod
對字段的值執行模運算，並選擇具有指定結果的文檔。
User::where('age', 'mod', [10, 0])->get();Near
注意：按此順序指定坐標：longitude, latitude。
$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一樣。
Saving a new model
$user = new User; $user->name = 'John'; $user->save();您還可以使用create方法將新模型保存在一行中：
User::create(['name' => 'John']);Updating a model
要更新模型，您可以檢索它，更改屬性並使用save方法。
$user = User::first();
$user->email = 'john@foo.com'; $user->save();還有對upsert操作的支持，請查看https://github.com/jenssegers/laravel-mongodb#mongodb-specific-operations
Deleting a model
要刪除模型，只需在實例上調用delete方法：
$user = User::first();
$user->delete();或者按鍵刪除模型：
User::destroy('517c43667db388101e00000f');有關模型操作的更多信息，請查看http://laravel.com/docs/eloquent#insert-update-delete
Dates
Eloquent允許您使用Carbon / DateTime對象而不是MongoDate對象。在內部，這些日期在保存到數據庫時將轉換為MongoDate對象。如果您希望在非默認日期字段上使用此功能，則需要按照此處所述手動指定它們：http：//laravel.com/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();Relations
支持的關系是：
- 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關系不會使用數據透視表“table”，而是將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'); } }其他關系尚未得到支持，但可能會在未來添加。有關這些關系的更多信息，請訪問http://laravel.com/docs/eloquent#relationships
嵌入許多關系
如果要嵌入模型而不是引用模型，可以使用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.com/docs/master/collections
EmbedsOne Relations
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的Message模型：
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
更新或插入文檔。update方法的其他選項將直接傳遞給本機更新方法。
DB::collection('users')->where('name', 'John') ->update($data, ['upsert' => true]);Projections
您可以使用該project方法將投影應用於查詢。
DB::collection('items')->project(['tags' => ['$slice' => 1]])->get(); DB::collection('items')->project(['tags' => ['$slice' => [3, 7]]])->get();Projections with Pagination
$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');您還可以在模型上執行取消設置。
$user = User::where('name', 'John')->first(); $user->unset('note');查詢緩存 Query Caching
您可以使用remember方法輕松緩存查詢結果：
$users = User::remember(10)->get();來自：http：//laravel.com/docs/queries#caching-queries
查詢日志 Query Logging
默認情況下，Laravel會記錄已為當前請求運行的所有查詢的內存。但是，在某些情況下，例如插入大量行時，這可能會導致應用程序使用過多的內存。要禁用日志，您可以使用以下disableQueryLog方法：
DB::connection()->disableQueryLog();