PHP 與 Oracle 10g Instant Client 輕量級連線部署全指南 (Windows/Linux)

2. 部署庫檔

# 建議目錄
C:\instantclient_21_10\
  oci.dll
  oraociei21.dll
  orannzsbb21.dll
  # 若使用舊版 PHP oracle 擴充 (php_oci8.dll) 需 ociw32.dll 而非 oci.dll

3. 環境變數配置 (關鍵!)

• PATH：系統變數 → Path → 新增 C:\instantclient_21_10，**置於最頂端** (優先於其他 Oracle Home)。
• TNS_ADMIN (可選)：使用者變數 → C:\instantclient_21_10，將 tnsnames.ora, sqlnet.ora 放在此目錄。
• NLS_LANG：AMERICAN_AMERICA.AL32UTF8 (或 TRADITIONAL CHINESE_TAIWAN.ZHT16MSWIN950)，避免中文亂碼。
• 不需設定：ORACLE_HOME, ORACLE_SID (Instant Client 不使用)。

4. 啟用 PHP OCI8 擴充

; php.ini
extension=oci8
; PHP 7/8: extension_dir = "C:\php\ext"
; PHP 5: extension_dir = "C:\php\extensions"

重啟 Apache / PHP-FPM / IIS (FastCGI)。

5. 驗證

<?php phpinfo(); ?>

瀏覽器開啟，搜尋 oci8 區塊 → 應顯示 OCI8 Support => enabled、Oracle Run-time Client Library Version => 21.x。

Linux 部署步驟 (RHEL/CentOS/Ubuntu/Debian)

1. 安裝 RPM/DEB 套件 (推薦)

# Oracle Linux / RHEL / CentOS (yum/dnf)
dnf install -y oracle-instantclient21.10-basic oracle-instantclient21.10-devel

# Ubuntu / Debian (轉換 RPM 或使用 Alien)
alien -i oracle-instantclient21.10-basic-*.rpm
alien -i oracle-instantclient21.10-devel-*.rpm

# 安裝路徑通常為：
# /usr/lib/oracle/21.10/client64/lib/ (庫檔)
# /usr/include/oracle/21.10/client64/ (標頭)

2. 手動解壓縮 (通用)

mkdir -p /opt/oracle/instantclient_21_10
cd /opt/oracle/instantclient_21_10
unzip instantclient-basic-linux.x64-21.10.0.0.0dbru.zip
unzip instantclient-sdk-linux.x64-21.10.0.0.0dbru.zip
# 建立軟連結 (某些舊版 PHP 需要)
ln -s libclntsh.so.21.1 libclntsh.so
ln -s libocci.so.21.1 libocci.so

3. 編譯 PHP OCI8 擴充 (PHP 7/8 內建支援 --with-oci8)

# 安裝建構依賴
dnf install -y php-devel php-pear gcc make libaio  # 或 apt install php-dev ...

# 下載 PHP 原始碼 (對應版本)
wget https://www.php.net/distributions/php-8.2.10.tar.gz
tar xzf php-8.2.10.tar.gz
cd php-8.2.10/ext/oci8

# phpize 配置
phpize
./configure --with-oci8=instantclient,/usr/lib/oracle/21.10/client64/lib
# 或手動指定 SDK 路徑
# ./configure --with-oci8=instantclient,/opt/oracle/instantclient_21_10

make && make install

# 啟用擴充
echo "extension=oci8.so" > /etc/php.d/20-oci8.ini

4. 執行階段環境變數 (必須在啟動 Apache/PHP-FPM 前設定)

# /etc/sysconfig/httpd 或 systemd drop-in
export LD_LIBRARY_PATH=/usr/lib/oracle/21.10/client64/lib:$LD_LIBRARY_PATH
export TNS_ADMIN=/etc/oracle  # 放置 tnsnames.ora
export NLS_LANG=AMERICAN_AMERICA.AL32UTF8

systemd 服務：

# /etc/systemd/system/httpd.service.d/oracle.conf
[Service]
Environment=LD_LIBRARY_PATH=/usr/lib/oracle/21.10/client64/lib
Environment=TNS_ADMIN=/etc/oracle
Environment=NLS_LANG=AMERICAN_AMERICA.AL32UTF8

5. 重啟服務並驗證

systemctl daemon-reload
systemctl restart httpd php-fpm
# 或 apachectl restart

連線字串最佳實踐

測試腳本

<?php
$conn = oci_connect('hr', 'hr_password', '//dbhost:1521/ORCLPDB');
if (!$conn) { $e = oci_error(); die(htmlentities($e['message'])); }

$stid = oci_parse($conn, 'SELECT table_name FROM user_tables ORDER BY table_name');
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);
?>

故障排查速查表