PHP5: passing and returning objects as a parameter in a SOAP call (Part II)

Translation of the original in Catalan. Read it in: CatalàCastellano

Part 3 of 3SOAP web services with PHP5
  1. PHP5 - Generating WSDL with Zend Studio 5.1
  2. PHP5: passing objects as a parameter in a SOAP call
  3. PHP5: passing and returning objects as a parameter in a SOAP call (Part II)

In March I wrote an article with almost the same title as this one, in that article I explained how PHP5 managed to receive and return complex types (e.g. objects) as parameters of SOAP calls. Well, I had found something that bothered me a bit and that is that when I sent an object from the client to the server or the other way round it lost its type. Well, this afternoon I've discovered how to do that without losing the type. You know how it is when I get something into my head...

The matter isn't simple and ZendStudio's WSDL generator is a bit fussy doing these things, so everything has to be done very nicely for the WSDL generator to understand it. In fact, the trick lies in defining the complex type inside the WSDL file, that's why the generator needs us to give it all the information the way it wants, otherwise it isn't able to generate the file properly.

In the example I give you below I've created the persona class with three attributes, two public and one private. The private one, contrary to what I said in the previous article, doesn't lose its value. So, in principle we have the object 100% replicated with the method I'll explain now.

The persona class:

<?php
/**
 * classe persona
 *
 */
class persona {
	/**
	 * propietat nom
	 *
	 * @var string $nom
	 * @var string $cognom
	 * @var string $dni
	 */
	public $nom;
	private $cognom;
	public $dni;
	/**
	 * setter function
	 *
	 * @param string $nom
	 */
	function set($nom) {
		$this-?>nom=$nom;
	}
	/**
	 * setter cognom
	 *
	 *  @param string $cognom
	 */
	function setCognom($cognom)
	{
		$this-?>cognom=$cognom;
	}
	/**
	 * getter function
	 *
	 * @return string valor a tornar
	 */
	function get()
	{
		return $this-?>nom;
	}
	/**
	 * getter cognom
	 *
	 * @return string valor a tornar
	 */
	function getCognom()
	{
		return $this-?>cognom;
	}
}
?>

Notice that we comment the code following the phpDoc syntax, that's done because it's from these comments that the WSDL generator will extract the types of the variables so as to export them without losing information. The dni property has neither getter nor setter because we'll access it directly. Otherwise it's a completely normal and simple class.

The server is quite simple:

<?php
require_once("persona.class.php");
/**
 * servidor soap
 *
 */
class soapservice {
	/**
	 * funcio soap publicada
	 *
	 * @param persona $per
	 * @return persona
	 */
	function peticion($per) {
		$per->dni="38147000x";
		return $per;
  }
}
	$server = new SoapServer("server.wsdl",array("classmap"=>array("persona"=>"persona")));
$server->setClass("soapservice");
$server->handle();
?>

To note that the soapservice class receives an object of type persona, adds a value to the dni property and returns the same object. Here too we have to document the code following the phpDoc syntax, so that the WSDL model explicitly tells us the type of the objects that the peticion method receives and returns.

As for the creation of the server object of type SoapServer, notice that with the classmap option we map the object of type persona passed as a parameter to the local class also called persona. Thanks to that mapping, when we receive the per object in the soapservice, it's already of type persona.

Now it's time to look at the client code, this code also has a mapping just like the SOAP server's, but in this case it serves to capture the server's output and, since the object returned at the output is also of type persona, the classmap is the same as the server's.

<?php
require_once("persona.class.php");
// creem objecte tipus persona
$myPersona=new persona;
$myPersona->set("el_nom");
$myPersona->setCognom("el_cognom");
	$client = new SoapClient("server.wsdl",array("classmap"=>array("persona"=>"persona")));
	$localPersona=$client->peticion($myPersona);
	var_dump($client->__getFunctions());
print_r($localPersona);
echo $localPersona->getCognom();
?>

One of the interesting things we do is ask which functions are being published on the SOAP server. That information is described in the WSDL and the __getFunctions() function formats it for humans. So we can see that the peticion function is available, which takes an object of type persona as a parameter and returns another object of that type.

array(1) {
  [0]=>
  string(30) "persona peticion(persona $per)"
}

Then we show (print_r) the localPersona object that the call to the peticion method has returned to us (localPersona=localPersona=client->peticion($myPersona);):

persona Object
(
    [nom] => el_nom
)

Finally we do a proof of concept and get the value of the nom property through the getter, that is, echo $localPersona->getCognom();:

el_nom 

As you can see it's been well demonstrated that it's relatively simple to send and receive complex types through SOAP services. The whole trick is in the WSDL file, below I paste the one Zend Studio has generated for me to do these tests, notice how at the very beginning the first thing it does is declare the complex data type that has to be passed over, in our case the persona class.

<?xml version='1.0' encoding='UTF-8'?>
	<!-- WSDL file generated by Zend Studio. -->
	<definitions name="server" targetNamespace="urn:server" xmlns:typens="urn:server" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:typens0="http://oriol.joor.net/fotoprix/web/cu.php/soap/server">
	<types>
		<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:server">
			<xsd:complexType name="persona">
				<xsd:all>
					<xsd:element name="nom" type="xsd:string"/>
					<xsd:element name="cognom" type="xsd:string"/>
					<xsd:element name="dni" type="xsd:string"/>
				</xsd:all>
			</xsd:complexType>
		</xsd:schema>
	</types>
	<message name="peticion">
		<part name="per" type="typens:persona"/>
	</message>
	<message name="peticionResponse">
		<part name="peticionReturn" type="typens:persona"/>
	</message>
	<portType name="soapservicePortType">
		<documentation>
			servidor soap
		</documentation>
		<operation name="peticion">
			<documentation>
				provem de descriure
			</documentation>
			<input message="typens:peticion"/>
			<output message="typens:peticionResponse"/>
		</operation>
	</portType>
	<binding name="soapserviceBinding" type="typens:soapservicePortType">
		<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
		<operation name="peticion">
			<soap:operation soapAction="urn:soapserviceAction"/>
			<input>
				<soap:body namespace="urn:server" use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
			</input>
			<output>
				<soap:body namespace="urn:server" use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
			</output>
		</operation>
	</binding>
	<service name="serverService">
		<port name="soapservicePort" binding="typens:soapserviceBinding">
			<soap:address location="http://oriol.joor.net/soap/server.php"/>
		</port>
	</service>
</definitions>