萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 建立與呼叫 WebService (SOAP) 完整實作:WSDL 生成、伺服端與客戶端代碼

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'];
    }
}

步驟二:自動生成 WSDL (使用 SoapDiscovery)

下載 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 供客戶端使用。

步驟三:建立 SOAP 伺服端

<?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";
}

進階主題

1. 複雜型別定義(WSDL 中的 types 區段)

SoapDiscovery 會自動從 PHPDoc @param/@return 推斷型別。複雜型別建議手寫 WSDL 或使用 Zend\Soap\AutoDiscover(Zend Framework 組件)。

2. SOAP Header 驗證

// 伺服端:驗證 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);

3. 錯誤處理與例外轉換

// 伺服端:將 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)
}

4. 效能優化

  • 生產環境啟用 WSDL 快取:ini_set('soap.wsdl_cache_enabled', 1); ini_set('soap.wsdl_cache_ttl', 86400);
  • 使用 SoapClient::__doRequest() 覆寫實作 HTTP/2、連線池、非同步
  • 大量資料傳輸考慮 MTOM (Message Transmission Optimization Mechanism)

REST vs SOAP 選型建議

現代新專案首選 REST/GraphQL;既有 SOAP 系統維護、銀行/電信/政府介接、需強型別合約場景繼續使用 SOAP。

copyright © 萬盛學電腦網 all rights reserved
維度REST/JSONSOAP/XML
契約定義OpenAPI/Swagger (可選)WSDL (強制、強型別)
跨語言極佳極佳 (企業級工具鏈成熟)
複雜交易需自行實作WS-AtomicTransaction 標準
安全性OAuth2/JWTWS-Security (XML 加密簽章)
頻寬/效能輕量、快速冗長、解析較慢
瀏覽器直接呼叫fetch() 原生支援需 JS 庫 (如 soap.js)