README

一個為 Laravel 設計的 CouchDB Eloquent ORM 套件，提供類似 Laravel Eloquent 的 API 來操作 CouchDB 資料庫。

功能特色

• Eloquent-like API: 提供熟悉的 Laravel Eloquent 語法
• 查詢建構器: 支援複雜的查詢條件和操作
• 模型關係: 基本的模型屬性和方法
• 時間戳記: 自動管理 created_at 和 updated_at
• 類型轉換: 支援屬性類型轉換
• 批量操作: 支援批量插入和更新
• 自動服務註冊: Laravel 自動發現和註冊服務

系統需求

• PHP 8.1 或更高版本
• Laravel 10.0 或更高版本
• CouchDB 3.0 或更高版本

安裝

使用 Composer 安裝套件：

composer require toolman/laravel-couchdb-eloquent

發布配置檔案：

php artisan vendor:publish --tag=couchdb-config

配置

環境變數設定

在 .env 檔案中添加 CouchDB 連線設定：

COUCHDB_HOST=http://localhost:5984
COUCHDB_DATABASE=laravel_app
COUCHDB_USERNAME=admin
COUCHDB_PASSWORD=password

初始化資料庫

執行設定命令來創建資料庫和索引：

php artisan couchdb:setup

基本使用

建立模型

<?php

namespace App\Models;

use Toolman\LaravelCouchdbEloquent\Models\CouchDBModel;

class Post extends CouchDBModel
{
    protected $database = 'blog';
    protected $documentType = 'post';
    
    protected $fillable = [
        'title',
        'content',
        'author_id',
        'published_at'
    ];
    
    protected $casts = [
        'published_at' => 'datetime',
        'is_published' => 'boolean'
    ];
}

CRUD 操作

建立記錄

// 方法 1: 使用 create
$post = Post::create([
    'title' => '我的第一篇文章',
    'content' => '這是文章內容...',
    'author_id' => 1
]);

// 方法 2: 使用 new 和 save
$post = new Post();
$post->title = '我的第一篇文章';
$post->content = '這是文章內容...';
$post->save();

查詢記錄

// 根據 ID 查詢
$post = Post::find('document-id');

// 查詢所有記錄
$posts = Post::all();

// 條件查詢
$posts = Post::where('author_id', 1)->get();
$posts = Post::where('title', 'like', '%Laravel%')->get();

// 複雜查詢
$posts = Post::where('author_id', 1)
    ->where('is_published', true)
    ->orderBy('created_at', 'desc')
    ->limit(10)
    ->get();

更新記錄

// 更新單一記錄
$post = Post::find('document-id');
$post->title = '更新的標題';
$post->save();

// 批量更新
Post::where('author_id', 1)->update(['is_published' => true]);

刪除記錄

// 刪除單一記錄
$post = Post::find('document-id');
$post->delete();

// 批量刪除
Post::where('is_published', false)->delete();

查詢建構器

基本查詢條件

// 等於
Post::where('author_id', 1)->get();

// 不等於
Post::where('author_id', '!=', 1)->get();

// 大於/小於
Post::where('view_count', '>', 100)->get();
Post::where('created_at', '>=', '2024-01-01')->get();

// IN 查詢
Post::whereIn('author_id', [1, 2, 3])->get();

// NULL 查詢
Post::whereNull('deleted_at')->get();
Post::whereNotNull('published_at')->get();

// 存在性查詢
Post::whereExists('tags')->get();

OR 查詢

Post::where('author_id', 1)
    ->orWhere('is_featured', true)
    ->get();

排序和分頁

// 排序
Post::orderBy('created_at', 'desc')->get();
Post::orderByDesc('view_count')->get();

// 分頁
Post::skip(20)->limit(10)->get();
Post::offset(20)->limit(10)->get();

聚合查詢

// 計數
$count = Post::where('is_published', true)->count();

// 檢查存在
$exists = Post::where('slug', 'my-post')->exists();

// 取得第一筆記錄
$post = Post::where('is_featured', true)->first();
$post = Post::where('slug', 'my-post')->firstOrFail();

屬性轉換

class Post extends CouchDBModel
{
    protected $casts = [
        'published_at' => 'datetime',
        'is_published' => 'boolean',
        'view_count' => 'integer',
        'tags' => 'array',
        'metadata' => 'json',
        'categories' => 'collection'
    ];
}

存取器和修改器

class Post extends CouchDBModel
{
    // 存取器 (Accessor)
    public function getTitleAttribute($value)
    {
        return ucfirst($value);
    }
    
    // 修改器 (Mutator)
    public function setTitleAttribute($value)
    {
        $this->attributes['title'] = strtolower($value);
    }
}

範圍查詢 (Scopes)

class Post extends CouchDBModel
{
    public static function published()
    {
        return static::where('is_published', true);
    }
    
    public static function byAuthor($authorId)
    {
        return static::where('author_id', $authorId);
    }
}

// 使用範圍查詢
$posts = Post::published()->byAuthor(1)->get();

進階功能

批量操作

use Toolman\LaravelCouchdbEloquent\Services\CouchDBService;

// 批量插入
$posts = [
    ['title' => '文章 1', 'content' => '內容 1', 'doc_type' => 'post'],
    ['title' => '文章 2', 'content' => '內容 2', 'doc_type' => 'post'],
];

$service = app(CouchDBService::class);
$service->bulk($posts, 'blog');

分塊處理

Post::chunk(100, function ($posts) {
    foreach ($posts as $post) {
        // 處理每筆記錄
        $post->process();
    }
});

原始查詢

use Toolman\LaravelCouchdbEloquent\Services\CouchDBService;

$service = app(CouchDBService::class);

// 使用 Mango 查詢
$result = $service->find([
    'doc_type' => 'post',
    'author_id' => ['$gt' => 1]
], [
    'sort' => [['created_at' => 'desc']],
    'limit' => 10
]);

// 使用視圖查詢
$result = $service->view('posts', 'by_author', [
    'key' => 1,
    'include_docs' => true
]);

配置選項

模型設定

class Post extends CouchDBModel
{
    // 指定資料庫名稱
    protected $database = 'blog';
    
    // 指定文件類型
    protected $documentType = 'post';
    
    // 可批量賦值的屬性
    protected $fillable = ['title', 'content'];
    
    // 受保護的屬性
    protected $guarded = ['id', 'created_at'];
    
    // 隱藏的屬性（序列化時）
    protected $hidden = ['password'];
    
    // 是否自動時間戳記
    public $timestamps = true;
}

全域設定

在 config/couchdb.php 中設定：

return [
    'host' => env('COUCHDB_HOST', 'http://localhost:5984'),
    'database' => env('COUCHDB_DATABASE', 'laravel_app'),
    'username' => env('COUCHDB_USERNAME'),
    'password' => env('COUCHDB_PASSWORD'),
    'default_timestamps' => true,
    'timestamp_format' => 'Y-m-d H:i:s',
    'soft_deletes' => true,
    'timeout' => 30,
    'verify_ssl' => true,
];

Artisan 命令

設定資料庫

# 使用預設資料庫
php artisan couchdb:setup

# 指定資料庫
php artisan couchdb:setup --database=my_database

# 強制重新建立
php artisan couchdb:setup --force

注意事項

1. 文件 ID: CouchDB 使用 _id 作為文件 ID，模型會自動處理
2. 版本控制: CouchDB 使用 _rev 進行版本控制，更新時需要正確的版本號
3. 索引: 為了提高查詢效能，建議為常用查詢欄位建立索引
4. 文件類型: 每個模型都會自動添加 doc_type 欄位來區分不同類型的文件

錯誤處理

try {
    $post = Post::findOrFail('non-existent-id');
} catch (\Exception $e) {
    // 處理找不到文件的錯誤
}

try {
    $post = new Post();
    $post->title = 'Test';
    $post->save();
} catch (\Exception $e) {
    // 處理儲存錯誤
}

效能優化

1. 建立索引: 為常用查詢欄位建立索引
2. 批量操作: 使用批量操作來提高效能
3. 分塊處理: 處理大量資料時使用分塊
4. 選擇欄位: 只選擇需要的欄位來減少資料傳輸

測試

composer test

變更日誌

請參閱 CHANGELOG 了解最近的變更。

貢獻

請參閱 CONTRIBUTING 了解詳細資訊。

安全性漏洞

如果您發現安全性漏洞，請發送電子郵件至 lamb100@example.com。

授權條款

MIT 授權條款。請參閱 License File 了解更多資訊。