Uncategorized

Beginners guide to consuming a web service using PHP SoapClient

In this example we’ll call a free public weather web service and get the current weather in Lagos, Nigeria.
 
The WSDL is for the web service is
 

The Web Services Description Language is an XML-based interface description language that is used for describing the functionality offered by a web service. A WSDL description of a web service (also referred to as a WSDL file) provides a machine-readable description of how the service can be called, what parameters it expects, and what data structures it returns. It thus serves a purpose that corresponds roughly to that of a method signature in a programming language. (Wikipedia)

Fortunately we don’t need to read the raw WSDL to get cracking. 
 
The code below demonstrates how to call this web service to get the weather in Lagos, Nigeria. 
$client = new SoapClient($url);
$fcs = $client->__getFunctions();
debug($fcs);
$res = $client->GetWeather(array(‘CityName’ => ‘Lagos’, ‘CountryName’ => ‘Nigeria’));
 
So let me explain a bit. 
 
First thing we need to do is create a new SoapClient http://www.php.net/manual/en/soapclient.soapclient.php
$client = new SoapClient($url);
 
The next step is not required but I do this to get a simple definition of the functions available in the web service.
$fcs = $client->__getFunctions();
debug($fcs); // This is a cakephp function. You can use var_dump instead or any other function you like.
 
I do this so it provides me the all functions available in the web service in a pattern I can understand. Below is what is returned.
array(
	(int) 0 => 'GetWeatherResponse GetWeather(GetWeather $parameters)',
	(int) 1 => 'GetCitiesByCountryResponse GetCitiesByCountry(GetCitiesByCountry $parameters)',
	(int) 2 => 'GetWeatherResponse GetWeather(GetWeather $parameters)',
	(int) 3 => 'GetCitiesByCountryResponse GetCitiesByCountry(GetCitiesByCountry $parameters)'
)
From here we see that the web service has 4 functions we can call. It also tells us the request parameter data types we need to send and also the data type of the response we’ll get.
 
So lets look at the first function 
GetWeatherResponse GetWeather(GetWeather $parameters)

The function name is GetWeather, the parameter is of type GetWeather and the response is of type GetWeatherResponse

 
We can call this function thus: 
 
$response = $client->GetWeather($parameters);
 
First we need pass the appropriate parameters. Fortunately the web service also provides us the definition of each data type. To get this we need to look into the WSDL file. 
 
<script id=”tinyhippos-injected”/>
<wsdl:types>
<s:schema elementFormDefault=”qualified” targetNamespace=”http://www.webserviceX.NET“>
<s:element name=”GetWeather”>
<s:complexType>
<s:sequence>
<s:element minOccurs=”0″ maxOccurs=”1″ name=”CityName” type=”s:string“/>
<s:element minOccurs=”0″ maxOccurs=”1″ name=”CountryName” type=”s:string“/>
</s:sequence>
</s:complexType>
</s:element>
<s:element name=”GetWeatherResponse”>
<s:complexType>
<s:sequence>
<s:element minOccurs=”0″ maxOccurs=”1″ name=”GetWeatherResult” type=”s:string”/>
</s:sequence>
</s:complexType>
</s:element>
 
 
Above is the definition of the GetWeather and the GetWeatherResponse data type. Notice that the GetWeather data type is a sequence complexType with two elements CityName and CountryName. Basically this means that in PHP you’ll pass an associative array with keys CityName and CountryName and having values of type string. Therefore our call to get the weather in Lagos will be 
 
$res = $client->GetWeather(array(‘CityName’ => ‘Lagos’, ‘CountryName’ => ‘Nigeria’));
 
 
Here is a sample of the response 
object(stdClass) {
	GetWeatherResult => '<?xml version="1.0" encoding="utf-16"?>
<CurrentWeather>
  <Location>Lagos / Ikeja, Nigeria (DNMM) 06-35N 003-20E 38M</Location>
  <Time>Dec 04, 2013 - 03:30 AM EST / 2013.12.04 0830 UTC</Time>
  <Wind> from the NW (320 degrees) at 6 MPH (5 KT) (direction variable):0</Wind>
  <Visibility> 4 mile(s):0</Visibility>
  <SkyConditions> partly cloudy</SkyConditions>
  <Temperature> 80 F (27 C)</Temperature>
  <DewPoint> 75 F (24 C)</DewPoint>
  <RelativeHumidity> 83%</RelativeHumidity>
  <Pressure> 29.97 in. Hg (1015 hPa)</Pressure>
  <Status>Success</Status>
</CurrentWeather>'
}
This is as defined in the WSDL i.e. GetWeatherResponse is a sequence complexType having an element GetWeatherResult. The value of the element is an XML document which can be parsed easily. 
 
This example is a bit complicated because of the use of complexTypes. Some web services take string parameters hence that would be very straight forward.
 
Hope this helps. Please leave a comment below if you have any issues with this and I’ll get back to you.
 
Cheers!
Standard