PHP 操作 Oracle CLOB 欄位完整指南

PHP 操作 Oracle CLOB 欄位完整指南

使用 PDO 操作 Oracle 時，CLOB（Character Large Object）欄位因體積大、型別特殊，讀寫方式與 VARCHAR2 截然不同。本文說明正確的繫結寫入與資源流讀取方法。

環境需求

• PHP 7.2+
• PDO_OCI 或 OCI8 擴充套件
• Oracle Client 正確配置

一、寫入 CLOB：必須顯式繫結長度

預設 PDO 將參數視為 PARAM_STR 並限制預設長度，直接 execute() 會導致資料截斷或錯誤。

正確寫法：bindParam + 指定長度

$sql = "INSERT INTO articles (id, content) VALUES (:id, :content)";
$stmt = $pdo->prepare($sql);

$id = 1;
$content = str_repeat('長文本內容...', 10000); // 超過 4000 字元

// 關鍵：第四參數指定字串長度
$stmt->bindParam(':id', $id, PDO::PARAM_INT);
$stmt->bindParam(':content', $content, PDO::PARAM_STR, strlen($content));

$stmt->execute();

替代方案：bindValue（一次性綁定）

$stmt->bindValue(':content', $content, PDO::PARAM_STR, strlen($content));

二、讀取 CLOB：處理資源流

PDO 取出 CLOB 欄位時，若非 NULL 會回傳 資源型別，需用 stream_get_contents() 讀取實際字串。

標準讀取模式

$stmt = $pdo->query("SELECT id, content FROM articles WHERE id = 1");
$row = $stmt->fetch(PDO::FETCH_ASSOC);

// 判斷是否為資源並讀取
if (is_resource($row['content'])) {
    $row['content'] = stream_get_contents($row['content']);
}

// 現在 $row['content'] 為純字串，可直接 echo、json_encode 等
echo $row['content'];

封裝為通用 Helper

function fetchClobRow(PDOStatement $stmt): ?array {
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if (!$row) return null;
    foreach ($row as $key => $val) {
        if (is_resource($val)) {
            $row[$key] = stream_get_contents($val);
        }
    }
    return $row;
}

// 使用
$stmt = $pdo->prepare("SELECT * FROM articles WHERE id = ?");
$stmt->execute([1]);
$article = fetchClobRow($stmt);

三、完整 CRUD 範例

class ArticleRepository {
    private PDO $pdo;

    public function __construct(PDO $pdo) { $this->pdo = $pdo; }

    public function create(string $title, string $content): int {
        $sql = "INSERT INTO articles (title, content, created_at) 
                VALUES (:title, :content, SYSTIMESTAMP) 
                RETURNING id INTO :id";
        $stmt = $this->pdo->prepare($sql);
        $stmt->bindParam(':title', $title, PDO::PARAM_STR);
        $stmt->bindParam(':content', $content, PDO::PARAM_STR, strlen($content));
        $stmt->bindParam(':id', $id, PDO::PARAM_INT, 32);
        $stmt->execute();
        return $id;
    }

    public function findById(int $id): ?array {
        $stmt = $this->pdo->prepare("SELECT id, title, content, created_at FROM articles WHERE id = :id");
        $stmt->bindParam(':id', $id, PDO::PARAM_INT);
        $stmt->execute();
        $row = $stmt->fetch(PDO::FETCH_ASSOC);
        if (!$row) return null;
        if (is_resource($row['content'])) {
            $row['content'] = stream_get_contents($row['content']);
        }
        return $row;
    }

    public function update(int $id, string $title, string $content): bool {
        $sql = "UPDATE articles SET title = :title, content = :content WHERE id = :id";
        $stmt = $this->pdo->prepare($sql);
        $stmt->bindParam(':id', $id, PDO::PARAM_INT);
        $stmt->bindParam(':title', $title, PDO::PARAM_STR);
        $stmt->bindParam(':content', $content, PDO::PARAM_STR, strlen($content));
        return $stmt->execute();
    }
}

常見坑點與解決

效能建議

• 頻繁讀寫大 CLOB 考慮改用 OCI-Lob::writeTemporary、OCI-Lob::read 底層 OCI8 API
• 資料庫端啟用 ENABLE STORAGE IN ROW 讓小於 4KB 的 CLOB 直接存表內
• 適當建立 CTXSYS.CONTEXT 全文索引支援搜尋

掌握「寫入指定長度、讀取轉字串」兩大核心，即可在 PHP 中順暢操作 Oracle CLOB。