Getting Started

To make use of the bundled library, you must first include the Recite_Webservices class (located in ./Recite/Webservices.php). This is a static class you use to set your username, password and web site URL, as well as to build a SoapClient object to access the required service.

Following is a script that shows how this achieved, using the example URL and credentials mentioned earlier in this guide.

<?php
    require_once('Recite/Webservices.php');
    
    Recite_Webservices::SetCredentials('wsuser', 'wspass');
    Recite_Webservices::SetUrl('http://xyz.example.com');
?>

To retrieve a configured instance of SoapClient with which to access web services, call the Factory() method on the Recite_Webservices class. This method takes a single argument, which is the name of the service to access. If no service is specified, the default web service is used. This service can be used to tell you which other services are available.

For example, to access the default web service and then call the getReciteVersion() method on it, you would use the following code:

<?php
    require_once('Recite/Webservices.php');
    
    Recite_Webservices::SetCredentials('wsuser', 'wspass');
    Recite_Webservices::SetUrl('http://xyz.example.com');
    
    $service = Recite_Webservices::Factory();
    
    echo $service->getReciteVersion();
?>

You can also see the other available services by calling getServices() on the default service (index). This will return an array with the names of the other services.

<?php
    require_once('Recite/Webservices.php');
    
    Recite_Webservices::SetCredentials('wsuser', 'wspass');
    Recite_Webservices::SetUrl('http://xyz.example.com');
    
    $service = Recite_Webservices::Factory();
    
    var_dump($service->getServices());
?>

This would result in the following output:

array
    0 => string 'pages' (length=5)
    1 => string 'users' (length=5)
    2 => string 'ecommerce' (length=9)
    3 => string 'assets' (length=6)
    4 => string 'search' (length=6)
    5 => string 'forms' (length=5)
    6 => string 'calendar' (length=8)
    7 => string 'listings' (length=8)
    8 => string 'templates' (length=9)
    9 => string 'index' (length=5)
    10 => string 'auth' (length=4)

You can use any of these values to access the respective web service. For instance, to use the Page Manager web service, you would pass pages to the Factory() method.

<?php
    // ...
    
    $service = Recite_Webservices::Factory('pages');
?>

To determine which methods and data types are available for each web service, you can either browse the WSDL file directly, or you can call the factory method for the required service then call $service->__getFunctions() or $service->__getTypes(). Alternatively, you can use the bundled test suite to browse and try the available methods on each service (see later in this chapter).

When using both the Recite_Webservices class and the SoapClient class (for calling web service functions), exceptions are thrown if any operations fail.

If an error occurs using Recite_Webservices (or one of the bundled type classes), the Recite_Webservices_Exception is thrown.

If an error occurs in calling a SOAP method, the built-in SoapFault exception type is thrown.

For example, an error setting the client URL:

<?php
    // ...
    
    try {
        Recite_Webservices::SetUrl('12345');
    }
    catch (Exception $ex) {
        die('Error setting the client URL: ' . $ex->getMessage());
    }
    
    // ...
?>

An example of an error occurring using the web service (in this example a non-existent method is called):

<?php
    // ...
    
    try {
        $service->madeUpMethod();
    }
    catch (Exception $ex) {
        die('Error in SOAP request: ' . $ex->getMessage());
    }
    
    // ...
?>

It is highly recommended that if you're going to use the bundled PHP library to access Recite web services that you first install the test suite to help become familiar with the services available. There are many sample scripts available that show you how to build requests and handle returned data nicely.

Let's assume you install the test suite in /var/www/wstest. You would need to set up /var/www/wstest/htdocs as the web root, and the include path as both /var/www/wstest/include and /var/www/wstest/lib.

A sample Apache configuration <VirtualHost> is as follows:

<VirtualHost *:80>
    ServerName wstest.example.com
    DocumentRoot /var/www/wstest/htdocs
    
    php_value include_path /var/www/wstest/include:/var/www/wstest/lib
</VirtualHost>

Once you've set up this host and restarted your web server, you can view the test suite by visiting http://wstest.example.com in your browser (of course substituting in your own host name).

The test suite comes bundled with full API documentation for the provided data types. These data types map directly back to the types returned by the Recite web services. The API guide also contains extensive description of the data available. Assuming you've set up the test suite as described in the previous section, you can visit http://wstest.example.com/api to view the API.