PHP 連接 Oracle 資料庫最佳實踐：Windows/Linux 下安裝配置 OCI8 + Instant Client 完整指南

架構選擇：為什麼選 Instant Client + OCI8？

• Instant Client：輕量級 (約 80 MB)，無需完整 Oracle Client 安裝，適合應用伺服器部署。
• OCI8 擴展：PHP 官方推薦的高效能 Oracle 介面 (C 層)，支援 8i~19c+；舊 oracle 擴展已棄用。
• 抽象層建議：PDO_OCI (原生 PDO)、PEAR MDB2、ADOdb 簡化開發。

Windows 環境部署步驟

1. 安裝 Apache + PHP (建議 PHP 7.4+/8.x)，驗證 php -v 正常。
2. 下載 Instant Client Basic (Windows x64)：
   從 OTN 下載 instantclient-basic-windows.x64-19.x.x.x.x.zip (或 11g/12c/18c 版本)。
3. 解壓至固定目錄，如 C:\instantclient_19_12，確認包含：
   oci.dll, oraociei19.dll, oraons.dll 等核心 DLL。
4. 加入系統 PATH 環境變數 (置於其他 Oracle 路徑之前)：
   C:\instantclient_19_12
5. 配置 TNSNAMES (可選)：
   將 tnsnames.ora 放入上述目錄，設定用戶環境變數 TNS_ADMIN=C:\instantclient_19_12。
6. 設定 NLS_LANG (重要)：
   系統變數 NLS_LANG=TRADITIONAL CHINESE_TAIWAN.ZHT16MSWIN950 (或 .AL32UTF8)，避免中文亂碼。
7. 啟用 PHP OCI8 擴展：
   編輯 php.ini：
   extension=oci8 (PHP 7.2+ 無需 _12c 後綴)
   extension_dir = "C:\php\ext" (確認路徑正確)
8. 重啟 Apache，瀏覽 phpinfo() 確認出現 oci8 區塊且顯示 OCI8 Support enabled。

Linux 環境部署步驟 (以 Oracle Linux / RHEL / CentOS 為例)

1. 安裝編譯工具與相依套件：

   yum install -y gcc make libaio-devel php-devel php-pear httpd-devel

2. 下載並安裝 Instant Client RPM (Basic + SDK)：

   # 範例 19.12 版
   rpm -Uvh oracle-instantclient19.12-basic-19.12.0.0.0-1.x86_64.rpm
   rpm -Uvh oracle-instantclient19.12-devel-19.12.0.0.0-1.x86_64.rpm

   安裝路徑：
   庫檔：/usr/lib/oracle/19.12/client64/lib/
   頭檔：/usr/include/oracle/19.12/client64/

3. 編譯安裝 OCI8 擴展 (PECL)：

   pecl install oci8
   # 互動提示輸入：instantclient,/usr/lib/oracle/19.12/client64/lib

   或手動編譯：

   cd /tmp
   pecl download oci8
   tar xzf oci8-*.tgz
   cd oci8-*
   phpize
   ./configure --with-oci8=instantclient,/usr/lib/oracle/19.12/client64/lib
   make && make install

4. 配置 PHP 與 Apache 環境變數：

   編輯 /etc/sysconfig/httpd (或 apachectl 腳本) 加入：

   export LD_LIBRARY_PATH=/usr/lib/oracle/19.12/client64/lib:$LD_LIBRARY_PATH
   export TNS_ADMIN=/etc/oracle  # 放置 tnsnames.ora 目錄
   export NLS_LANG=TRADITIONAL_CHINESE_TAIWAN.AL32UTF8

5. 啟用擴展並重啟：

   echo "extension=oci8.so" > /etc/php.d/oci8.ini
   systemctl restart httpd

6. 驗證：php -m | grep oci8 及 phpinfo()。

連線字串三種寫法

// 1. Easy Connect (無需 tnsnames.ora)
$conn = oci_connect('hr', 'password', '//db-host:1521/ORCLPDB1');

// 2. TNS 別名 (需 TNS_ADMIN 指向 tnsnames.ora)
$conn = oci_connect('hr', 'password', 'MY_TNS_ALIAS');

// 3. 環境變數 TWO_TASK (Linux) / LOCAL (Windows) 設定預設連線
// export TWO_TASK=MY_TNS_ALIAS
$conn = oci_connect('hr', 'password');

簡易測試腳本

<?php
$conn = oci_connect('hr', 'password', '//db-host:1521/ORCLPDB1');
if (!$conn) { $e = oci_error(); die(htmlentities($e['message'])); }

$stid = oci_parse($conn, 'SELECT table_name FROM user_tables');
oci_execute($stid);

echo "<table border=1><tr><th>TABLE_NAME</th></tr>";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
    echo "<tr><td>".htmlentities($row['TABLE_NAME'])."</td></tr>";
}
echo "</table>";

oci_free_statement($stid);
oci_close($conn);
?>

常見故障排查

結語

Instant Client + OCI8 是 PHP 連接 Oracle 最輕量、效能最佳、維護最簡單的組合。關鍵在於：**統一 64-bit 架構、正確設定 PATH/LD_LIBRARY_PATH/TNS_ADMIN/NLS_LANG、善用 Easy Connect 簡化部署**。