README

一个支持MongoDB的Eloquent模型和查询构建器，使用原始Laravel API。 这个库扩展了原始的Laravel类，因此使用完全相同的方法。

目录

• 安装
• 升级
• 配置
• Eloquent
• 可选：别名
• 查询构建器
• 模式
• 扩展
• 故障排除
• 示例

安装

确保您已安装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扩展，并将Model类的位置移动了，并用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而不是自定义的Collection类。如果您正在使用特殊方法之一，请将其转换为Collection操作。

$books = $user->books()->sortBy('title');

测试

要运行此包的测试，请运行

docker-compose up

配置

在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别名用于table以及一些额外的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');
});

支持的操作包括

• 创建和删除
• collection
• hasCollection
• index 和 dropIndex（支持复合索引）
• unique
• background、sparse、expire、geospatial（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();

OrderBy

$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();

分组

未分组的选定列将使用$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）。

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'];

}

更多信息请查看 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

嵌套Many关系

如果您想嵌套模型而不是引用它们，可以使用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

嵌套One关系

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();

更新或插入

更新或插入文档。将更新方法的附加选项直接传递给原生更新方法。

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);

推入

向数组中添加项目。

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);

拉出

从数组中删除一个项目。

DB::collection('users')->where('name', 'John')->pull('items', 'boots');
DB::collection('users')->where('name', 'John')->pull('messages', ['from' => 'Jane Doe', 'message' => 'Hi John']);

未设置

从一个文档中移除一个或多个字段。

DB::collection('users')->where('name', 'John')->unset('note');

您也可以对一个模型执行未设置操作。

$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();

来源：https://laravel.net.cn/docs/database#query-logging