maer/mongo-query

PHP 的 MongoDB 查询构建器

0.2.1 2023-10-04 13:25 UTC

This package is auto-updated.

Last update: 2024-09-04 16:19:15 UTC


README

原因?因为用 PHP 编写 MongoDB 查询感觉不自然,很快就会变得难以阅读。

这仍在开发中,API 可能会在 1.x 版本发布之前发生变化。

注意: 这只是一个对 mongodb/mongodb-库的包装器,如果您想执行该包装器不支持的操作,您始终可以访问底层库。

用法

安装

克隆此存储库或使用 composer(推荐)以以下命令下载库

composer require maer/mongo-query

简单示例

// Load composers autoloader
include '/path/to/vendor/autoload.php';

// Instatiate with no arguments and a MongoDB\Client instance will be created
// (using localhost and default port)
$client = new Maer\MongoQuery\Connection();

// To use a custom client instance, pass it as the first argument
$client = $client = new Maer\MongoQuery\Connection(
    new MongoDB\Client('mongodb://example.com:1234')
);


// Get a database
$db = $client->myDatabase; // Or: $client->getDatabase('myDatabase');

// Get a collection
$collection = $db->myCollection; // Or: $db->getCollection('myCollection');

// Add some criterias
$result = $collection->where('some-key', 'some-value')
    ->orderBy('some-key', 'asc')
    ->get();

// $result will now contain an array with the matched documents

这只是一个简单示例。请阅读下面以获取更多信息...

查询构建器

插入

您可以选择插入一个文档

$id = $collection->insert([
    'some-key' => 'some-value',
]);

// $id contains the new id for the inserted document or false on error

或者一次插入多个

$ids = $collection->insert([
    [
        'some-key' => 'some-value',
    ],
    [
        'some-key' => 'some-other-value',
    ]
]);

// $ids contains an array of the new ids for the inserted documents or false on error

获取数据

以下大多数项目将返回一个包含匹配项目的多维数组。

获取项目列表

$result = $collection->get();

获取第一个项目

返回第一个匹配项。

$result = $collection->first();

查找

获取匹配单个条件的第一个项目。

// Find by _id (default)
$result = $collection->find('123');

// Find by some other key (is equal to)
$result = $collection->find('some-value', 'some-key');

这是唯一不能有任何其他标准的“获取器”。

计数

要获取匹配文档的总数,请使用

$result = $collection->where('some-key', 'some-value')->count();
// $result is an integer with the number of matched documents

所有返回实际结果的方法也将重置查询(删除之前添加的任何标准)。

对于 count() 而言,可能存在您不希望这种情况的情况(例如,当您构建分页时)。为了保留所有标准,您可以向 count()-方法传递 falsecount(false)

如果您传递 false,您可以这样做

$result = $colletion->get();

它将只返回匹配先前标准的文档。

条件

通常,您只想返回符合某些标准的一些特定项目。

$result = $collection->where('some-key', 'some-value')->get();

上述内容将匹配所有具有 some-value 作为 some-key 键值的项。这等于: where('some-key', '=', 'some-value')

运算符

您可以使用许多其他运算符来缩小结果。

以下运算符的用法如下: where($column, $operator, $value)

您可以将任意多的条件添加到相同的查询中。为了使其更容易,您可以将它们链接起来

$result = $collection->where('some-key', '=', 'some-value')
    ->where('some-other-key', '!=', 'some-other-value')
    ...
    ->get();

或条件

要添加或 $or-块,请使用 orWhere()

$collection->orWhere('some-key', 'some-value')
    ->orWhere('some-other-key', 'some-other-value');

// Same as:
// [
//     '$or' => [
//         [
//             'some-key' => 'some-value',
//         ],
//         [
//             'some-other-key' => 'some-other-value'
//         ]
//     ],
// ]

您还可以分组或条件

$collection->orWhere(function ($query) {
    $query->where('some-key', 'some-value')
        ->where('some-other-key', 'some-other-value');
});


// Same as:
// [
//     '$or' => [
//         [
//             'some-key' => 'some-value',
//             'some-other-key' => 'some-other-value'
//         ]
//     ],
// ]

排序

要按特定方式排序结果,请使用 orderBy(['column' => 'asc|desc'])

// Ascending order:
$result = $collection->orderBy(['first_name' => 'asc']);

// Descending order:
$result = $collection->orderBy(['first_name' => 'desc']);

限制

您可以限制返回的项目数量。

// Only get the 2 first matches
$result = $collection->people->limit(2)->get();

跳过

如果您需要添加偏移量(例如用于分页),您可以定义应跳过多少文档 skip()

// Get all results from the second match and forward.
$result = $collection->offset(2)->get();

选择

您可能只想从文档中获取一些特定字段。您可以使用 select() 定义要获取的字段

// Define what fields you want to get
$result = $collection->select(['some-key', 'some-other-key'])->get();

注意: 此方法将始终返回 _id-字段

提取

如果您只想获取一个数组中的单个字段作为所有值的数组,您可以使用 pluck()

$result = $collection->pluck('some-key');

// Returns
// [
//     'first-value',
//     'second-value',
//     ...
// ]

任何潜在的重复项也将被删除。

更新

要更新项目,请使用 updateOne(array $data)

$modified = $collection->where('some-key', 'some-value')
    ...
    ->updateOne([
        'some-key' => 'some-new-value',
    ]);

要更新多个项目,请使用 updateMany(array $data)

$modified = $collection->where('some-key', 'some-value')
    ...
    ->updateMany([
        'some-key' => 'some-new-value',
    ]);

这些方法返回已修改的文档数量。

在更新时,您只需传递您想要更新的字段和值。其他所有值将保持数据库中的原始状态。

替换

这些方法和更新之间的区别在于,这些方法会替换完整的文档,除了_id之外。例如

$modified = $collection->insert([
    'foo'     => 'Lorem',
    'bar'     => 'Ipsum',
]);

$modified = $collection->where('foo', 'Lorem')
    ->replaceOne([
        'foo_bar' => 'Lorem Ipsum',
    ]);

$result = $collection->first();
// Returns:
// [
//     '_id'      => xxx,
//     'foo_bar' => 'Lorem Ipsum',
// ]

删除

删除项目

$result = $collection->where('some-key', 'some-value')
    ->deleteOne();

要删除多个项目,请使用deleteMany()

这些方法返回已修改的文档数量。

附加

MongoDB 实例

有时您可能想要执行一些这个库(目前)不支持的操作。为了做到这一点,您可能需要访问底层的MongoDB实例。您可以使用getInstance()方法来做到这一点。

$mongo = new Maer\MongoQuery\Connection;

// Get MongoDB\Client
$client = $mongo->getClient();

// Get MongoDB\Database
$database = $mongo->someDatabase->getDatabase();

// Get MongoDB\Collection
$collection = $mongo->someDatabase->someCollection->getCollection();

如果您有任何问题、建议或问题,请告诉我!

祝您编码愉快!