這個(gè)文檔描述了如何取得和安裝 NuSOAP，然后提供一些實(shí)例來說明 NuSOAP 的功能，這并不是一個(gè)全面的 NuSOAP 的介紹，但是希望能夠然一些 php 開發(fā)者可以有一個(gè)很好的入門。

NuSOAP 是一組 PHP 類，它讓開發(fā)者可以創(chuàng)建和使用 SOAP web services。它不需要安裝任何的 PHP 擴(kuò)展。它是在2004年12月3日被開發(fā)，當(dāng)前的版本是 NuSOAP(0.6.7) 。支持 SOAP 1.1 規(guī)范，它能夠生產(chǎn) WSDL 1.1 ，當(dāng)然也可以使用它，同時(shí)也支持 rpc/encoded and document/literal service。但是，必須注意 NuSOAP 沒有像 .NET 和 Apache Axis 那樣提供完全的實(shí)現(xiàn)。

Hello, World
我會以 "Hello, World" 為實(shí)例做開始，編寫基本的 NuSOAP 客戶端和服務(wù)器端的代碼。

我們先從服務(wù)器端開始，應(yīng)為沒有服務(wù)器端，有客戶端也是沒有意義的。我們將編寫一個(gè)帶有單個(gè)參數(shù)并返回一個(gè)字符串，名叫 Hello 的 SOAP 方法，希望代碼中的注釋能夠提供有效的說明。

<?php
// Pull in the NuSOAP code
require_once('nusoap.php');
// Create the server instance
$server = new soap_server;
// Register the method to expose
$server->register('hello');
// Define the method as a PHP function
function hello($name) {
    return 'Hello, ' . $name;
}
// Use the request to (try to) invoke the service
$HTTP_RAW_POST_DATA = isset($HTTP_RAW_POST_DATA) ? $HTTP_RAW_POST_DATA : '';
$server->service($HTTP_RAW_POST_DATA);
?>

以下是客戶端的代碼，有一些重要的事情需要注意：首先，當(dāng)創(chuàng)建實(shí)例 soapclient 時(shí)，需要指定一個(gè) service 的 URL 為參數(shù)，在這個(gè)實(shí)例中，helloworld.php 從 http://localhost/phphack 訪問的。當(dāng)然，你要使用的 services 放在不同的 URL；第二，當(dāng)調(diào)用service 時(shí)，第一個(gè)參數(shù)是 service 的名字，必須要匹配有效的方法名（有的服務(wù)器是大小寫敏感的）。在這個(gè)實(shí)例，他必須匹配在 helloworld.php 中已經(jīng)注冊了的方法。最后，第二個(gè)參數(shù)是一個(gè)數(shù)組，它將是傳遞給 SOAP service 方法作為參數(shù)。既然 helloworld.php 中的方法 hello 只有一個(gè)參數(shù)，那么數(shù)組就只有一個(gè)元素。

<?php
// Pull in the NuSOAP code
require_once('nusoap.php');
// Create the client instance
$client = new soapclient('http://localhost/phphack/helloworld.php');
// Call the SOAP method
$result = $client->call('hello', array('name' => 'Scott'));
// Display the result
PRint_r($result);
?>

Debugging
編程時(shí)，當(dāng)有問題出現(xiàn)的時(shí)候你都需要調(diào)試。NuSOAP 提供了一組工具來幫助你做這個(gè)工作。NuSOAP 調(diào)試的時(shí)候需要查看的信息是發(fā)送的請求信息和返回的相應(yīng)信息。NuSOAP 的客戶端類允許你通過它的兩個(gè)成員來查看這些信息。例如，這里是顯示請求和響應(yīng)的 helloworldclient.php 的修改版。在下一部分我會回顧顯示在客戶端代碼的請求和響應(yīng)信息。

<?php
// Pull in the NuSOAP code
require_once('nusoap.php');
// Create the client instance
$client = new soapclient('http://localhost/phphack/helloworld.php');
// Call the SOAP method
$result = $client->call('hello', array('name' => 'Scott'));
// Display the result
print_r($result);
// Display the request and response
echo '<h2>Request</h2>';
echo '<pre>' . htmlspecialchars($client->request, ENT_QUOTES) . '</pre>';
echo '<h2>Response</h2>';
echo '<pre>' . htmlspecialchars($client->response, ENT_QUOTES) . '</pre>';
?>

NuSOAP 也提供了一個(gè)方法使用它的類就可以通過日志來查看調(diào)試信息。加入以下的代碼將會顯示冗長的調(diào)試信息。不幸的是輸出的說明必須留給讀者。

// Display the debug messages
echo '<h2>Debug</h2>';
echo '<pre>' . htmlspecialchars($client->debug_str, ENT_QUOTES) . '</pre>';

服務(wù)器端能夠提供相似的調(diào)試信息，有趣的是，這些調(diào)試信息是在SOAP 的相應(yīng)的末尾以 xml 格式顯示，因此它可以在客戶端中查看到。服務(wù)器端的調(diào)試看起來像這樣：

<?php
// Pull in the NuSOAP code
require_once('nusoap.php');
// Enable debugging *before* creating server instance
$debug = 1;
// Create the server instance
$server = new soap_server;
// Register the method to expose
$server->register('hello');
// Define the method as a PHP function
function hello($name) {
    return 'Hello, ' . $name;
}
// Use the request to (try to) invoke the service
$HTTP_RAW_POST_DATA = isset($HTTP_RAW_POST_DATA) ? $HTTP_RAW_POST_DATA : '';
$server->service($HTTP_RAW_POST_DATA);
?>

調(diào)試的第三個(gè)方法不算是真正的調(diào)試，它是很好的編程實(shí)踐。上面的實(shí)例在調(diào)用 SOAP 的時(shí)候沒有做錯(cuò)誤的檢查，更健壯的客戶端會像這樣：

<?php
// Pull in the NuSOAP code
require_once('nusoap.php');
// Create the client instance
$client = new soapclient('http://localhost/phphack/helloworld.php');
// Check for an error
$err = $client->getError();
if ($err) {
    // Display the error
    echo '<p><b>Constructor error: ' . $err . '</b></p>';
    // At this point, you know the call that follows will fail
}
// Call the SOAP method
$result = $client->call('hello', array('name' => 'Scott'));
// Check for a fault
if ($client->fault) {
    echo '<p><b>Fault: ';
    print_r($result);
    echo '</b></p>';
} else {
    // Check for errors
    $err = $client->getError();
    if ($err) {
        // Display the error
        echo '<p><b>Error: ' . $err . '</b></p>';
    } else {
        // Display the result
        print_r($result);
    }
}
?>

為了測試代碼，需要引起錯(cuò)誤發(fā)生，例如，改變調(diào)用的方法名稱 hello 為 goodbye。

Request and Response
我在上面的例子中已經(jīng)展示了顯示 SOAP 的請求和響應(yīng)信息是如此的容易，在這里 hello2client.php 的請求信息：

POST /phphack/helloworld2.php HTTP/1.0
Host: localhost
User-Agent: NuSOAP/0.6.8 (1.81)
Content-Type: text/xml; charset=ISO-8859-1
SOAPAction: ""
Content-Length: 538

<?xml version="1.0" encoding="ISO-8859-1"?>
<SOAP-ENV:Envelope
  SOAP-ENV:encodingStyle="  xmlns:SOAP-ENV="  xmlns:xsd="  xmlns:xsi="  xmlns:SOAP-ENC="  xmlns:si="<SOAP-ENV:Body>
  <ns1:hello xmlns:ns1="   <name xsi:type="xsd:string">Scott</name>
  </ns1:hello>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
在 HTTP headers 里，你會看到 SOAPAction 是一個(gè)空的字符串，這是它的默認(rèn)值。你的 service 方法可以設(shè)置 SOAPAction 的值，你的客戶端代碼可以指定 SOAPAction 作為參數(shù)來調(diào)用方法。

在 XML payload，你可以看到 NuSOAP 使用和Latin-1一樣著名的 ISO-8859-1 做為編碼，為了指定不同的編碼，你可以在客戶端 soapclient 的實(shí)例設(shè)置 soap_defencoding 屬性。使用指定的編碼來編碼參數(shù)的數(shù)據(jù)當(dāng)然就是程序員的責(zé)任。幸運(yùn)地，在 SOAP 里PHP提供了很多函數(shù)來編碼和解碼最通用的編碼數(shù)據(jù)，如 UTF-8。

另一件事情要注意的是，元素指定要調(diào)用的方法，名稱為 hello 的元素被放在 http://tempuri.org的域名下，指定真實(shí)的域名是最佳的實(shí)踐，對于很多 services 也是很有必要的。這里展示了一個(gè)未來的文檔：

SOAP 服務(wù)的響應(yīng)像以下：

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.0
Date: Wed, 03 Nov 2004 21:32:34 GMT
X-Powered-By: asp.net
X-Powered-By: PHP/4.3.4
Server: NuSOAP Server v0.6.8
X-SOAP-Server: NuSOAP/0.6.8 (1.81)
Content-Type: text/xml; charset=ISO-8859-1
Content-Length: 556

<?xml version="1.0" encoding="ISO-8859-1"?>
<SOAP-ENV:Envelope
  SOAP-ENV:encodingStyle="  xmlns:SOAP-ENV="  xmlns:xsd="  xmlns:xsi="  xmlns:SOAP-ENC="  xmlns:si="<SOAP-ENV:Body>
  <ns1:helloResponse xmlns:ns1="   <return xsi:type="xsd:string">Hello, Scott</return>
  </helloResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>