以 PHP 建立 Oracle 驅動的 SOAP Web Service 完整實作教學

一、架構概覽與必要元件

本範例建立一個 BookManager SOAP 服務，後端資料庫為 Oracle，資料表結構：

CREATE TABLE books (
  isbn     VARCHAR2(32) PRIMARY KEY,
  author   VARCHAR2(50),
  title    VARCHAR2(50),
  price    NUMBER
);

技術棧：PHP 5.6+、Oracle Instant Client、OCI8 擴充、Zend Studio（WSDL 產生）。

二、SOAP Server 核心類別：SoapServer

$server = new SoapServer('bookman.wsdl', ['soap_version' => SOAP_1_2]);
$server->setClass('BookManager');
$server->handle();

關鍵選項：soap_version、encoding、classmap（WSDL 型別對應 PHP 類別）。

三、服務類別實作兩種模式

1. 函數模式（簡單）

function add($a, $b) { return $a + $b; }
$server->addFunction('add');
// 或批次
$server->addFunction(['add', 'sub']);
// 或全部
$server->addFunction(SOAP_FUNCTIONS_ALL);

2. 類別模式（推薦，模組化）

class BookManager {
  private $db;
  public function __construct() {
    $this->db = oci_connect('demo', 'passWord', 'myOracle');
    if (!$this->db) throw new SoapFault(-1, 'DB連線失敗: '.oci_error());
  }
  private function getDB() { /* 檢查連線 */ }

  /** @param string $isbn @param string $author @param string $title @param float $price @return bool|SoapFault */
  public function addBook($isbn, $author, $title, $price) {
    $sql = "INSERT INTO books VALUES (:isbn, :author, :title, :price)";
    $st = oci_parse($this->getDB(), $sql);
    oci_bind_by_name($st, ':isbn', $isbn, 32);
    oci_bind_by_name($st, ':author', $author, 50);
    oci_bind_by_name($st, ':title', $title, 50);
    oci_bind_by_name($st, ':price', $price);
    if (!oci_execute($st)) { oci_rollback($this->getDB()); throw new SoapFault(-1, '執行失敗'); }
    oci_commit($this->getDB());
    return true;
  }
  // delBook, findBookISBNByAuthor, findBookISBNByTitle, getBookByISBN, listAllBooks ...
}

規則： 參數順序必須符合 WSDL、不可輸出內容、必須回傳值（單值或關聯陣列）。

四、錯誤處理：SOAP Fault 標準化

public function div($a, $b) {
  if ($b == 0) throw new SoapFault('Server', '除數不可為零', null, -1);
  return $a / $b;
}

客戶端以 try { } catch (SoapFault $f) { } 捕捉。

五、WSDL 產生：PHPDoc + Zend Studio 產生器

1. 在每個 public method 上方加上 PHPDoc 註解，標註 @param type $name、@return type。
2. Zend Studio → Tools → Generate WSDL → 選取類別 → 完成嚮導 → 儲存 bookman.wsdl。
3. 將 WSDL 放置於 Server 腳本同目錄，客戶端亦可透過 URL 存取。

六、SOAP Client 串接範例

$client = new SoapClient('https://example.com/bookman.wsdl', [
  'soap_version' => SOAP_1_2,
  'trace' => 1,          // 除錯用
  'exceptions' => true   // 拋出 SoapFault
]);

try {
  $isbns = $client->findBookISBNByAuthor('J.K. Rowling');
  foreach ($isbns as $isbn) {
    $book = $client->getBookByISBN($isbn);
    echo "{$book['TITLE']} - {$book['PRICE']}\n";
  }
} catch (SoapFault $e) {
  echo "SOAP 錯誤: {$e->faultstring}";
}

七、完整前端查詢頁面（HTML + PHP）

提供書名/作者搜尋表單，透過 SOAP Client 呼叫後端服務，渲染結果表格。程式碼見原文完整範例。

八、部署與效能優化提醒

• 生產環境啟用 opcache、oci8.statement_cache_size。
• WSDL 檔案可快取於記憶體或 APCu，避免每次解析 XML。
• 資料庫連線池：考慮 PHP-FPM + OCI8 持久連線（oci_pconnect）或 DRCP（Database Resident Connection Pool）。
• 安全：HTTPS 傳輸、WS-Security 或 API Key 驗證、限制 IP 存取。