README

此包为MongoDB的Eloquent模型和查询构建器添加功能，使用原始的Laravel API。 此库扩展了原始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;

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

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/

'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，请替换$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';
}

扩展Authenticable基础模型

此包包括一个MongoDB Authenticatable Eloquent类Jenssegers\Mongodb\Auth\User，您可以使用它来替换您的User模型的默认Authenticatable类Illuminate\Foundation\Auth\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;

    protected $dates = ['deleted_at'];
}

有关更多信息，请参阅Laravel关于软删除的文档。

保护属性

在选择保护属性或标记某些属性为可填充时，Taylor Otwell更喜欢可填充的路径。这是由于这里描述的最近的安全问题。

请记住，保护仍然有效，但您可能会遇到意外的行为。

日期

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

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

偏移量 & 限制（跳过 & 取出）

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

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和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连接时，您将能够构建流畅的查询以执行数据库操作。

为了方便起见，除了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',
        // 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，而不是自定义的 Collection 类。如果你正在使用其中一种特殊方法，请将其转换为 Collection 操作。

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

安全联系方式

要报告安全漏洞，请遵循以下步骤。

app-accounts / mongodb

维护者

详细信息

README

安装

Laravel版本兼容性

Laravel

Lumen

非Laravel项目

测试

数据库测试

配置

Eloquent

扩展基础模型

扩展Authenticable基础模型

软删除

保护属性

日期

基本用法

MongoDB特定操作符

MongoDB特定地理空间操作

插入、更新和删除

MongoDB特定操作

关系

基本用法

belongsToMany和pivots

EmbedsMany关系

EmbedsOne关系

查询构建器

基本用法

可用操作

模式

基本用法

地理空间索引

扩展

跨数据库关系

身份验证

队列

Laravel特定

Lumen特定

升级

从版本2升级到3

安全联系方式