View on GitHub

equella.github.io

Home

PHP SOAP Tutorial

  Table of Contents

Running the examples

You need to have the SOAP extension enabled in your PHP installation to use these samples. To do this, make sure you have extension=php_soap.dll (Windows) or extension=php_soap.so (UNIX) in your php.ini file. Restart your web server after making this change. You may need to download the appropriate extension file if you do not have it. Also make sure that your PHP installation has ‘magic quotes’ disabled (http://www.php.net/manual/en/security.magicquotes.disabling.php)

To run the example files, modify settings.php with the appropriate values (SOAP endpoint, username and password). The SOAP endpoint is of the format: http://INSTITUTION_URL/services/SoapService50

For example: http://mydomain.edu.au/myinst/services/SoapService50

Guide to the example code

The example code contains some helper classes (EQUELLA and XMLWrapper) which you are free to use and modify. These classes have been created to simplify the processing of the XML results and XML parameters returned from and supplied to the SOAP methods. The EQUELLA and XMLWrapper classes are not required to use the EQUELLA SOAP service, they are simply for convenience.

This example shows how you can retrieve a list of items from EQUELLA based on a few search parameters. Most of the code in the search.php file is dedicated to displaying the form; the actual SOAP invocation code is clearly marked ‘EQUELLA SOAP Searching Code’ at the bottom of the file. Here is a summary of that code:

Contribute

This example shows how you can contribute an item to a collection and give it a name, description and a file attachment. As with the search example, much of the contribute.php code is dedicated to displaying the form. The contribution SOAP code is clearly marked ‘EQUELLA SOAP Contribution Code’ towards the bottom of the file. Here is a summary of that code:

Writing your own code

In general the process for invoking a SOAP method is as follows:

  1. Create a SoapClient object. When creating a SoapClient object, you MUST also specify the optional ‘location’ parameter. The WSDL files generated by the EQUELLA server have an incorrect URL within them.
  2. Call the login method. The parameter names when invoking SOAP methods are ‘in0’, ‘in1’, ‘in2’ etc and values for all of these need to be specified. (Note that all Boolean parameters should be specified as ‘0’ or ‘1’) For example, to invoke the login method:
    $client->login(array('in0' => $username, 'in1' => $password));
    

    The user that you login as must have sufficient privileges to perform your required task. You cannot do anything over SOAP that you cannot do within the EQUELLA Digital Repository.

  3. Invoke a method: The results of all SOAP methods (if available) will always be in a field called ‘out’. E.g.:
    $collections = $client->getContributableCollections()->out;
    

    NOTE: All SOAP methods will return either a simple string, number or an XML object. We recommend using the PHP DOMDocument and DOMXPath classes to parse the results of any SOAP call.

  4. Call the logout method This is not strictly necessary, the user session will eventually time out on the server, but it is good practice to call logout to free server side resources.