In this example we will see an example of a SOAP client communicating with a server. SOAP is one of many web service protocol definition. A web service is a technology that uses a protocol (SOAP in this example) for exchanging data between applications over the network.
If we are developing a client for consuming a web service, we have to look at the protocol that the service is using. This example is for looking at the resources provided by PHP for developing a client for a web service implementing the SOAP protocol.
For this example, we will use:
- Ubuntu (14.04) as Operating System.
- Apache HTTP server (2.4.7).
- PHP (5.5.9).
You may skip environment preparation creation and jump directly to the beginning of the example below.
1. Preparing the environment
1.1. Installation
Below, commands to install Apache and PHP are shown:
sudo apt-get update sudo apt-get install apache2 php5 libapache2-mod-php5 sudo service apache2 restart
1.2. PHP configuration
Even if it’s not necessary, is recommendable to disable the SOAP WSDL cache for development environments. In /etc/php5/apache2/php.ini file, set the soap.wsdl_cache_enabled directive to 0:
php.ini
soap.wsdl_cache_enabled=0
Don’t forget to restart Apache after doing any change.
Note: if you want to use Windows, installing XAMPP is the fastest and easiest way to install a complete web server that meets the prerequisites.
2. What is SOAP?
SOAP (Simple Object Access Protocol) is a standard protocol that defines how two different objects in different processes can communicate each other, through data exchange in XML format. Is one of the widest protocols used in web services.
In other words, this protocol allows to call method of objects that are defined in remote machines.
3. PHP example of SOAP clients
The server offering their SOAP services can define them in two different ways:
- With WSDL (Web Services Definition Language)
- Without WSDL
From the client point of view, there are very few differences, but let’s see how to proceed for each one.
We will consider the following scenario, which is quite typical: a web service that inserts and reads from a database (simulated with a plain text file), for which we will develop a client.
Is responsibility of the server offering the service to let know the protocol used, as same as the available method definitions, in order to let the clients know how to deal with the service.
Even if this tutorial is about the client itself, we will see also the server side, in order to test that the client is actually working.
3.1. Working directory structure
For this example, we will use the following structure:
php_soapclient_example/ ├── simple_soap_client_class.php ├── simple_soap_server_class.php ├── handle_soap_request.php ├── no_wsdl │ └── server_endpoint.php └── wsdl ├── server_endpoint.php └── simple_service_definition.wsdl
Where the root directory, php_soapclient_example, will be in the web server’s root directory, which is /var/www/html/ by default.
Briefly explained each file:
simple_soap_client_class.phpis the class defined for the SOAP client methods.simple_soap_server_class.phpis the class defined for the SOAP server methods.handle_soap_request.phpis for instantiate and use theSimpleSoapClientclass defined insimple_soap_client_class.php.- In the directories
wsdlandno_wsdl, the service defined insimple_soap_server_class.phpis offered, in the way it accords to each of the modes. We won’t go into details for these, since it is not the purpose of this example. The only thing we have to know is that in one of the directories there is a service offered in WSDL mode, and that in the other, in no WSDL mode; they are two independent web services that use the code defined insimple_soap_server_class.php.
Note: the WSDL mode needs a .wsdl file, where the web service is defined. We are not going to see it in this example, since the aim is not to see how to build a WSDL definition file, but it’s also available to download in the last section of the example.
3.2. The server
As said, our server will read and write data into a text file. Let’s see it:
simple_soap_server_class.php
<?php
/**
* Methods of our simple SOAP service.
*/
class SimpleSoapServer {
const FILENAME = 'data.txt';
/**
* Inserts data. Invoked remotely from SOAP client.
*
* @param $data Data to insert.
* @return Resume of operation.
*/
public function insertData($data) {
$writtenBytes = file_put_contents(self::FILENAME, $data . '<br>', FILE_APPEND);
if ($writtenBytes) {
$response = "$writtenBytes bytes have been inserted.";
} else {
$response = 'Error inserted data.';
}
return $response;
}
/**
* Reads data. Invoked remotely from SOAP client.
*
* @return Data of file.
*/
public function readData() {
$contents = file_get_contents(self::FILENAME);
return $contents;
}
}So simple, about reading and writing into a text file.
Note the functions this server implements, in lines 16 and 33. This functions will be those invoked by the client.
3.3. The client
As we said above, depending of the mode (WSDL or not WSDL), the client has to handle the connection in a different way but, once stablished, the procedure is the same. So, let’s code a class that works for both modes, handling the SoapClient class instantiation accordingly to the mode:
simple_soap_client_class.php
<?php
/**
* Methods for dealing with SOAP service.
*/
class SimpleSoapClient {
const MODE_WSDL = 'wsdl';
const MODE_NO_WSDL = 'no_wsdl';
private $client;
/**
* SimpleSoapClient class constructor.
*
* @param $soapMode The SOAP mode, WSDL or non-WSDL.
* @param $serverLocation The location of server.
*/
public function __construct($soapMode, $serverLocation) {
$this->initializeClient($soapMode, $serverLocation);
}
/**
* Instantiates the SoapClient, depending on the specified mode.
*
* For WSDL, it just has to be instantiated with the location of the service, which actually has to be the
* .wsdl location.
*
* For non-WSDL, the first parameter of the constructor has to be null; and the second, an array specifying
* both location and URI (which can be the same, the important parameter is the location).
*/
protected function initializeClient($soapMode, $serverLocation) {
switch ($soapMode) {
case self::MODE_WSDL:
$this->client = new SoapClient($serverLocation);
break;
case self::MODE_NO_WSDL:
$options = array(
'location' => $serverLocation,
'uri' => $serverLocation
);
$this->client = new SoapClient(NULL, $options);
break;
default:
throw new Exception('Error: invalid SOAP mode provided.');
break;
}
}
/**
* Inserts data remotely into the SOAP service.
*
* @param $data Data to insert remotely.
* @return Response from remote service.
*/
public function insertData($data) {
$response = $this->client->insertData($data);
return $response;
}
/**
* Reads data from SOAP service.
*
* @return Data received from remote service.
*/
public function readData() {
return $this->client->readData();
}
}The lines 35 and 45 instantiate the SoapClient class, depending on the $mode received. This is how it works for each mode:
- For WSDL mode, we have just to pass the server location to the constructor. For this mode, the location must be the WSDL definition file (
.wsdl), not a PHP file. - For non WSDL mode, the first parameter has to be null (because we are not accessing a WSDL definition). So, the location must be defined in a different way, providing an array with
'location'and'uri'elements, with the server location as values. In this case, the location must be the PHP file handling the web service.
After the instantiation, the communication with the service is pretty simple. We have just to call the methods that we saw defined in SimpleSoapServer class, in simple_soap_client_class.php, through the SoapClient class instance. As we said before, we are calling methods that are defined in other place. What PHP SoapClient does, is to provide us those methods defined by the web service, and, when we call them, it will execute them in the server through the SOAP protocol that it has already implemented, with no needing to care about how it works. Seems magic, doesn’t it?
If you don’t believe it, let’s see a script to use this client.
3.4. Using the client
The following script allows us to use the client to communicate with the service, through GET parameters. These are the parameters available:
'mode', to specify the mode (WSDL or non WSDL).'action', to specify the action to perform. Available values are'insert'and'read'.'value', to specify the value to insert, only necessary when the action is'insert'.
handle_soap_request.php
<?php
require_once('simple_soap_client_class.php');
// GET parameter definition.
define('ACTION_INSERT', 'insert');
define('ACTION_READ', 'read');
define('INSERT_VALUE', 'value');
define('MODE_WSDL', 'wsdl');
define('MODE_NO_WSDL', 'no_wsdl');
// Server location definition.
define('LOCATION_WSDL', 'http://127.0.0.1/php_soapclient_example/wsdl/simple_service_definition.wsdl');
define('LOCATION_NO_WSDL', 'http://127.0.0.1/php_soapclient_example/wsdl/server_endpoint.php');
// Function definitions.
/**
* Checks if the given parameters are set. If one of the specified parameters is not set,
* die() is called.
*
* @param $parameters The parameters to check.
*/
function checkGETParametersOrDie($parameters) {
foreach ($parameters as $parameter) {
isset($_GET[$parameter]) || die("Please, provide '$parameter' parameter.");
}
}
/**
* Instantiates the SOAP client, setting the server location, depending on the mode.
* If any error occurs, the page will die.
*
* @param $mode The SOAP mode, 'wsdl' or 'no_wsdl'.
* @return SoapClient class instance.
*/
function instantiateSoapClient($mode) {
if ($mode == MODE_WSDL) {
$serverLocation = LOCATION_WSDL;
} else {
$serverLocation = LOCATION_NO_WSDL;
}
try {
$soapClient = new SimpleSoapClient($mode, $serverLocation);
} catch (Exception $exception) {
die('Error initializing SOAP client: ' . $exception->getMessage());
}
return $soapClient;
}
// Flow starts here.
checkGETParametersOrDie(['mode', 'action']);
$mode = $_GET['mode'];
$action = $_GET['action'];
$soapClient = instantiateSoapClient($mode);
switch($action) {
case ACTION_INSERT:
checkGETParametersOrDie([INSERT_VALUE]);
$value = $_GET[INSERT_VALUE];
try {
$response = $soapClient->insertData($value);
echo "Response from SOAP service: $response<br>";
} catch (Exception $exception) {
die('Error inserting into SOAP service: ' . $exception->getMessage());
}
break;
case ACTION_READ:
try {
$data = $soapClient->readData();
echo "Received data from SOAP service:<br>";
echo $data;
} catch (Exception $exception) {
die('Error reading from SOAP service: ' . $exception->getMessage());
}
break;
default:
die('Invalid "action" specified.');
break;
}Let’s try it.
If we enter in the browser http://127.0.0.1/php_soapclient_example/handle_soap_request.php?mode=no_wsdl&action=insert&value=testing_no_wsdl, the service will create a no_wsdl/data.txt file (if not exists already), writing the provided value 'testing_no_wsdl', and the following will be printed:
Response from SOAP service: 19 bytes have been inserted.
(The 4 bytes extra correspond to additional <br> characters inserted into the file).
The service offers a method to reading all the data, so, if we enter in the browser http://127.0.0.1/php_soapclient_example/handle_soap_request.php?mode=no_wsdl&action=read, the following will be printed:
Received data from SOAP service:
testing_no_wsdl
We can check it also for WSDL mode, setting mode=wsdl in the parameters.
4. Considerations
As said in section 3, when we are developing a web service client (no matter if SOAP, REST, etc.), the service provider has to provide also documentation about the available methods; we need to know the definition of these: which parameters is expecting, af if it returns something. Because of that, the most usual way to develop a SOAP web service is using WSDL files, to provide documentation of the available methods. In any case, the SoapClient has a method to get the available methods, for debugging purposes, named __getFunctions(). So, we could see the offered methods by the service with the following:
var_dump($soapClient->__getFunctions())
Assuming that $soapClient has been instanced properly.
Also note that, if the service does not offer an encrypted connection, the communication between the client and the server will be made in plain text. So, if we have to develop a client that has to deal with sensible information, we should ensure that the communication with the server can be considered safe.
5. Summary
We have seen how to develop a client for a SOAP web service using PHP’s SoapClient class. The server may offer the service using WSDL, or not, something to take into account when we are instantiating the SoapClient class. Then, to use the methods provided by the service, we just have to call those methods in SoapClient instance, as they were ours.
6. Download the source code
This was an example of SoapClient with PHP.
You can download the full source code of this example here: PHPSoapClientExample
This post is very useful. Thank you for ur sharing. Hope you will continue posting other good posts :)