在 ServBay 中使用內建 SQLite 資料庫模組進行 PHP 開發

ServBay 是一套功能強大的本機 Web 開發環境，專為開發者設計，支援多種技術堆疊。它內建 SQLite 資料庫模組，讓 PHP 應用能更輕鬆地運用 SQLite 進行資料儲存與管理。本文將詳細介紹如何在 ServBay 中運用這一優勢。

SQLite 模組概述

SQLite 是一個輕量級、嵌入式的關聯式資料庫管理系統。與傳統的客戶端/伺服器式資料庫（如 MySQL、PostgreSQL）不同，SQLite 不需要獨立的伺服器程序，而是直接以函式庫的型態嵌入至應用程式中。整個資料庫僅存於單一檔案內，大大簡化了部署與管理。

由於下列特色，SQLite 廣受歡迎，特別適合中小型專案、本機快取、行動應用程式及開發與測試環境使用：

主要特點

1. 輕量小巧：核心程式庫體積極小，占用資源極低。
2. 零設定：免安裝、免設定伺服器或管理使用者權限，隨裝即用。
3. 高效能：對於多數讀取操作及適度寫入，SQLite 皆有極佳效能表現。
4. 單一檔案儲存：整個資料庫保存在一個 .sqlite 檔案中，易於備份、轉移與管理。
5. ACID 交易支援：提供可靠的交易處理，確保資料一致性與完整性。
6. 跨平台：支援多種作業系統及程式語言。

ServBay 對 SQLite 的支援

ServBay 集成多個 PHP 版本，且對應的 SQLite 擴充（如 sqlite3 和 pdo_sqlite）均已預先安裝並預設啟用。這意謂著用戶無需手動下載、編譯或設定 PHP 擴充，即可在 PHP 專案中直接使用 SQLite 相關功能。

前置條件

• 已於 macOS 安裝並執行 ServBay。
• 已在 ServBay 中啟動且運行所需的 PHP 版本。
• 需準備一個用於存放網站檔案的資料夾，建議使用 ServBay 的預設網站根目錄 /Applications/ServBay/www 或其子目錄。

如何在 ServBay 中使用 SQLite

由於 ServBay 預設已啟用 SQLite 模組，無須進行任何額外設定。PHP 環境已可直接調用 SQLite 相關函式與類別。

驗證 SQLite 擴充是否已啟用：

如欲確認 SQLite 擴充已成功載入，可藉由查看 phpinfo() 頁面：

1. 建立一個 PHP 檔案，內容為 <?php phpinfo(); ?>（例：info.php）。
2. 將該檔案放於 ServBay 網站根目錄 /Applications/ServBay/www 下的某網站資料夾（例：/Applications/ServBay/www/servbay.demo/info.php）。
3. 透過瀏覽器存取該檔案（例：http://servbay.demo/info.php）。
4. 在頁面中搜尋 "sqlite" 或 "pdo_sqlite"。若找到相關設定區塊，即表示擴充已成功啟用。

在 PHP 程式中使用 SQLite

確定 SQLite 擴充可用後，即可於 PHP 應用程式中直接利用相關 API 進行資料庫操作。PHP 提供多種 SQLite 互動方式，目前最常見為 SQLite3 類別（物件導向）及 PDO（PHP Data Objects）。

下方範例示範於 ServBay 環境下，兩種方式連接、建立資料表、插入及查詢資料。建議將這些 PHP 檔案及產生的 .sqlite 資料庫檔案，放置於您的網站專案資料夾中，例如 /Applications/ServBay/www/your-project-name/。

範例程式碼（標準 SQLite3 作法）

此法利用 PHP 內建 SQLite3 類別，提供物件導向的 API 操作 SQLite 資料庫。

<?php
// 資料庫檔案路徑
// 建議將資料庫檔案放在網站專案資料夾下的子目錄，如 data/
$db_file = __DIR__ . '/data/servbay_demo.sqlite'; // __DIR__ 為目前腳本所在目錄

// 確保資料夾存在
if (!is_dir(__DIR__ . '/data')) {
    mkdir(__DIR__ . '/data', 0777, true);
}

// 連線至 SQLite 資料庫
// 如檔案不存在，SQLite 會自動建立
try {
    $db = new SQLite3($db_file);
    echo "成功連線至資料庫: " . $db_file . "\n";
} catch (Exception $e) {
    die("資料庫連線失敗: " . $e->getMessage());
}


// 建立資料表
// 採用 IF NOT EXISTS 防止重覆建立錯誤
$create_table_sql = "CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    age INTEGER
)";
if ($db->exec($create_table_sql)) {
    echo "資料表 'users' 已建立或已存在\n";
} else {
    echo "建立資料表失敗: " . $db->lastErrorMsg() . "\n";
}


// 插入資料
$name = 'ServBay Demo User';
$email = 'demo@servbay.test';
$age = 30;

// 使用預處理語句避免 SQL 注入
$stmt = $db->prepare("INSERT INTO users (name, email, age) VALUES (:name, :email, :age)");
$stmt->bindValue(':name', $name, SQLITE3_TEXT);
$stmt->bindValue(':email', $email, SQLITE3_TEXT);
$stmt->bindValue(':age', $age, SQLITE3_INTEGER);

// 執行插入，並檢查是否成功（email 為 UNIQUE，重複插入將失敗）
if ($stmt->execute()) {
    echo "資料插入成功: Name=" . $name . ", Email=" . $email . "\n";
} else {
    // 檢查是否為唯一約束錯誤
    if (strpos($db->lastErrorMsg(), 'UNIQUE constraint failed') !== false) {
         echo "資料插入失敗: Email '" . $email . "' 已存在\n";
    } else {
        echo "資料插入失敗: " . $db->lastErrorMsg() . "\n";
    }
}
$stmt->close(); // 關閉預處理語句


// 查詢資料
$search_name = 'ServBay Demo User';
$query_sql = "SELECT id, name, email, age FROM users WHERE name = :name";
$stmt = $db->prepare($query_sql);
$stmt->bindValue(':name', $search_name, SQLITE3_TEXT);

$result = $stmt->execute();

echo "查詢結果:\n";
$found = false;
while ($row = $result->fetchArray(SQLITE3_ASSOC)) {
    print_r($row);
    $found = true;
}
if (!$found) {
    echo "查無符合資料\n";
}

$result->finalize(); // 釋放結果集資源
$stmt->close(); // 關閉預處理語句


// 關閉資料庫連線
$db->close();
echo "資料庫連線已關閉\n";

?>

範例程式碼（PDO 作法）

PDO（PHP Data Objects）提供統一的資料庫抽象層，使用相同的函式即可存取不同類型的資料庫。建議使用 PDO 來連線 SQLite，彈性更高且支援更多資料庫系統。

<?php
// 資料庫檔案路徑
// 建議將資料庫檔案放在網站專案資料夾下的子目錄，如 data/
$db_file = __DIR__ . '/data/servbay_demo_pdo.sqlite'; // __DIR__ 為目前腳本所在目錄

// 確保資料夾存在
if (!is_dir(__DIR__ . '/data')) {
    mkdir(__DIR__ . '/data', 0777, true);
}

try {
    // 建立新的 PDO 執行個體
    // DSN (Data Source Name) 格式為 'sqlite:資料庫檔案路徑'
    $dsn = 'sqlite:' . $db_file;
    $pdo = new PDO($dsn);

    // 設定錯誤模式為拋出例外，便於偵錯
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    // 設定預設的 fetch 模式，例如關聯陣列
    $pdo->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_ASSOC);

    echo "成功連線至資料庫: " . $db_file . "\n";

    // 建立資料表
    $create_table_sql = "CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        name TEXT NOT NULL,
        email TEXT UNIQUE NOT NULL,
        age INTEGER
    )";
    $pdo->exec($create_table_sql);
    echo "資料表 'users' 已建立或已存在\n";


    // 插入資料
    $name = 'ServBay PDO User';
    $email = 'pdo_demo@servbay.test';
    $age = 35;

    // 使用預處理語句
    $stmt = $pdo->prepare("INSERT INTO users (name, email, age) VALUES (:name, :email, :age)");

    // 執行插入並檢查是否成功（email 為 UNIQUE，重複插入會失敗）
    try {
        $stmt->execute([
            ':name' => $name,
            ':email' => $email,
            ':age' => $age
        ]);
        echo "資料插入成功: Name=" . $name . ", Email=" . $email . "\n";
    } catch (PDOException $e) {
         // 檢查是否唯一約束錯誤 (SQLite 錯誤碼 19)
         if ($e->getCode() == '23000' || strpos($e->getMessage(), 'UNIQUE constraint failed') !== false) {
             echo "資料插入失敗: Email '" . $email . "' 已存在\n";
         } else {
             throw $e; // 重新丟出其他錯誤
         }
    }
    $stmt->closeCursor(); // 釋放語句資源


    // 查詢資料
    $search_name = 'ServBay PDO User';
    $stmt = $pdo->prepare("SELECT id, name, email, age FROM users WHERE name = :name");
    $stmt->execute([':name' => $search_name]);

    $data = $stmt->fetchAll(); // 取得所有結果列

    echo "查詢結果:\n";
    if ($data) {
        print_r($data);
    } else {
        echo "查無符合資料\n";
    }

    $stmt->closeCursor(); // 釋放語句資源

} catch (PDOException $e) {
    // 捕捉 PDO 例外
    echo "資料庫操作失敗: " . $e->getMessage();
    // 亦可透過 $e->getCode() 取得 SQLSTATE 錯誤碼
}

// PDO 執行結束時會自動關閉連線，無須額外呼叫 close() 方法

?>

關於資料庫檔案位置：

上方範例中，資料庫檔案（servbay_demo.sqlite 與 servbay_demo_pdo.sqlite）會建立於當前 PHP 腳本所在目錄下的 data/ 子目錄。例如，如果您的 PHP 檔案位於 /Applications/ServBay/www/my-servbay-project/index.php，那麼資料庫將位於 /Applications/ServBay/www/my-servbay-project/data/ 下。

將資料庫檔案放於網站專案資料夾的子目錄是一個良好習慣，有利於專案管理及備份。請確認 ServBay 執行用戶對該目錄擁有寫入權限（macOS 上 ServBay 的預設設定下通常無虞）。

注意事項

• SQLite 資料庫檔案屬於敏感資料，應避免遭公共存取。建議將資料庫檔案置於非 Web 可直連目錄，或透過伺服器設定（如 Caddy 或 Nginx）阻擋 .sqlite 檔案直接存取。上例僅為方便演示，將資料庫放在網站下 data/ 目錄，實際營運環境中請採更嚴謹的安全措施。
• SQLite 適合寫入並發量不高的情境。在高並發寫入狀況下，可能會遇到效能瓶頸或鎖定問題。若有高頻繁寫入需求，建議改用 MySQL 或 PostgreSQL 等客戶端/伺服器式資料庫。
• 儘管 ServBay 預設啟用 SQLite 擴充，若於 phpinfo() 中未見相關資訊，請檢查 ServBay PHP 設定，或試著重新啟動 ServBay 服務。

常見問題解答 (FAQ)

Q: 需要另外安裝 SQLite 嗎？

A: 不需要。ServBay 所附 PHP 軟體包已預設內建並啟用 SQLite 擴充，可直接於 PHP 程式碼中使用。

Q: 我的 .sqlite 資料庫檔要放哪？

A: 建議放於您網站專案目錄下，並避免放在 Web 可直接存取的目錄裡（如 data/ 或 database/），以提升安全性。上述程式碼用 __DIR__ . '/data/' 指定相對路徑。

Q: 為何我的 PHP 無法連線或建立 SQLite 資料庫檔案？

A: 請檢查：

• ServBay 已執行，並且您確實透過 ServBay 存取該 PHP 檔案。
• phpinfo() 輸出有「sqlite3」及「pdo_sqlite」擴充啟動資訊。
• 資料庫存放目錄已存在，且 ServBay 執行用戶具備寫入權限。

小結

ServBay 為 PHP 開發者帶來便利的 SQLite 資料庫支援。透過 ServBay 內建且預設啟用的 SQLite 模組，您能輕鬆在本機進行基於 SQLite 的應用開發與測試，無須繁瑣的安裝與設定。結合 SQLite 的輕巧與零設定特性，ServBay 成為高效、易用的本地開發利器。