MongoDB - Knowledge of Laravel

簡介

MongoDB 是最受歡迎的 NoSQL 文件導向資料庫之一。特色包含高寫入效能（適合分析與 IoT）、高可用性（透過 replica set 自動故障轉移）、水平擴充（sharding），以及強大的查詢語言（聚合、全文檢索、地理空間查詢）。與 SQL 資料庫的列 / 欄形式不同，MongoDB 的每筆資料都是 BSON（binary JSON）形式的文件。應用程式可以以 JSON 格式取得這些資料。

在 Laravel 中使用 MongoDB，建議使用官方維護的 mongodb/laravel-mongodb 套件。它提供與 Eloquent 及 Laravel 各功能的豐富整合。

安裝

MongoDB PHP 驅動

要連線至 MongoDB 需要 mongodb PHP 擴充。若你使用 Laravel Herd 或 php.new，通常已預先安裝。手動安裝請透過 PECL：

pecl install mongodb

詳細請參閱 MongoDB PHP 擴充安裝指南。

請確認 mongodb PHP 擴充在 CLI 與 Web 伺服器兩邊都已啟用，因為設定可能不同。

啟動 MongoDB 伺服器

MongoDB Community Server 可用於本機開發。Windows、macOS、Linux、Docker 的安裝方式請參閱官方安裝指南。 使用 Docker 時：

# docker-compose.yml
services:
  mongodb:
    image: mongo:8
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: password
      MONGO_INITDB_DATABASE: laravel_app
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:

docker compose up -d

雲端託管可使用 MongoDB Atlas。要從本機連線至 Atlas cluster，需將自己的 IP 加入專案的 IP 存取名單。

安裝 laravel-mongodb 套件

以 Composer 安裝 mongodb/laravel-mongodb：

composer require mongodb/laravel-mongodb

設定

環境變數

在 .env 加入 MongoDB 的連線資訊。

MONGODB_URI="mongodb://localhost:27017"
MONGODB_DATABASE="laravel_app"

若使用 MongoDB Atlas，請將連線字串換成 Atlas 的：

MONGODB_URI="mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<dbname>?retryWrites=true&w=majority"
MONGODB_DATABASE="laravel_app"

config/database.php

在 config/database.php 的 connections 陣列加入 mongodb：

'connections' => [

    // ... 既有連線設定 ...

    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => env('MONGODB_URI', 'mongodb://localhost:27017'),
        'database' => env('MONGODB_DATABASE', 'laravel_app'),
    ],

],

若要同時使用 MySQL 等關聯式資料庫與 MongoDB，default 保持不變，只要加入 mongodb 連線即可。可依模型切換連線。

主要功能

Eloquent 模型

繼承 MongoDB\Laravel\Eloquent\Model 即可用幾乎相同的操作方式使用 MongoDB。

<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'articles'; // Collection 名（省略時由類別名自動產生）

    protected $fillable = [
        'title',
        'body',
        'tags',
        'published_at',
    ];
}

MongoDB 為 schema-less，不需要 migration。儲存文件時 collection 會自動建立。

基本 CRUD 操作

可以與一般 Eloquent 一樣使用相同的 API。

use App\Models\Article;

// 建立
$article = Article::create([
    'title' => 'MongoDB 入門',
    'body' => 'MongoDB 是一款文件導向資料庫。',
    'tags' => ['nosql', 'mongodb', 'laravel'],
    'published_at' => now(),
]);

// 取得
$article = Article::find('64f1a2b3c4d5e6f7a8b9c0d1');
$articles = Article::where('tags', 'nosql')->get();

// 更新
$article->update(['title' => '改訂版 MongoDB 入門']);

// 刪除
$article->delete();

陣列與內嵌文件

可直接運用 MongoDB 的陣列與內嵌文件優勢：

// 對陣列欄位 push
$article->push('tags', 'database');

// 從陣列欄位 pull
$article->pull('tags', 'nosql');

// 對內嵌文件查詢
$articles = Article::where('meta.author', 'Taylor')->get();

Query Builder

可用 MongoDB 的 Query Builder 撰寫較複雜的查詢，詳細請見 laravel-mongodb Query Builder 文件。

use Illuminate\Support\Facades\DB;

// 基本查詢
$articles = DB::connection('mongodb')
    ->collection('articles')
    ->where('tags', 'laravel')
    ->orderBy('published_at', 'desc')
    ->limit(10)
    ->get();

// 匯總管線
$stats = DB::connection('mongodb')
    ->collection('orders')
    ->raw(function ($collection) {
        return $collection->aggregate([
            ['$group' => ['_id' => '$status', 'total' => ['$sum' => '$amount']]],
            ['$sort' => ['total' => -1]],
        ]);
    });

快取驅動

MongoDB 快取驅動會透過 TTL 索引自動刪除過期項目。詳細請見快取驅動文件。在 config/cache.php 加入 store：

'stores' => [

    'mongodb' => [
        'driver' => 'mongodb',
        'connection' => 'mongodb',
        'collection' => 'cache',
    ],

],

.env 中將快取驅動改為 MongoDB：

CACHE_STORE=mongodb

佇列驅動

也可以將 MongoDB 作為佇列驅動使用。詳細請見佇列驅動文件。在 config/queue.php 加入連線：

'connections' => [

    'mongodb' => [
        'driver' => 'mongodb',
        'connection' => 'mongodb',
        'collection' => 'jobs',
        'queue' => env('MONGODB_QUEUE', 'default'),
        'retry_after' => (int) env('MONGODB_QUEUE_RETRY_AFTER', 90),
        'after_commit' => false,
    ],

],

.env 中改為 MongoDB：

QUEUE_CONNECTION=mongodb

以 GridFS 儲存檔案

可使用 MongoDB 的 GridFS 儲存檔案，需要 Flysystem 的 GridFS adapter。詳細請見 GridFS 文件。

composer require league/flysystem-gridfs

在 config/filesystems.php 加入 disk：

'disks' => [

    'gridfs' => [
        'driver' => 'gridfs',
        'connection' => 'mongodb',
        'database' => env('MONGODB_DATABASE', 'laravel_app'),
    ],

],

use Illuminate\Support\Facades\Storage;

// 上傳檔案
Storage::disk('gridfs')->put('file.pdf', $contents);

// 取得檔案
$contents = Storage::disk('gridfs')->get('file.pdf');

向量搜尋（Vector Search）

透過 MongoDB Atlas Vector Search 可依向量嵌入進行相似度搜尋。將文字、圖片、音訊等資料向量化後儲存，找出最接近查詢向量的文件；這是為 AI / 機器學習量身打造的搜尋機能。

向量搜尋僅能在 MongoDB Atlas 使用，本機 MongoDB Community Server 或自架環境無法使用。事先需在 Atlas 主控台建立 Vector Search 索引。

在 Query Builder 中使用 vectorSearch：

use App\Models\Article;

// 由查詢字串生成 embedding（例如：OpenAI API 等）
$queryVector = getEmbedding('MongoDB 是什麼'); // float[] 陣列

$results = Article::query()->vectorSearch(
    index: 'vector_index',   // Atlas Vector Search 索引名
    path: 'embedding',       // 儲存向量的欄位名
    queryVector: $queryVector,
    limit: 10,               // 回傳文件數
    numCandidates: 100,      // 候選數（ANN 搜尋時指定）
);

// 每個文件會附上 vectorSearchScore
foreach ($results as $result) {
    echo $result->title . ': ' . $result->vectorSearchScore;
}

全文檢索（Scout 引擎）

可透過 mongodb Scout 引擎在 MongoDB 使用 Laravel Scout 的全文檢索。內部使用 MongoDB Atlas Search，支援模糊搜尋與萬用字元搜尋。詳細請見 Scout 引擎文件。

MongoDB Scout 引擎同樣僅能於 MongoDB Atlas 使用。Scout 的索引 collection 必須與模型的 collection 分開。config/scout.php 的 prefix（預設為應用程式名稱）會自動套用。

於 .env 將 Scout 驅動設為 mongodb：

SCOUT_DRIVER=mongodb

在模型上加入 Searchable trait：

use Laravel\Scout\Searchable;
use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    use Searchable;

    // 指定要納入索引的欄位
    public function toSearchableArray(): array
    {
        return [
            'title' => $this->title,
            'body'  => $this->body,
            'tags'  => $this->tags,
        ];
    }
}

建立 Scout 索引並匯入既有資料：

php artisan scout:index articles
php artisan scout:import "App\Models\Article"

使用標準 Scout API 進行搜尋：

// 全文檢索
$results = Article::search('MongoDB Laravel')->get();

// 附條件搜尋
$results = Article::search('Query Builder')
    ->where('status', 'published')
    ->paginate(15);

與 MySQL 並用

在 Laravel 中可同時使用 MySQL 與 MongoDB，於模型以 $connection 屬性指定連線。

// 一般 Eloquent 模型，使用 MySQL
class User extends \Illuminate\Database\Eloquent\Model
{
    protected $connection = 'mysql';
}

// 使用 MongoDB 的模型
class Article extends \MongoDB\Laravel\Eloquent\Model
{
    protected $connection = 'mongodb';
}

若要在 MySQL 模型與 MongoDB 模型之間建立關聯，請參考混合關聯（Hybrid Relations）。

總結

安裝檢查清單

pecl install mongodb 安裝 PHP 擴充
啟動 MongoDB 伺服器（本機或 Docker、或 Atlas）
composer require mongodb/laravel-mongodb 安裝套件
於 .env 設定 MONGODB_URI 與 MONGODB_DATABASE
於 config/database.php 加入 mongodb 連線

MongoDB 與 MySQL 的取捨

特性	MongoDB	MySQL
資料模型	文件（JSON/BSON）	表格（列 / 欄）
schema	schema-less（靈活）	固定 schema
擴充	水平擴充容易	以垂直擴充為主
交易	多文件（v4+）	完整 ACID
適用情境	日誌 / 分析 / IoT / 靈活結構資料	結構化資料、複雜關聯

功能整理

功能	設定位置
Eloquent 模型	繼承 `MongoDB\Laravel\Eloquent\Model`
Query Builder	`DB::connection('mongodb')->collection(...)`
快取	`config/cache.php` + `CACHE_STORE=mongodb`
佇列	`config/queue.php` + `QUEUE_CONNECTION=mongodb`
檔案儲存	`config/filesystems.php` + GridFS adapter
向量搜尋	`Model::query()->vectorSearch(...)`（需 Atlas）
全文檢索	`SCOUT_DRIVER=mongodb` + `Searchable` trait（需 Atlas）

下一步

laravel-mongodb 官方文件

Eloquent、Query Builder、關聯等所有功能的詳細參考。

快速上手

快速學習 MongoDB 與 Laravel 的基本用法。

資料庫設定

Laravel 資料庫連線設定的基礎。

Eloquent 入門

Eloquent ORM 的基本用法。

​簡介

​安裝

​MongoDB PHP 驅動

​啟動 MongoDB 伺服器

​安裝 laravel-mongodb 套件

​設定

​環境變數

​config/database.php

​主要功能

​Eloquent 模型

​基本 CRUD 操作

​陣列與內嵌文件

​Query Builder

​快取驅動

​佇列驅動

​以 GridFS 儲存檔案

​向量搜尋（Vector Search）

​全文檢索（Scout 引擎）

​與 MySQL 並用

​總結

​下一步

laravel-mongodb 官方文件

快速上手

資料庫設定

Eloquent 入門

簡介

安裝

MongoDB PHP 驅動

啟動 MongoDB 伺服器

安裝 laravel-mongodb 套件

設定

環境變數

config/database.php

主要功能

Eloquent 模型

基本 CRUD 操作

陣列與內嵌文件

Query Builder

快取驅動

佇列驅動

以 GridFS 儲存檔案

向量搜尋（Vector Search）

全文檢索（Scout 引擎）

與 MySQL 並用

總結

下一步