MongoDB PHP 驅動基礎操作指南：連接、CRUD、查詢條件、更新運算子

MongoDB PHP 驅動基礎操作指南：連接、CRUD、查詢條件、更新運算子

本文基於舊版 mongodb/mongodb (PHP Library) 或 ext-mongo (legacy) 的常見用法整理。新專案請使用官方 mongodb/mongodb Composer 套件 (PHP 7.1+)，底層依賴 ext-mongodb 擴展。以下提供核心 API 速查與實用範例。

環境準備

# 安裝擴展 (PECL)
pecl install mongodb

# Composer 專案
composer require mongodb/mongodb

php.ini 加入 extension=mongodb.so (或 php_mongodb.dll)。

連接與資料庫/集合存取

selectDatabase('myapp');          // $client->myapp
$collection = $db->selectCollection('users');    // $db->users

插入文件

insertOne([
    'name' => 'Wang Wu',
    'age' => 25,
    'tags' => ['php', 'mongodb'],
    'created_at' => new MongoDB\BSON\UTCDateTime(),
]);
echo "Inserted ID: " . $insertOneResult->getInsertedId();

// 批次
$insertManyResult = $collection->insertMany([
    ['name' => 'Li Si', 'age' => 30],
    ['name' => 'Zhang San', 'age' => 28],
]);
echo "Inserted IDs: " . json_encode($insertManyResult->getInsertedIds());

查詢文件

findOne(['name' => 'Wang Wu']);

// 查多筆 (游標)
$cursor = $collection->find(
    ['age' => ['$gte' => 20, '$lte' => 30]], // 條件
    ['projection' => ['name' => 1, 'age' => 1], 'sort' => ['age' => -1], 'limit' => 10]
);
foreach ($cursor as $doc) {
    print_r($doc);
}

// 計數
$count = $collection->countDocuments(['status' => 1]);

更新文件 (重點：更新運算子)

updateOne(
    ['_id' => $id],
    ['$set' => ['age' => 26, 'updated_at' => new MongoDB\BSON\UTCDateTime()]]
);

// $inc: 數值增減
$collection->updateOne(['_id' => $id], ['$inc' => ['login_count' => 1]]);

// $push / $addToSet: 陣列操作
$collection->updateOne(['_id' => $id], ['$push' => ['tags' => 'new-tag']]);
$collection->updateOne(['_id' => $id], ['$addToSet' => ['tags' => 'unique-tag']]); // 不重複

// $pull: 移除陣列元素
$collection->updateOne(['_id' => $id], ['$pull' => ['tags' => 'old-tag']]);

// 批次更新
$collection->updateMany(
    ['status' => 1],
    ['$set' => ['last_sync' => new MongoDB\BSON\UTCDateTime()]]
);

// 替換整份文件 (慎用)
$collection->replaceOne(['_id' => $id], $newDocument);

刪除文件

deleteOne(['_id' => $id]);
$collection->deleteMany(['status' => 0]); // 批次刪除

常用查詢運算子速查

索引建立 (效能關鍵)

createIndex(['email' => 1], ['unique' => true]);

// 複合索引 (查詢順序需符合前綴)
$collection->createIndex(['status' => 1, 'created_at' => -1]);

// 文字索引 (全文搜尋)
$collection->createIndex(['title' => 'text', 'content' => 'text']);
// 使用: $collection->find(['$text' => ['$search' => 'mongodb php']]);

遷移提醒：legacy ext-mongo vs 新 mongodb/mongodb

強烈建議： 所有新專案直接使用 mongodb/mongodb，舊專案規劃遷移。