README

此包通过使用原始Laravel API为MongoDB的Eloquent模型和查询构建器添加功能。此库扩展了原始Laravel类，因此使用完全相同的方法。

Laravel MongoDB

安装

请确保您已安装MongoDB PHP驱动。您可以在https://php.ac.cn/manual/en/mongodb.installation.php找到安装说明。

Laravel版本兼容性

通过Composer安装此包

$ composer require jenssegers/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 manager并添加

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

请注意，这些特性目前尚不支持

使用Database Transactions;
使用RefreshDatabase;

配置

您可以将MongoDB用作主数据库或副数据库。为此，请向config/database.php中添加一个新的mongodb连接。

'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' => [
        // here you can pass more settings to the Mongo Driver Manager
        // see https://php.ac.cn/manual/en/mongodb-driver-manager.construct.php under "Uri Options" for a list of complete parameters that you can use

        'database' => env('DB_AUTHENTICATION_DATABASE', 'admin'), // required with Mongo 3+
    ],
],

对于多个服务器或副本集配置，将主机设置为数组并指定每个服务器主机

'mongodb' => [
    'driver' => 'mongodb',
    'host' => ['server1', 'server2', ...],
    ...
    'options' => [
        'replicaSet' => 'rs0',
    ],
],

如果您希望使用连接字符串而不是完整的键值参数，可以设置它。请检查MongoDB的URI格式文档：https://docs.mongodb.com/manual/reference/connection-string/

'mongodb' => [
    'driver' => 'mongodb',
    'dsn' => env('DB_DSN'),
    'database' => env('DB_DATABASE', 'homestead'),
],

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

// Mongo 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';
}

软删除

当软删除一个模型时，它实际上并没有从您的数据库中删除。相反，会在记录上设置一个 deleted_at 时间戳。

要为模型启用软删除，请将 Jenssegers\Mongodb\Eloquent\SoftDeletes 特性应用到模型上。

use Jenssegers\Mongodb\Eloquent\SoftDeletes;

class User extends Model
{
    use SoftDeletes;

    protected $dates = ['deleted_at'];
}

更多信息请查看 Laravel 关于软删除的文档。

日期

Eloquent 允许您使用 Carbon 或 DateTime 对象而不是 MongoDate 对象。在内部，这些日期在保存到数据库时会被转换为 MongoDate 对象。

use Jenssegers\Mongodb\Eloquent\Model;

class User extends Model
{
    protected $dates = ['birthday'];
}

这使得您可以执行如下查询

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

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

Mod

对字段的值执行模运算，并选择具有指定结果的文档。

User::where('age', 'mod', [10, 0])->get();

MongoDB特定地理空间运算

Near

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

插入、更新和删除

插入、更新和删除记录的工作方式与原始 Eloquent 相同。请查看 Laravel 文档的 Eloquent 部分。

这里只指定了 MongoDB 特定的操作。

MongoDB特定操作

原始表达式

这些表达式将直接注入到查询中。

User::whereRaw([
    'age' => ['$gt' => 30, '$lt' => 40],
])->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和枢轴

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

EmbedsMany关系

如果您想嵌入模型，而不是引用它们，可以使用 embedsMany 关系。此关系类似于 hasMany 关系，但将模型嵌入到父对象中。

记住：这些关系返回 Eloquent 集合，它们不返回查询构建器对象！

use Jenssegers\Mongodb\Eloquent\Model;

class User extends Model
{
    public function books()
    {
        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;

class User extends Model
{
    public function books()
    {
        return $this->embedsMany(Book::class, 'local_key');
    }
}

嵌入的关系将返回嵌入项的集合，而不是查询构建器。请查看此处提供的可用操作：https://laravel.net.cn/docs/master/collections

EmbedsOne关系

embedsOne 关系类似于 embedsMany 关系，但只嵌入单个模型。

use Jenssegers\Mongodb\Eloquent\Model;

class Book extends Model
{
    public function author()
    {
        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 查询，则具有相同的功能。

可用操作

要查看可用操作，请查看 Eloquent 部分。

模式

数据库驱动程序还具有（有限的）模式构建器支持。您可以轻松地操作集合并设置索引。

基本用法

Schema::create('users', function ($collection) {
    $collection->index('name');
    $collection->unique('email');
});

您还可以将MongoDB文档中指定的所有参数传递给$options参数。（有关所有索引类型的选项）

Schema::create('users', function ($collection) {
    $collection->index(
        'username',
        null,
        null,
        [
            'sparse' => true,
            'unique' => true,
            'background' => true,
        ]
    );
});

继承操作

创建和删除
集合
hasCollection
索引和dropIndex（支持复合索引）
唯一

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',
        'table' => 'jobs',
        'queue' => 'default',
        'expire' => 60,
    ],
],

如果您想使用MongoDB处理失败的任务，请更改config/queue.php中的数据库

'failed' => [
    'driver' => env('QUEUE_FAILED_DRIVER', 'database'),
    'database' => env('DB_CONNECTION', 'mongodb'),
    'table' => 'failed_jobs',
],

或者简单地将自己的QUEUE_FAILED_DRIVER环境变量设置为mongodb

QUEUE_FAILED_DRIVER=mongodb

最后，在config/app.php中添加服务提供程序

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，而不是一个自定义的Collection类。如果您使用过这些特殊方法之一，请将它们转换为Collection操作。

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

安全联系信息

要报告安全漏洞，请遵循这些步骤。

binaryx-dev / mongodb

维护者

详细信息

README

安装

Laravel版本兼容性

Laravel

Lumen

非Laravel项目

测试

数据库测试

配置

Eloquent

扩展基本模型

软删除

日期

基本用法

MongoDB特定运算符

MongoDB特定地理空间运算

插入、更新和删除

MongoDB特定操作

关系

基本用法

belongsToMany和枢轴

EmbedsMany关系

EmbedsOne关系

查询构建器

基本用法

可用操作

模式

基本用法

地理空间索引

扩展

跨数据库关系

身份验证

队列

升级

从版本2升级到3

安全联系信息