WebService (SOAP) 雖然不如 REST API 普及,但在企業級系統整合、跨語言介接(Java/.NET/PHP)、強型別合約優先開發中仍佔重要地位。本文完整示範 PHP 使用 SOAP 擴展建立服務端、自動生成 WSDL、客戶端呼叫的全流程。
[Client] --HTTP POST (SOAP XML)--> [Server (PHP SoapServer)]
^ |
| WSDL (契約定義) |
+----------- SoapDiscovery -----------+
<?php
// Service.php
class Service {
/**
* 問候方法
* @param string $name
* @return string
*/
public function Hello(string $name): string {
return "Hello, {$name}!";
}
/**
* 加法運算
* @param int $a
* @param int $b
* @return int
*/
public function Add(int $a, int $b): int {
return $a + $b;
}
/**
* 取得使用者資料(示範複雜型別回傳)
* @param int $id
* @return array
*/
public function GetUser(int $id): array {
// 模擬資料庫查詢
$users = [
1 => ['id'=>1, 'name'=>'Alice', 'email'=>'alice@example.com', 'roles'=>['admin']],
2 => ['id'=>2, 'name'=>'Bob', 'email'=>'bob@example.com', 'roles'=>['user']],
];
return $users[$id] ?? ['error'=>'User not found'];
}
}
下載 SoapDiscovery.class.php(單檔案類別)
<?php
// create_wsdl.php
require_once 'Service.php';
require_once 'SoapDiscovery.class.php';
$wsdl = new SoapDiscovery('Service', 'MySoapService'); // 類別名、服務名
$wsdl->getWSDL(); // 直接輸出 WSDL XML 至瀏覽器
// 或存檔:file_put_contents('Service.wsdl', $wsdl->getWSDL(true));
瀏覽 create_wsdl.php 即可看到生成的 WSDL XML,另存為 Service.wsdl 供客戶端使用。
<?php
// server.php
require_once 'Service.php';
$server = new SoapServer('Service.wsdl', [
'soap_version' => SOAP_1_2, // 或 SOAP_1_1
'encoding' => 'UTF-8',
'actor' => 'https://example.com/soap',
'cache_wsdl' => WSDL_CACHE_NONE, // 開發階段關閉快取
]);
$server->setClass('Service'); // 註冊類別所有 public 方法
// 或註冊單一方法:$server->addFunction('Hello');
$server->handle(); // 處理請求
<?php
// client.php
ini_set('soap.wsdl_cache_enabled', 0); // 開發關閉 WSDL 快取
ini_set('soap.wsdl_cache_ttl', 0);
try {
$client = new SoapClient('https://localhost/soap/Service.wsdl', [
'trace' => 1, // 除錯用:可取得最後請求/回應 XML
'exceptions' => true, // 拋出 SoapFault 例外
'connection_timeout' => 10,
'cache_wsdl' => WSDL_CACHE_NONE,
]);
// 呼叫方式一:直接當方法呼叫
echo $client->Hello('World') . "\n"; // Hello, World!
// 呼叫方式二:__soapCall(動態方法名)
echo $client->__soapCall('Add', [10, 20]) . "\n"; // 30
// 複雜型別回傳
$user = $client->GetUser(1);
print_r($user);
/* 輸出:
stdClass Object
(
[id] => 1
[name] => Alice
[email] => alice@example.com
[roles] => Array ( [0] => admin )
)
*/
// 除錯:查看原始 XML
// echo "REQUEST:\n" . $client->__getLastRequest() . "\n";
// echo "RESPONSE:\n" . $client->__getLastResponse() . "\n";
} catch (SoapFault $e) {
echo "SOAP Fault: {$e->faultcode} - {$e->faultstring}\n";
if (isset($client)) {
echo "Last Request:\n" . $client->__getLastRequest() . "\n";
}
} catch (Exception $e) {
echo "Error: {$e->getMessage()}\n";
}
SoapDiscovery 會自動從 PHPDoc @param/@return 推斷型別。複雜型別建議手寫 WSDL 或使用 Zend\Soap\AutoDiscover(Zend Framework 組件)。
// 伺服端:驗證 Token
$server->setObject(new class {
public function Hello($name) {
$headers = $this->__getHeaders(); // 需在 SoapServer 子類別中實作
// 驗證 $headers['Auth']->token
}
});
// 客戶端:發送 Header
$header = new SoapHeader('https://example.com/soap', 'Auth', ['token' => 'secret123']);
$client->__setSoapHeaders($header);
// 伺服端:將 Exception 轉為 SoapFault
try {
// 業務邏輯
} catch (Exception $e) {
throw new SoapFault('Server', $e->getMessage());
}
// 客戶端:捕獲 SoapFault
try {
$client->SomeMethod();
} catch (SoapFault $e) {
// $e->faultcode: 'Client'|'Server'|'VersionMismatch'|'MustUnderstand'
// $e->faultstring: 錯誤訊息
// $e->detail: 詳細資訊 (stdClass)
}
ini_set('soap.wsdl_cache_enabled', 1); ini_set('soap.wsdl_cache_ttl', 86400);SoapClient::__doRequest() 覆寫實作 HTTP/2、連線池、非同步| 維度 | REST/JSON | SOAP/XML |
|---|---|---|
| 契約定義 | OpenAPI/Swagger (可選) | WSDL (強制、強型別) |
| 跨語言 | 極佳 | 極佳 (企業級工具鏈成熟) |
| 複雜交易 | 需自行實作 | WS-AtomicTransaction 標準 |
| 安全性 | OAuth2/JWT | WS-Security (XML 加密簽章) |
| 頻寬/效能 | 輕量、快速 | 冗長、解析較慢 |
| 瀏覽器直接呼叫 | fetch() 原生支援 | 需 JS 庫 (如 soap.js) |