PHP OCI8 操作 Oracle 資料庫封裝類實作

PHP OCI8 操作 Oracle 資料庫封裝類實作

OCI8 是 PHP 連接 Oracle 資料庫的標準擴展。本文展示一個完整的資料庫操作封裝類，涵蓋連接管理、查詢執行、結果集獲取、錯誤處理與資源釋放等核心功能。

Oracle_db 類別完整實作

<?php
class Oracle_db {
    public $link;

    public function __construct() {
        $this->link = $this->connect();
        if (!$this->link) {
            die("Oracle 連接失敗: " . $this->error());
        }
    }

    // 建立連接
    public function connect() {
        // oci_connect(使用者, 密碼, 連接字串, 字元集)
        return oci_connect('demo', 'demo', 'localhost/xe', 'AL32UTF8');
    }

    // 執行 SQL 陳述式
    public function execute($sql) {
        $stid = oci_parse($this->link, $sql);
        if (!$stid) {
            return array(false, false);
        }
        $result = oci_execute($stid);
        return array($stid, $result);
    }

    // 取得單行關聯陣列
    public function fetch_assoc($stid) {
        return oci_fetch_assoc($stid);
    }

    // 取得單筆記錄並釋放語句
    public function fetch_one($stid) {
        $arr = $this->fetch_assoc($stid);
        $this->free($stid);
        return $arr;
    }

    // 取得所有記錄並釋放語句
    public function fetch_all($stid) {
        $arr = array();
        while ($row = $this->fetch_assoc($stid)) {
            $arr[] = $row;
        }
        $this->free($stid);
        return $arr;
    }

    // 取得影響列數
    public function num_rows($stmt) {
        return oci_num_rows($stmt);
    }

    // 取得錯誤資訊
    public function error() {
        return oci_error($this->link);
    }

    // 釋放語句資源
    public function free($stid) {
        return oci_free_statement($stid);
    }

    // 伺服器版本
    public function server_version() {
        return oci_server_version($this->link);
    }

    // 客戶端版本
    public function client_version() {
        return oci_client_version();
    }

    // 解構時關閉連接
    public function __destruct() {
        if ($this->link) {
            oci_close($this->link);
        }
    }
}
?>

使用範例

<?php
require_once 'Oracle_db.class.php';

$db = new Oracle_db();

// 查詢範例
list($stid, $success) = $db->execute("SELECT * FROM users WHERE status = 1");
if ($success) {
    $users = $db->fetch_all($stid);
    foreach ($users as $user) {
        echo "ID: {$user['ID']}, Name: {$user['NAME']}<br>";
    }
} else {
    echo "查詢失敗: " . $db->error();
}

// 插入範例
list($stid, $success) = $db->execute(
    "INSERT INTO logs (msg, created_at) VALUES ('測試訊息', SYSDATE)"
);
if ($success) {
    echo "新增成功，影響列數: " . $db->num_rows($stid);
}
?>

關鍵最佳實務

1. 連接字串格式：host/service_name 或 //host:port/service_name，支援 EZConnect 語法
2. 字元集指定：務必指定 AL32UTF8 避免中文亂碼
3. 繫結變數：生產環境應使用 oci_bind_by_name() 防止 SQL 注入
4. 資源管理：每個 statement 用畢即釋放，長連接環境需注意連接池設定
5. 錯誤處理：oci_error() 可接受 connection、statement 或無參數，回傳陣列含 code、message、offset、sqltext

常見問題排查

• ORA-12154：TNS 解析失敗，檢查 tnsnames.ora 或使用 EZConnect 語法
• ORA-28001：密碼過期，需在 SQL*Plus 中修改密碼
• 中文亂碼：確認資料庫 NLS_CHARACTERSET 為 AL32UTF8，PHP 端指定相同字元集
• 連接數耗盡：調整 Oracle PROCESSES/SESSIONS 參數，或啟用 PHP 端持久連接 oci_pconnect()

此封裝類提供了基本的 CRUD 操作介面，實際專案可延伸加入交易控制、預處理語句快取、查詢日誌等進階功能。