| NuSOAP 是 PHP 环境下的 WEB 服务编程工具，用于创建或调用 WEB 服务。它是一个开源软件，当前版本是 0.7.2 ，支持 SOAP1.1 、 WSDL1.1 ，可以与其他支持 SOAP1.1 和 WSDL1.1 的系统互操作。 NuSOAP 完全由PHP 语言编写，由一系列 PHP 类组成，不需要扩展库的支持，这种特性使得 NuSOAP 可以用于所有的 PHP 环境，不受服务器安全设置的影响。
1. NuSOAP 的获取和安装
NuSOAP 项目建立在 SourceForge 上，网络地址是： http://sourceforge.net/projects/nusoap/ 或 http://dietrich.ganx4.com/nusoap ，这里，可以下载到 NuSOAP 的最新的版本。
NuSOAP 的安装比较简单，把下载的 NuSOAP 的文件拷贝到服务器上，可以放在独立的目录里，也可以与程序代码放在相同的目录里，只要你的 PHP 代码能够访问到这些文件就可以了。
本文的测试环境基于 PHP4.3.2 和 NuSOAP 0.7.2 版本， NuSOAP 安装在 WEB 目录“ /nusoap ” 里，有两个子目录， lib 和 samples 。其中， lib 目录下存放 NuSOAP 的所有源代码文件， samples 目录下是NuSOAP 开发小组提供一些的例子。测试文件存放在 WEB 目录“ /nusoap ” 里。
2. NuSOAP 的使用
NuSOAP 由一 PHP 的类组成，其中最常用到的是类soap_server 和类soalclient 。 类soap_server 用于创建 WEB 服务， 类soapclient 在访问WEB 服务时会用到。
2.1 一个简单的例子： Hello World
这个例子将利用 NuSOAP 创建一个简单的 WEB 服务，并利用 NuSOAP 创建一个客户端程序，调用这个服务。这个服务唯一的功能就是向客户端返回一个字符串“ Hello World ” 。首先，创建 WEB 服务程序代码文件“ /nusoap/nusoap_server1.php ” ：
// 把 NuSOAP 的源文件包含到当前的代码文件里
<?php
require_once("lib/nusoap.php");
// 定义服务程序
function hello() {
return 'Hello World!';
}
// 初始化服务对象 , 这个对象是类 soap_server 的一个实例
$soap = new soap_server;
// 调用服务对象的 register 方法注册需要被客户端访问的程序。
// 只有注册过的程序，才能被远程客户端访问到。
$soap->register('hello');
// 最后一步，把客户端通过 post 方式提交的数据，传递给服务对象的 service 方法。
//service 方法处理输入的数据，调用相应的函数或方法，并且生成正确的反馈，传回给客户端。
$soap->service($HTTP_RAW_POST _DATA);
?>
至此， WEB 服务程序代码文件已经建好，接下来，创建一个客户端程序代码文件“ /nusoap/nusoap_client1.php ” ，调用 WEB 服务：
// 把 NuSOAP 的源文件包含到当前的代码文件里
<?php
require_once("lib/nusoap.php");
// 初始化客户端对象，这个对象是类 soapclient 的一个实例，
// 把服务程序的 URL 地址传递给soapclient 类的构造函数。
$client = new soapclient('http://127.0.0.1/nusoap/nusoap_server1.php');
// 利用客户端对象的 call 方法调用 WEB 服务的程序
$str=$client->call('hello');
// 客户端对象的 getError() 方法可以用来检查调用过程是否出现错误。
// 如果没有错误， getError() 方法返回 false ；如果有错误， getError() 方法返回错误信息。
if (!$err=$client->getError()) {
echo " 程序返回 :",htmlentities($str,ENT_QUOTES);
} else {
echo " 错误 :",htmlentities($err,ENT_QUOTES);
}
?>
至此，客户端程序也建立好了，打开浏览器，访问客户端程序，看一下结果。这个例子，浏览器会显示字符串：“ 程序返回 :Hello World! ”
2.2 传递参数和返回错误信息的方法
再通过例子说明传递参数和返回错误信息的方法。这个例子实现两个字符串的连接，参数是两个字符串，返回值是由两个参数连接而成的字符串。首先，创建服务程序代码文件“ /nusoap/nusoap_server2.php ” ，完整的代码如下：
<?php
require_once("lib/nusoap.php");
function concatenate($str1,$str2) {
if (is_string($str1) && is_string($str2))
return $str1 . $str2;
else
return new soap_fault(' 客户端 ','','concatenate 函数的参数应该是两个字符串 ');
}
$soap = new soap_server;
$soap->register('concatenate');
$soap->service($HTTP_RAW_POST _DATA);
?>
与 2.1 节 WEB 服务程序的代码比较，这里的代码结构大体是相同的。注意以下两点：
* 服务程序的定义不同，带有两个参数。 NuSOAP 注册服务程序的过程还是一样的，都是调用服务对象的 register 方法。
* 这里使用了 NuSOAP 的一个新类 soap_fault 。当传入的两个参数有一个不是字符串时，程序通过这个类把错误信息返回给客户端。这个类的构造函数有 4 个参数：
fault
code
必填参数 , 建议值为“ Client ” 或“ Server ” ，指明错误是客户端的错误还是服务端的错误。
faultactor
预留项，现在还没有使用
faultstring
错误的描述信息
faultdetail
可选项， XML 格式的数据 , 说明详细的错误信息
客户端程序代码文件“ /nusoap/nusoap_client2.php ” 的完整内容如下 :
<?php
require_once("lib/nusoap.php");
$client = new soapclient('http://127.0.0.1/nusoap/nusoap_server2.php');
$parameters=array(' 字符串 1',' 字符串 2');
$str=$client->call('concatenate',$parameters );
if (!$err=$client->getError()) {
echo " 程序返回 :",$str;
} else {
echo " 错误 :",$err;
}
?>
NuSOAP 的客户端调用带参数的 WEB 服务时，使用数组传递参数。 $parameters 是一个数组，其中依次是每个参数的值。客户端在调用远程的服务程序时， 使用带有两个参数的 call 方法，第一个参数是服务程序的名称，第二个参数是服务程序的参数数组 ，这里是 $parameters 。通过浏览器访问上面的客户端程序，浏览器上会显示字符串：“ 程序返回 : 字符串 1 字符串 2 ”
接下来，试着给 WEB 服务程序传入错误参数，修改上面的客户端程序，把生成参数数组的语句改成： $parameters=array(“ 字符串 ”,12) ，再通过浏览器访问客户端程序，浏览器上会显示字符串：“ 错误 : 客户端 : concatenate 函数的参数应该是两个字符串” 。 WEB 服务程序判断传入的参数有一个不是字符串，通过 soap_fault 给客户端返回错误信息。
2.3 调试的方法
NuSOAP 中常用的调试方法 有三种:
2.3.1 soapclient 类的 request 和 response 成员变量
最直接的调试方法就是检查访问 WEB 服务的过程中，客户端发出的 request 信息和服务端返回的 response 信息。 soapclient 类的 request 和 response 成员变量包含这些信息，在程序中显示出这两个变量的内容，可以帮助分析程序运行的情况。看下面的代码:
<?php
require_once("lib/nusoap.php");
$client = new soapclient('http://127.0.0.1/nusoap/nusoap_server2.php');
$parameters=array(' 字符串 1',' 字符串 2');
$str=$client->call('concatenate',$parameters);
if (!$err=$client->getError()) {
echo " 程序返回 :",$str;
} else {
echo " 错误 :",$err;
}
// 下面显示request 和response 变量的内容
echo '<p/>';
echo 'Request:';
echo '<pre>',htmlspecialchars($client->request ,ENT_QUOTES),'</pre>';
echo 'Response:';
echo '<pre>',htmlspecialchars($client->response ,ENT_QUOTES ),'</pre>';
?>
2.3.2 soapclient 类的 debug_str 成员变量
s o apclient 类的 debug_str 成员变量提供了更为详细的调试信息，查看这个变量的内容，可以更好地帮助程序调试。
2.3.3 WEB 服务程序提供的调试方法
WEB 服务程序代码中，在创建 soap_server 类的实例前，定义变量 $debug=1 。调试信息作为备注，放在 SOAP 消息的尾部返回客户端，客户端通过查看 WEB 服务的 response 信息来查看调试信息。
<?php
require_once("lib/nusoap.php");
function concatenate($str1,$str2) {
if (is_string($str1) && is_string($str2))
return $str1 . $str2;
else
return new soap_fault(' 客户端 ','','concatenate 函数的参数应该是两个字符串 ');
}
$debug=1; // 定义调试 客户端通过查看 WEB 服务的 response 信息来查看调试信息。
$soap = new soap_server;
$soap->register('concatenate');
$soap->service($HTTP_RAW_POST_DATA);
?>
2.4 对 WSDL 的支持
NuSOAP 内部通过类 "WSDL" 实现对 WSDL 的支持。对于 NuSOAP 的用户来说，不需要关心内部的WSDL 类是如何工作的，正确地使用 soap_server 类和 soapclient 类就可以实现对 WSDL 的支持。
2.4.1 创建支持 WSDL 的 WEB 服务
为了实现 WEB 服务程序对 WSDL 的支持，需要使用 soap_server 的 configureWSDL 方法，并且在调用 soap_server 的 register 方法注册 WEB 服务程序时，需要提供更详细的参数。看下面的代码，代码的文件名是 “/nusoap/nusoap_server3.php” 。
<?php
require_once("lib/nusoap.php");
function concatenate ($str1,$str2) {
if (is_string($str1) && is_string($str2))
return $str1 . $str2;
else
return new soap_fault(' 客户端 ','','concatenate 函数的参数应该是两个字符串 ');
}
$soap = new soap_server;
$soap->configureWSDL('concatenate '); // 初始化对 WSDL 的支持
// 注册服务
$soap->register('concatenate ',
array("str1"=>"xsd:string","str2"=>"xsd:string"), // 输入参数 的定义
array("return"=>"xsd:string") // 返回参数 的定义
);
$HTTP_RAW_POST_DATA = isset($HTTP_RAW_POST_DATA) ? $HTTP_RAW_POST_DATA : '';
$soap->service($HTTP_RAW_POST_DATA);
?>
现在打开浏览器，访问刚才建立的文件，http://127.0.0.1/nusoap/nusoap_server3.php ，结果如下：
concatenate
View the WSDL for the service. Click on an operation name to view it's details.
* concatenate
点击函数名称concatenate ，可以看到对函数的描述。点击"WSDL" ，或者访问WEB 服务文件，并在后面加上查询字符串"?wsdl"(http://127.0.0.1/nusoap/nusoap_server3.php?wsdl) ，可以得到WEB 服务的WSDL 内容。
2.4.2 通过 WSDL 调用 WEB 服务
通过 WSDL 调用 WEB 服务，与不通过 WSDL 调用 WEB 服务，程序的结构大体相同。区别在于，通过 WSDL 调用 WEB 服务， 初始化 soapclient 类时，传入两个参数到 soapclient 的构造函数， 第一个参数是 WSDL 文件的地址， 第二个参数指定是否使用 WSDL ，指定为 true 即可。 看下面的代码，代码的文件名是 “ /nusoap/nusoap_client3.php ”
<?php
require_once("lib/nusoap.php");
$client = new soapclient('http://127.0.0.1/nusoap/nusoap_server3.php?wsdl', true );
$parameters=array(' 字符串 1',' 字符串 2');// $parameters=array('key'=>'value' ,'key_2'=>' 字value_2'); $ str=$client->call('concatenate',$parameters);
if (!$err=$client->getError()) {
echo " 程序返回 :",$str;
} else {
echo " 错误 :",$err;
}
?>
2.4.3 代理的使用 NuSOAP 提供代理的方法调用远程 WEB 服务。这种方法， 在客户端程序里面创建一个远程服务的代理对象，通过代理直接调用远程的 WEB 服务，而不需要通过 soalclient 类的 call 方法。 看下面的代码。
<?php
require_once("lib/nusoap.php");
$client = new soapclient('http://127.0.0.1/nusoap/nusoap_server3.php?wsdl', true );
$proxy=$client -> getProxy(); // 创建代理对象 (soap_proxy 类 )
$str=$proxy->concatenate(" 参数 1"," 参数 2"); // 直接调用 WEB 服务
if (!$err= $proxy->getError() ) {
echo " 程序返回 :",$str;
} else {
echo " 错误 :",$err;
}
?> 乱码问题 许多使用NuSoap 调用.NET WebService或J2EE WebService的朋友可能都遇到过中文乱码问题，下面介绍这一问题的出现的原因和相应的解决方法。
NuSoap调用WebService出现乱码的原因：
通常我们进行WebService开发时都是用的UTF-8编码，这时我们需要设置：
view plaincopy to clipboardprint?
$client->soap_defencoding = 'utf-8';
$client->soap_defencoding = 'utf-8'; 同时，需要让xml以同样的编码方式传递：
view plaincopy to clipboardprint?
$client->xml_encoding = 'utf-8';
$client->xml_encoding = 'utf-8';
至此应该是一切正常了才对，但是我们在输出结果的时候，却发现返回的是乱码。
NuSoap调用WebService出现乱码的解决方法：
实际上，开启了调试功能的朋友，相信会发现$client->response返回的是正确的结果，为什么$result = $client->call($action, array('parameters' => $param)); 却是乱码呢？
研究过NuSoap代码后我们会发现，当xml_encoding设置为UTF-8时，NuSoap会检测decode_utf8的设置，如果为true，会执行 PHP 里面的utf8_decode函数，而NuSoap默认为true， 因此，我们需要设置：
view plaincopy to clipboardprint?
$client->soap_defencoding = 'utf-8';
$client->decode_utf8 = false;
$client->xml_encoding = 'utf-8'; |
