NuSOAP 實戰：快速構建 PHP SOAP Web Service 服務端與客戶端

為什麼選 NuSOAP？

NuSOAP 是純 PHP 實現的 SOAP 庫，無需安裝 C 擴展，部署簡單，適合快速構建兼容 SOAP 1.1、WSDL 1.1 的 Web Service。雖已停止維護，但在存量項目中仍廣泛使用。

項目結構

soap/
├── soapfunc.php    # 業務邏輯函數
├── soapserver.php  # SOAP 服務端
└── soapclient.php  # SOAP 客戶端

1. 業務邏輯層 soapfunc.php

<?php
// 字符串反轉
function reverse(string $str): string|soap_fault {
    if (strlen($str) < 1) {
        return new soap_fault('Client', '', 'Invalid string');
    }
    return strrev($str); // 內置函數更高效
}

// 兩數求和
function add2numbers(int|float $num1, int|float $num2): int|float|soap_fault {
    if (!is_numeric($num1)) {
        return new soap_fault('Client', '', 'First number is invalid');
    }
    if (!is_numeric($num2)) {
        return new soap_fault('Client', '', 'Second number is invalid');
    }
    return $num1 + $num2;
}
?>

注意： 返回 soap_fault 對象即拋出 SOAP Fault，客戶端可捕獲。

2. 服務端 soapserver.php

<?php
require_once 'nusoap.php';
include 'soapfunc.php';

$server = new soap_server();
// 註冊方法：名稱、參數、返回類型、命名空間（可選）
$server->register('reverse',
    ['str' => 'xsd:string'],      // 輸入參數
    ['return' => 'xsd:string'],   // 輸出參數
    'urn:soapfunc'                // namespace
);
$server->register('add2numbers',
    ['num1' => 'xsd:float', 'num2' => 'xsd:float'],
    ['return' => 'xsd:float'],
    'urn:soapfunc'
);

// 處理請求
$HTTP_RAW_POST_DATA = $HTTP_RAW_POST_DATA ?? file_get_contents('php://input');
$server->service($HTTP_RAW_POST_DATA);
?>

3. 客戶端 soapclient.php

<?php
require_once 'nusoap.php';

$client = new soapclient('https://localhost/soap/soapserver.php');

// 錯誤檢查
if ($err = $client->getError()) {
    die("Client init error: $err");
}

// 調用 reverse
$str = 'Hello NuSOAP';
$result = $client->call('reverse', ['str' => $str]);
if ($client->fault) {
    die("SOAP Fault: " . print_r($result, true));
}
if ($err = $client->getError()) {
    die("Call error: $err");
}
echo "Reverse of '$str': $result\n";

// 調用 add2numbers
$result = $client->call('add2numbers', ['num1' => 5, 'num2' => 14]);
// ... 同樣錯誤檢查 ...
echo "5 + 14 = $result\n";
?>

調試利器

NuSOAP 內置調試屬性，開發期必開：

<?php
// 客戶端調試
echo '
Request
' . htmlspecialchars($client->request) . '
';
echo '
Response
' . htmlspecialchars($client->response) . '
';
echo '
Debug
' . htmlspecialchars($client->debug_str) . '
';

// 服務端調試：實例化前啟用
$debug = 1;
$server = new soap_server;
// ... 註冊方法 ...
// 響應末尾會自動附帶 XML 格式調試信息
?>

WSDL 自動生成

NuSOAP 支持自動生成 WSDL，客戶端可直接使用 WSDL URL：

<?php
// 服務端啟用 WSDL
$server->configureWSDL('MyService', 'urn:soapfunc');
$server->wsdl->schemaTargetNamespace = 'urn:soapfunc';
// 訪問 https://host/soapserver.php?wsdl 即可獲取 WSDL

// 客戶端使用 WSDL
$client = new soapclient('https://host/soapserver.php?wsdl', true); // 第 2 參 true 表示 WSDL 模式
?>

常見坑與避雷指南

• 編碼問題：NuSOAP 默認 ISO-8859-1，中文項目請統一設置 UTF-8：$server->soap_defencoding = 'UTF-8';。
• 大小寫敏感：方法名區分大小寫，註冊與調用必須一致。
• 複雜類型：傳遞陣列/對象需用 wsdl->addComplexType() 定義，或改用 PHP 原生 SoapClient（PHP 5+ 內置）。
• 性能：純 PHP 解析 XML，高併發下建議遷移至原生 ext-soap 或 gRPC/REST。

總結

NuSOAP 以「零擴展依賴、代碼簡潔」著稱，適合中小型 SOAP 集成。新項目優先考慮 REST/JSON 或 gRPC，若必須用 SOAP，PHP 內置 SoapClient/SoapServer 性能更好、標準支持更完善。