PHP 操作 MongoDB 完整指南：安裝、連線、CRUD 與實戰範例

PHP 操作 MongoDB 完整指南：安裝、連線、CRUD 與實戰範例

MongoDB 是高效能、無結構描述的文件型資料庫，適合快速迭代、大量非結構化資料儲存。本文涵蓋 MongoDB 核心特性、Windows/Linux 安裝、PHP 擴展部署、連線方式、CRUD 操作與完整程式碼範例。

MongoDB 核心特性

• 文件導向：JSON-like BSON 格式，動態結構描述。
• 全索引支援：含內嵌文件、陣列索引。
• 原地更新：原子性修改器 ($set, $inc, $push...)。
• 高擴展性：Replica Set 自動故障轉移、Sharding 水平分片。
• 豐富查詢：聚合管線、MapReduce、地理空間索引。
• GridFS：儲存大型二進位檔案（圖片、影片）。

安裝與部署

Windows

1. 下載 MongoDB Community Server，解壓至 D:\mongodb。
2. 建立資料目錄 D:\mongodb\data\db。
3. 啟動：mongod --dbpath D:\mongodb\data\db。

Linux (Ubuntu)

sudo apt-get install mongodb
# 或依官方倉庫安裝最新版
sudo systemctl start mongod

PHP MongoDB 擴展安裝

Windows

下載對應 PHP 版本、執行緒安全性 (TS/Non-TS) 的 php_mongodb.dll (新版驅動) 或 php_mongo.dll (舊版 legacy)。放入 ext 目錄，php.ini 加入 extension=php_mongodb.dll，重啟 Web 伺服器。

Linux (PECL)

sudo pecl install mongodb
# 編譯需 php-dev、openssl-dev
# php.ini 加入 extension=mongodb.so

注意： 新版 mongodb 擴展 (PHP 7+) 類別命名空間為 MongoDB\Driver\Manager，舊版 mongo 擴展類別為 MongoClient，兩者 API 不相容。本文以新版為主，舊版語法標註於註解。

連線 MongoDB

// 新版 mongodb 擴展 (PHP 7+)
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
// 帶認證
$manager = new MongoDB\Driver\Manager("mongodb://user:pass@host:27017/db");
// Replica Set
$manager = new MongoDB\Driver\Manager("mongodb://host1:27017,host2:27017/?replicaSet=myReplSet");

// 舊版 mongo 擴展 (PHP 5.x)
$conn = new MongoClient("mongodb://user:pass@localhost:27017");
$db = $conn->selectDB('my_database');
$coll = new MongoCollection($db, 'my_collection');

CRUD 核心操作 (新版 MongoDB\Driver)

use MongoDB\Driver\BulkWrite;
use MongoDB\Driver\Query;
use MongoDB\Driver\Command;

// --- Insert ---
$bulk = new BulkWrite;
$bulk->insert(['name' => 'Calvin', 'email' => 'calvin@example.com', 'tags' => ['php', 'mongodb']]);
$manager->executeBulkWrite('db.collection', $bulk);

// --- Find (Query) ---
$filter = ['name' => 'Calvin'];
$options = ['projection' => ['email' => 1], 'sort' => ['_id' => -1], 'limit' => 10];
$query = new Query($filter, $options);
$cursor = $manager->executeQuery('db.collection', $query);
foreach ($cursor as $doc) {
    var_dump($doc); // 回傳 stdClass 物件
}

// --- Update ---
$bulk = new BulkWrite;
$bulk->update(
    ['name' => 'Calvin'],
    ['$set' => ['email' => 'new@example.com'], '$inc' => ['login_count' => 1]],
    ['multi' => false, 'upsert' => false]
);
$manager->executeBulkWrite('db.collection', $bulk);

// --- Delete ---
$bulk = new BulkWrite;
$bulk->delete(['name' => 'Calvin'], ['limit' => 1]);
$manager->executeBulkWrite('db.collection', $bulk);

// --- Aggregation ---
$pipeline = [
    ['$match' => ['status' => 'active']],
    ['$group' => ['_id' => '$category', 'count' => ['$sum' => 1]]],
    ['$sort' => ['count' => -1]]
];
$cmd = new Command(['aggregate' => 'collection', 'pipeline' => $pipeline, 'cursor' => new \stdClass()]);
$cursor = $manager->executeCommand('db', $cmd);

完整實戰範例：簡易文章系統

<?php
require 'vendor/autoload.php'; // 使用 mongodb/mongodb 官方庫 (高層封裝)

$client = new MongoDB\Client("mongodb://localhost:27017");
$coll = $client->blog->posts;

// 新增
$insertResult = $coll->insertOne([
    'title' => 'Hello MongoDB',
    'content' => 'First post from PHP',
    'tags' => ['php', 'mongodb', 'tutorial'],
    'created_at' => new MongoDB\BSON\UTCDateTime(),
    'author' => ['name' => 'Admin', 'email' => 'admin@example.com']
]);
echo "Inserted ID: {$insertResult->getInsertedId()}\n";

// 查詢最新 5 篇
$posts = $coll->find(
    ['status' => 'published'],
    ['sort' => ['created_at' => -1], 'limit' => 5, 'projection' => ['title' => 1, 'created_at' => 1]]
);
foreach ($posts as $post) {
    echo "{$post['created_at']->toDateTime()->format('Y-m-d')} - {$post['title']}\n";
}

// 更新：新增標籤
$coll->updateOne(
    ['_id' => $insertResult->getInsertedId()],
    ['$addToSet' => ['tags' => 'beginner']]
);

常見問題與最佳實踐

• ID 型別：_id 預設為 MongoDB\BSON\ObjectId，前端傳輸時轉字串 (string)$id，查詢時需建立 new MongoDB\BSON\ObjectId($idStr)。
• 游標迭代：executeQuery 回傳 MongoDB\Driver\Cursor，不可重複迭代，需一次性轉陣列或即時處理。
• 寫入關注：BulkWrite 可設定 writeConcern (w=majority, j=true) 確保資料持久化。
• 索引建立：$db->command(['createIndexes' => 'coll', 'indexes' => [['key' => ['email' => 1], 'unique' => true]]])。