PHP 使用Nusoap类构建WebService(1)
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/ ,这里,可以下载到 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 给客户端返回错误信息。