Remote services using REST

In this example, we implement a REST client and a REST server.

Components used in this example

• Zend_Rest_Client
• Zend_Rest_Server

---

MyRestClient MyRestServer MyScalarService MyArrayService MyHtml Entry point HTML | Try it | View source code

Implementation of the client

class MyRestClient
{

Processing the user request

• We get the data and the action.
• We parse the data to get a scalar or an array.
• We set the server name. It is the same as the client plus one parameter to indicate it is the server.
• We get the list of remote methods. We remove the system methods.
• We process the request.
• If there is a XML node named response, we get the response that is a scalar.
• Otherwise we extract the array from the XML node.
• We add the response details if needed.
• If we catch an exception, we return the error message.

    public function process()
    {
        // We get the data and the action.
        list($data, $action, $response) = $this->_getParameters();

        $methods = array();
        
        try {
            // We parse the data to get a scalar or an array.
            $parsed = $this->_parseData($data);
            
            // We set the server name.
            // It is the same as the client plus one parameter to indicate it is the server.
            $server = "http://{$_SERVER['HTTP_HOST']}{$_SERVER['PHP_SELF']}?server=";
            $client = new Zend_Rest_Client($server);

            // We get the list of remote methods. We remove the system methods.
            $get = $client->getFunctions()->get();
            $methods = $this->_toArray($get->getFunctions);
            $methods = preg_grep('~^(array|scalar)_\w+$~', $methods);
            sort($methods);
            
            // We process the request.
            if ($action) {
                $get = $client->$action($parsed)->get();
                
                if ($get->getStatus()) {
                    if (isset($get->response)) {
                        // If there is a XML node named response, 
                        // we get the response that is a scalar. 
                        $result['GET'] = (string)$get;
                    } else {
                        // Otherwise we extract the array from the XML node.
                        $result['GET'] = $this->_toArray($get->$action);
                    }
                } else {
                    $result['ERROR'] = (string)$get;                        
                }

                // We add the response details if needed.
                $response and $result['RESPONSE'] = $get;
                
            } else {
                $result = 'Enter some data and select an action.';
            }                        
            
        } catch (Exception $e) {
            // If we catch an exception, we return the error message.
            $result = '[' . __CLASS__ . '] ' . $e->getMessage();
        }

        return array($data, $action, $response, $methods, $result);
    }

Extraction of the parameters from the GET request

    private function _getParameters()
    {
        $data = isset($_GET['data'])? $_GET['data'] : '';
        $action = isset($_GET['action'])? $_GET['action'] : null;
        $response = empty($_GET)? 0 : !empty($_GET['response']);

        return array($data, $action, $response);
    }

Extraction of the data into a scalar or an array.

    private function _parseData($data)
    {        
        if (strpos($data, "\n") === false) {
            return $data;
            
        } else {
            foreach(explode("\n", $data) as $line) {
                $parts = explode('=', $line, 2);
                if (count($parts) == 1) {
                    $parsed[] = trim($parts[0]);
                } else {
                    $parsed[trim($parts[0])] = trim($parts[1]);
                }
            }
            return $parsed;
        }
    }

Extraction of the array from the XML node

• We ignore the status that is returned as an array element.
• We explore nodes recursively.
• We replace the keys generated by ZF Server with the corresponding index.
• Or we keep the key as it is.

    private function _toArray($simpleXml)
    {
        $array = array();
        
        foreach((array)$simpleXml as $key => $value) {
            // We ignore the status that is returned as an array element.
            if (!($key == 'status' and strtolower($value) == 'success')) {
                // We explore nodes recursively.
                $value instanceof SimpleXMLElement and $value = $this->_toArray($value);
            
                if (preg_match('~^key_(\d+)$~', $key, $match)) {
                    // We replace the keys generated by ZF Server with the corresponding index.
                    $array[$match[1]] = $value;
                } else {
                    // Or we keep the key as it is.
                    $array[$key] = $value;
                }
            } 
        }
        
        return $array;
    }

}

Implementation of the server

class MyRestServer
{    
    private static $functions;

Processing the client request

• We instantiate the server.
• We add the class methods. Note: this method should ideally be excluded from the list.
• We save the list of service methods.
• We process the client request.
• If we catch an exception, we return the error message.

    public function process()
    {
        try {
            // We instantiate the server.
            $server = new Zend_Rest_Server();
            // We add the class methods. 
            // Note: this method should ideally be excluded from the list.
            $server->setClass(__CLASS__);
            $server->setClass('MyArrayService');
            $server->setClass('MyScalarService');
            
            // We save the list of service methods.
            self::$functions = array_keys($server->getFunctions());
            
            // We process the client request.
            $result = $server->handle();
            
        } catch (Exception $e) {
            // If we catch an exception, we return the error message.
            $result = '[' . __CLASS__ . '] ' . $e->getMessage();
        }

        return $result;
    }

Return the list of methods to the client

    public static function getFunctions()
    {
        return self::$functions;
    }

}

Implementation of the scalar methods

class MyScalarService
{

Decodes data encoded with MIME base64

    public static function scalar_base64_decode($string)
    {
        return base64_decode($string);
    }

Encodes data with MIME base64

    public static function scalar_base64_encode($string)
    {
        return base64_encode($string);
    }

Format a local time and date

    public static function scalar_date($timestamp)
    {
        return date(DATE_ISO8601, $timestamp);
    }

Calculate the md5 hash of a string

    public static function scalar_md5($string)
    {
        return md5($string);
    }

Finds whether a variable is a number or a numeric string

    public static function scalar_is_numeric($string)
    {
        return is_numeric($string);
    }

Make a string lowercase

    public static function scalar_strtolower($string)
    {
        return strtolower($string);
    }

Make a string uppercase

    public static function scalar_strtoupper($string)
    {
        return strtoupper($string);
    }

Parse about any English textual datetime description into a Unix timestamp

    public static function scalar_strtotime($string)
    {
        return strtotime($string);
    }

}

Implementation of the array methods

class MyArrayService
{

Calculate the sum of values in an array

    public static function array_sum($array)
    {
        return array_sum($array);
    }

Sort an array and maintain index association

    public static function array_asort($array)
    {
        asort($array);
        return $array;
    }

Sort an array by key

    public static function array_ksort($array)
    {
        ksort($array);
        return $array;
    }

Sort an array

    public static function array_sort($array)
    {
        sort($array);
        return $array;
    }

}

Displaying items

class MyHtml
{

Displaying the title of the page based on the file name.

    public static function printTitle()
    {
        $basename = basename(__FILE__, '.php');
        $title = ucwords(str_replace('-' , ' ', $basename));
        $zfVersion = Zend_Version::VERSION;
        $phpVersion = phpversion();
        echo "ZfEx $title (ZF/$zfVersion PHP/$phpVersion)";
    }

Displaying the selected option

    public static function printSelected($value, $target)
    {
        $value == $target and print 'selected="selected"';
    }

Displaying a check mark

    public static function printChecked($value)
    {
        empty($value) or print 'checked="checked"';
    }

Colorization of data

• We export the data as valid PHP code.
• We add the PHP tag, we colorize the code, we remove the PHP tag.
• We display the data.

    public static function colorize($mixed)
    {
        // We export the data as valid PHP code.
        $mixed = is_object($mixed)? print_r($mixed, true) : var_export($mixed, true);
        // We add the PHP tag, we colorize the code, we remove the PHP tag.
        $mixed = '<?' . "php $mixed";
        $mixed = str_replace("\'", 'ZFEX_QUOTE', $mixed);
        $mixed = str_replace("'", 'ZFEX_QUOTE', $mixed);
        $mixed = str_replace('"', 'ZFEX_DQUOTE', $mixed);
        $mixed = highlight_string($mixed, true);
        $mixed = str_replace('ZFEX_QUOTE', '&#039;', $mixed);
        $mixed = str_replace('ZFEX_DQUOTE', '&quot;', $mixed);
        $mixed = str_replace('&lt;?php&nbsp;', '', $mixed);
        // We display the data.
        echo "<pre>$mixed</pre>";
    }

Displaying a string or an array

• If the data is an array, we convert the array into a set of lines.
• We converts special characters into HTML entities.
• We convert new-line characters into line breaks.

    public static function display($mixed, $isNl2Br = true, $isStripslashes = true)
    {
        // If the data is an array, we convert the array into a set of lines.
        is_array($mixed) and $mixed = implode("\n", $mixed);
        $isStripslashes and $mixed = stripslashes($mixed);
        // We converts special characters into HTML entities.
        $mixed = htmlspecialchars($mixed, ENT_QUOTES, 'UTF-8');
        // We convert new-line characters into line breaks.
        $isNl2Br and $mixed = nl2br($mixed);
        echo $mixed;
    }

}

Entry point

• We set the default timezone that is used by the methods handling date and time.
• We capture all notices or errors. Notices and errors will be thrown as exceptions.
• We start the server to process the client request.
• Or we run the client interface depending on the URL parameter.
• Note: the code for the client and the server would most likely run in separate environments in a real application.

// We set the default timezone that is used by the methods handling date and time.
date_default_timezone_set('UTC');

// We capture all notices or errors. 
// Notices and errors will be thrown as exceptions.
$fct = create_function('$errno, $errstr', 'throw new Exception($errstr);');
set_error_handler($fct);

if (isset($_GET['server'])) {
    // We start the server to process the client request.
    $server = new MyRestServer();
    $server->process();
    exit;
} else {
    // Or we run the client interface depending on the URL parameter.
    $client = new MyRestClient();
    list($data, $action, $response, $methods, $result) = 
        $client->process();
    // Note: the code for the client and the server would most likely run 
    // in separate environments in a real application.
}

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title><?php MyHtml::printTitle();?></title>
    <style type="text/css">
      body, td {
          font-family: arial, sans-serif;
          font-size: 0.9em;
      }
      .data {
          height: 8em;
          width: 20em;
      }
    </style>
  </head>

  <body>

    <p>EXAMPLE <?php MyHtml::printTitle();?></p>
    <hr />

    <form name="form">

      <table>

        <tr>
          <td>Data</td>
          <td>
            <textarea name="data"
                      class="data"><?php MyHtml::display($data, false);?></textarea>
          </td>
          <td>
             Data is one of the following:
             <ul>
               <li>A scalar value (integer, double, string, base64).</li>
               <li>A date, I.e. 1 January 1970, or a timestamp, I.e. 0.</li>
               <li>A list of values (indexed array), one value per line.</li>
               <li>A list of key=value's (associative array or struct), INI format.</li>
             </ul>
          </td>
        </tr>

        <tr><td>&nbsp;</td></tr>

        <tr>
          <td>Action</td>
          <td>
            <select name="action">
              <option></option>
              <?php foreach($methods as $name):?>
              <option <?php MyHtml::printSelected($action, $name);?>>
                <?php echo $name;?>
              </option>
              <?php endforeach;?>
            </select>
          </td>
        </tr>

        <tr><td>&nbsp;</td></tr>

        <tr>
          <td></td>
          <td>
            <input type="checkbox" name="response" value="1"
                   <?php MyHtml::printChecked($response);?> />
            Get response
          </td>
        </tr>

        <tr><td>&nbsp;</td></tr>

        <tr>
          <td></td>
          <td>
            <input type="submit" value="Submit" />
          </td>
        </tr>

      </table>
    </form>

    <hr />
    RESULT
    <?php MyHtml::colorize($result);?>

  </body>
</html>

Remote services with XML-RPC

In this example, we implement an XML-RPC client and an XML-RPC server. We also use namespaces, the XMLRPC data types, and the server proxy.

Components used in this example

• Zend_XmlRpc_Client
• Zend_XmlRpc_Server
• Zend_XmlRpc_Server_Fault
• Zend_XmlRpc_Value

---

MyXmlRpcClient MyXmlRpcServer MyScalarService MyArrayService MyHtml Entry point HTML | Try it | View source code

Implementation of the client

• We define the XMLRPC types.

class MyXmlRpcClient
{
    // We define the XMLRPC types.
    public static $types = array(
         'AUTO_DETECT_TYPE',
         'XMLRPC_TYPE_APACHEI8',
         'XMLRPC_TYPE_APACHENIL',
         'XMLRPC_TYPE_ARRAY',
         'XMLRPC_TYPE_BASE64',
         'XMLRPC_TYPE_BOOLEAN',
         'XMLRPC_TYPE_DATETIME',
         'XMLRPC_TYPE_DOUBLE',
         'XMLRPC_TYPE_I4',
         'XMLRPC_TYPE_I8',
         'XMLRPC_TYPE_INTEGER',
         'XMLRPC_TYPE_NIL',
         'XMLRPC_TYPE_STRING',
         'XMLRPC_TYPE_STRUCT',
         // 'XML_STRING',
    );

Processing the user request

• We get the data, the action, the data type, etc...
• We parse the data to get a scalar or an array.
• We convert the data to a given XMLRPC type if requested.
• We set the server name. It is the same as the client plus one parameter to indicate it is the server.
• We get the list of remote methods. We remove the system methods.
• We process the request.
• We use the proxy server if requested.
• We add the response details and the request details if needed.
• If we catch an exception, we return the error message.

    public function process()
    {
        // We get the data, the action, the data type, etc...
        list($data, $action, $type, $request, $response, $proxy) = $this->_getParameters();

        $methods = array();
        
        try {
            // We parse the data to get a scalar or an array.
            $parsed = $this->_parseData($data);
            // We convert the data to a given XMLRPC type if requested.
            $type and $parsed = Zend_XmlRpc_Value::getXmlRpcValue($parsed, 
                constant("Zend_XmlRpc_Value::$type"));
            
            // We set the server name.
            // It is the same as the client plus one parameter to indicate it is the server.
            $server = "http://{$_SERVER['HTTP_HOST']}{$_SERVER['PHP_SELF']}?server=";
            $client = new Zend_XmlRpc_Client($server);

            // We get the list of remote methods. We remove the system methods.
            $methods = $client->getIntrospector()->listMethods();
            $methods = preg_grep('~^system~', $methods, PREG_GREP_INVERT);
            sort($methods);
            
            // We process the request.
            switch($action) {
                case 'listMethods':
                case 'getSignatureForEachMethod':
                    $result = $client->getIntrospector()->$action();
                    break;
                    
                case '':
                    $result = 'Enter some data and select an action.';
                    break;
                    
                default:
                    // We use the proxy server if requested.
                    if ($proxy) {
                        list($service, $method) = explode('.', $action);
                        $server = $client->getProxy($service);
                        $result['PROXY'] = $server->$method($parsed);
                    } else {
                        $result['CALL'] = $client->call($action, array($parsed));
                    }
                    // We add the response details and the request details if needed.
                    $response and $result['RESPONSE'] = $client->getLastResponse();
                    $request and $result['REQUEST'] = $client->getLastRequest();
            }
                        
            
        } catch (Exception $e) {
            // If we catch an exception, we return the error message.
            $result = '[' . __CLASS__ . '] ' . $e->getMessage();
        }

        return array($data, $action, $type, $request, $response, $proxy, $methods, $result);
    }

Extraction of the parameters from the GET request

    private function _getParameters()
    {
        $data = isset($_GET['data'])? $_GET['data'] : '';
        $action = isset($_GET['action'])? $_GET['action'] : null;
        $type = (isset($_GET['type']) and in_array($_GET['type'], self::$types))? 
            $_GET['type'] : null;
        $request = empty($_GET)? 0 : !empty($_GET['request']);
        $response = empty($_GET)? 0 : !empty($_GET['response']);
        $proxy = empty($_GET)? 0 : !empty($_GET['proxy']);

        return array($data, $action, $type, $request, $response, $proxy);
    }

Extraction of the data into a scalar or an array.

    private function _parseData($data)
    {        
        if (strpos($data, "\n") === false) {
            return $data;
            
        } else {
            foreach(explode("\n", $data) as $line) {
                $parts = explode('=', $line, 2);
                if (count($parts) == 1) {
                    $parsed[] = trim($parts[0]);
                } else {
                    $parsed[trim($parts[0])] = trim($parts[1]);
                }
            }
            return $parsed;
        }
    }

}

Implementation of the server

class MyXmlRpcServer
{

Processing the client request

• We allow exceptions to be reported as fault responses.
• We instantiate the server.
• We add the class methods. We have one namespace for scalar methods and one namespace for array methods.
• We process the client request.
• If we catch an exception, we return the error message.

    public function process()
    {
        try {
            // We allow exceptions to be reported as fault responses.
            Zend_XmlRpc_Server_Fault::attachFaultException('Exception');

            // We instantiate the server.
            $server = new Zend_XmlRpc_Server();
            // We add the class methods. 
            // We have one namespace for scalar methods and one namespace for array methods.
            $server->setClass('MyArrayService', 'array');
            $server->setClass('MyScalarService', 'scalar');
            // We process the client request.
            $result = $server->handle();
            
        } catch (Exception $e) {
            // If we catch an exception, we return the error message.
            $result = '[' . __CLASS__ . '] ' . $e->getMessage();
        }

        return $result;
    }

}

Implementation of the scalar methods

class MyScalarService
{

Decodes data encoded with MIME base64

    public static function base64_decode($string)
    {
        return base64_decode($string);
    }

Encodes data with MIME base64

    public static function base64_encode($string)
    {
        return base64_encode($string);
    }

Format a local time and date

    public static function date($timestamp)
    {
        return date(DATE_ISO8601, $timestamp);
    }

Calculate the md5 hash of a string

    public static function md5($string)
    {
        return md5($string);
    }

Finds whether a variable is a number or a numeric string

    public static function is_numeric($string)
    {
        return is_numeric($string);
    }

Make a string lowercase

    public static function strtolower($string)
    {
        return strtolower($string);
    }

Make a string uppercase

    public static function strtoupper($string)
    {
        return strtoupper($string);
    }

Parse about any English textual datetime description into a Unix timestamp

    public static function strtotime($string)
    {
        return strtotime($string);
    }

}

Implementation of the array methods

class MyArrayService
{

Calculate the sum of values in an array

    public static function array_sum($array)
    {
        return array_sum($array);
    }

Sort an array and maintain index association

    public static function asort($array)
    {
        asort($array);
        return $array;
    }

Sort an array by key

    public static function ksort($array)
    {
        ksort($array);
        return $array;
    }

Sort an array

    public static function sort($array)
    {
        sort($array);
        return $array;
    }

}

Displaying items

class MyHtml
{

Displaying the title of the page based on the file name.

    public static function printTitle()
    {
        $basename = basename(__FILE__, '.php');
        $title = ucwords(str_replace('-' , ' ', $basename));
        $zfVersion = Zend_Version::VERSION;
        $phpVersion = phpversion();
        echo "ZfEx $title (ZF/$zfVersion PHP/$phpVersion)";
    }

Displaying the selected option

    public static function printSelected($value, $target)
    {
        $value == $target and print 'selected="selected"';
    }

Displaying a check mark

    public static function printChecked($value)
    {
        empty($value) or print 'checked="checked"';
    }

Colorization of data

• We export the data as valid PHP code.
• We add the PHP tag, we colorize the code, we remove the PHP tag.
• We display the data.

    public static function colorize($mixed)
    {
        // We export the data as valid PHP code.
        $mixed = is_object($mixed)? print_r($mixed, true) : var_export($mixed, true);
        // We add the PHP tag, we colorize the code, we remove the PHP tag.
        $mixed = '<?' . "php $mixed";
        $mixed = str_replace("\'", 'ZFEX_QUOTE', $mixed);
        $mixed = str_replace("'", 'ZFEX_QUOTE', $mixed);
        $mixed = str_replace('"', 'ZFEX_DQUOTE', $mixed);
        $mixed = highlight_string($mixed, true);
        $mixed = str_replace('ZFEX_QUOTE', '&#039;', $mixed);
        $mixed = str_replace('ZFEX_DQUOTE', '&quot;', $mixed);
        $mixed = str_replace('&lt;?php&nbsp;', '', $mixed);
        // We display the data.
        echo "<pre>$mixed</pre>";
    }

Displaying a string or an array

• If the data is an array, we convert the array into a set of lines.
• We converts special characters into HTML entities.
• We convert new-line characters into line breaks.

    public static function display($mixed, $isNl2Br = true, $isStripslashes = true)
    {
        // If the data is an array, we convert the array into a set of lines.
        is_array($mixed) and $mixed = implode("\n", $mixed);
        $isStripslashes and $mixed = stripslashes($mixed);
        // We converts special characters into HTML entities.
        $mixed = htmlspecialchars($mixed, ENT_QUOTES, 'UTF-8');
        // We convert new-line characters into line breaks.
        $isNl2Br and $mixed = nl2br($mixed);
        echo $mixed;
    }

}

Entry point

• We set the default timezone that is used by the methods handling date and time.
• We capture all notices or errors. Notices and errors will be thrown as exceptions.
• We start the server to process the client request.
• Or we run the client interface depending on the URL parameter.
• Note: the code for the client and the server would most likely run in separate environments in a real application.

// We set the default timezone that is used by the methods handling date and time.
date_default_timezone_set('UTC');

// We capture all notices or errors. 
// Notices and errors will be thrown as exceptions.
$fct = create_function('$errno, $errstr', 'throw new Exception($errstr);');
set_error_handler($fct);

if (isset($_GET['server'])) {
    // We start the server to process the client request.
    $server = new MyXmlRpcServer();
    echo $server->process();
    exit;
} else {
    // Or we run the client interface depending on the URL parameter.
    $client = new MyXmlRpcClient();
    list($data, $action, $type, $request, $response, $proxy, $methods, $result) = 
        $client->process();
    // Note: the code for the client and the server would most likely run 
    // in separate environments in a real application.
}

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title><?php MyHtml::printTitle();?></title>
    <style type="text/css">
      body, td {
          font-family: arial, sans-serif;
          font-size: 0.9em;
      }
      .data {
          height: 8em;
          width: 20em;
      }
    </style>
  </head>

  <body>

    <p>EXAMPLE <?php MyHtml::printTitle();?></p>
    <hr />

    <form name="form">

      <table>

        <tr>
          <td>Data</td>
          <td>
            <textarea name="data"
                      class="data"><?php MyHtml::display($data, false);?></textarea>
          </td>
          <td>
             Data is one of the following:
             <ul>
               <li>A scalar value (integer, double, string, base64).</li>
               <li>A date, I.e. 1 January 1970, or a timestamp, I.e. 0.</li>
               <li>A list of values (indexed array), one value per line.</li>
               <li>A list of key=value's (associative array or struct), INI format.</li>
             </ul>
          </td>
        </tr>

        <tr><td>&nbsp;</td></tr>

        <tr>
          <td>Action</td>
          <td>
            <select name="action">
              <option></option>
              <optgroup label="Service methods">
                <?php foreach($methods as $name):?>
                <option <?php MyHtml::printSelected($action, $name);?>>
                  <?php echo $name;?>
                </option>
                <?php endforeach;?>
              </optgroup>
              
              <optgroup label="Server introspection">
                <option <?php MyHtml::printSelected($action, 'listMethods');?>>
                  listMethods</option>
                <option <?php MyHtml::printSelected($action, 'getSignatureForEachMethod');?>>
                  getSignatureForEachMethod</option>
              </optgroup>
            </select>
          </td>
        </tr>

        <tr><td>&nbsp;</td></tr>

        <tr>
          <td>Type</td>
          <td>
            <select name="type">
              <option value="">Native PHP type</option>
              <optgroup label=" XMLRPC_TYPE*">
                <?php foreach(MyXmlRpcClient::$types as $name):?>
                <option <?php MyHtml::printSelected($type, $name);?>>
                  <?php echo $name;?>
                </option>
                <?php endforeach;?>
              </optgroup>
            </select>
          </td>
          <td>The XMLRPC type will be applied to the data before the call if selected.
          </td>
        </tr>

        <tr><td>&nbsp;</td></tr>

        <tr>
          <td></td>
          <td>
            <input type="checkbox" name="response" value="1"
                   <?php MyHtml::printChecked($response);?> />
            Get last response
          </td>
        </tr>

        <tr>
          <td></td>
          <td>
            <input type="checkbox" name="request" value="1"
                   <?php MyHtml::printChecked($request);?> />
            Get last request
          </td>
        </tr>

        <tr>
          <td></td>
          <td>
            <input type="checkbox" name="proxy" value="1"
                   <?php MyHtml::printChecked($proxy);?> />
            Use proxy
          </td>
        </tr>

        <tr><td>&nbsp;</td></tr>

        <tr>
          <td></td>
          <td>
            <input type="submit" value="Submit" />
          </td>
        </tr>

      </table>
    </form>

    <hr />
    RESULT
    <?php MyHtml::colorize($result);?>

  </body>
</html>