README

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

Laravel MongoDB

安装

请确保您已安装MongoDB PHP驱动。您可以在以下位置找到安装说明：[https://php.ac.cn/manual/en/mongodb.installation.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;

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

use Database Transactions;
use 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/](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();

高级 wheres

$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 (skip & take)

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

regexp 的逆操作

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 对象执行原始表达式。如果在模型类上执行此操作，它将返回一个模型集合。

如果在查询构建器上执行此操作，它将返回原始响应。

Cursor 超时

为了防止 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);

推送

向数组中添加项目。

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

拉动

从数组中删除一个项目。

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

取消设置

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

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和pivots

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
索引和删除索引（支持复合索引）
唯一

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

viitech / laravel-mongodb

维护者

详细信息

README

安装

Laravel版本兼容性

Laravel

Lumen

非Laravel项目

测试

数据库测试

配置

Eloquent

扩展基础模型

软删除

日期

基本用法

MongoDB特定运算符

MongoDB特定地理空间操作

插入、更新和删除

MongoDB特定操作

关系

基本用法

belongsToMany和pivots

EmbedsMany关系

EmbedsOne关系

查询构建器

基本用法

可用操作

模式

基本用法

地理空间索引

扩展

跨数据库关系

身份验证

队列

升级

从版本2升级到3