企業級系統整合常需 PHP 呼叫 .NET Framework 建立的 ASMX WebService(基於 SOAP 1.1/1.2 協議)。PHP 5 內建 SoapClient 提供原生支援,但實際整合常遇 WSDL 解析、型別對應、編碼、認證等問題。本文以實戰案例詳細說明完整整合流程。
// Localization.asmx.cs
using System.Web.Services;
[WebService(Namespace = "https://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
public class Localization : WebService
{
[WebMethod]
public string GetLocalizationResource(string culture = "zh-TW")
{
// 實際專案會從資源檔/資料庫讀取
var resources = new Dictionary
{
["Welcome"] = "歡迎使用系統",
["Login"] = "登入",
["Logout"] = "登出",
["Save"] = "儲存",
};
return Newtonsoft.Json.JsonConvert.SerializeObject(resources,
new Newtonsoft.Json.JsonSerializerSettings {
EnsureAscii = false
});
}
}
<?php
// 關鍵:啟用 WSDL 快取提升效能
ini_set('soap.wsdl_cache_enabled', 1);
ini_set('soap.wsdl_cache_ttl', 3600); // 1 小時
try {
$wsdlUrl = 'https://localhost/webservice1/Localization.asmx?wsdl';
// 建立客戶端(生產環境建議關閉 WSDL 快取或設定較短 TTL)
$client = new SoapClient($wsdlUrl, [
'trace' => 1, // 除錯用:啟用請求/回應追蹤
'exceptions' => true, // 拋出 SoapFault 異常
'cache_wsdl' => WSDL_CACHE_MEMORY,
'features' => SOAP_SINGLE_ELEMENT_ARRAYS, // 避免單元素陣列變物件
'encoding' => 'UTF-8', // 強制 UTF-8
]);
// 呼叫 WebMethod
$result = $client->GetLocalizationResource(['culture' => 'zh-TW']);
// .NET 回傳結構:$result->GetLocalizationResourceResult
$jsonString = $result->GetLocalizationResourceResult;
$resources = json_decode($jsonString, true);
var_dump($resources);
} catch (SoapFault $fault) {
// 詳細錯誤資訊
error_log("SOAP Fault: {$fault->faultcode} - {$fault->faultstring}");
if (isset($client)) {
error_log("Last Request:\n" . $client->__getLastRequest());
error_log("Last Response:\n" . $client->__getLastResponse());
}
// 回退機制或拋出業務異常
}
?>
<?php
// .NET 端定義複雜型別
// public class UserProfile { public int Id; public string Name; public string[] Roles; }
// PHP 端對應:使用 stdClass 或關聯陣列
$params = [
'userId' => 123,
'profile' => [
'Id' => 123,
'Name' => '張三',
'Roles' => ['Admin', 'Editor'] // 陣列自動序列化為 ArrayOfString
]
];
$result = $client->UpdateUserProfile($params);
// .NET 端接收:public void UpdateUserProfile(int userId, UserProfile profile)
?>
| 問題 | 原因 | 解決方案 |
|---|---|---|
| WSDL 無法載入 / 連線逾時 | 防火牆、網路不通、HTTPS 憑證驗證失敗 | 1. 測試 curl $wsdlUrl 連通性2. HTTPS 設定 'stream_context' => stream_context_create(['ssl' => ['verify_peer' => false, 'verify_peer_name' => false]]) |
| ClassMap 對應失敗 | .NET 型別名稱含命名空間 | 使用 'classmap' => ['{namespace}TypeName' => 'PHPClassName'] |
| 日期時間型別錯誤 | .NET DateTime ↔ PHP DateTime 格式不符 | 傳遞 ISO 8601 字串:date('c') 或 DateTime::createFromFormat() 解析回傳值 |
| 長整數截斷 (int64) | PHP 32 位元系統整數上限 | PHP 5.6+ 使用 gmp 或字串傳遞;.NET 端改用 long 對應 string |
| 編碼亂碼 | 雙端編碼不一致 | 雙端強制 UTF-8,PHP 設定 'encoding' => 'UTF-8' |
| SOAP Header 認證失敗 | .NET 端要求 SOAP Header 驗證 | 使用 SoapHeader 注入認證 Token |
<?php
$authHeader = new SoapHeader(
'https://tempuri.org/', // 命名空間需與 .NET 端一致
'AuthToken', // Header 元素名
['Username' => 'api_user', 'Password' => 'secret123'], // 複雜型別
false // mustUnderstand
);
$client->__setSoapHeaders([$authHeader]);
$result = $client->GetProtectedData();
?>
ini_set('soap.wsdl_cache_enabled', 1); ini_set('soap.wsdl_cache_ttl', 86400); 避免每次請求下載 WSDLSoapClient 實例(注意執行緒安全)<?php
// 開啟追蹤後,可輸出原始 XML 請求/回應
$client = new SoapClient($wsdl, ['trace' => 1, 'exceptions' => 0]);
$result = $client->SomeMethod($params);
echo "<h3>Request</h3><pre>". htmlspecialchars($client->__getLastRequest()) ."</pre>";
echo "<h3>Response</h3><pre>". htmlspecialchars($client->__getLastResponse()) ."</pre>";
echo "<h3>Request Headers</h3><pre>". htmlspecialchars($client->__getLastRequestHeaders()) ."</pre>";
echo "<h3>Response Headers</h3><pre>". htmlspecialchars($client->__getLastResponseHeaders()) ."</pre>";
?>
PHP 呼叫 .NET ASMX WebService 核心在於:正確配置 SoapClient 參數、處理型別對應、解決編碼與認證問題。本文提供從基礎呼叫到進階除錯的完整指南。雖然 SOAP/ASMX 屬傳統技術,但在存量系統整合中仍不可避免,掌握這些技巧能大幅降低整合風險。