Programming the KwaMoja API - A simple client part 2

This is the second part of the tutorial on building a PHP client to extract data from KwaMoja via the API. If you missed the first, read this first. In the last part we created a client that queried the KwaMoja installation and extracted a list of stock locations, we then used to populate a drop down list in our HTML page. What we then wanted to do, was to extract the full name of the location, rather than just showing the code.

To do this we need a function much like the one we used to extract the array of location codes. Here is the full code:

    function LocationName($LocationCode) {

        //Encode the data items
        $UserID = php_xmlrpc_encode("admin");
        $Password = php_xmlrpc_encode("kwamoja");
        $Code = php_xmlrpc_encode($LocationCode);

        //Create a client object to use for xmlrpc call and set its debug level to zero
        $Client = new xmlrpc_client("http://localhost/KwaMoja/api/api_xml-rpc.php");
        $Client->setDebug(0);

        //Create a message object, containing the parameters and the function name
        $Message = new xmlrpcmsg('kwamoja.xmlrpc_GetLocationDetails', array($Code, $UserID, $Password));

        //Use the client object to send the message object to the server, returning the response
        $Response = $Client->send($Message);

        //Decode the response and return the array
        $ReturnValue = php_xmlrpc_decode($Response->value());
        if ($ReturnValue[0] == 0) {
            return $ReturnValue[1]['locationname'];
        }
    }

The first section encodes the parameters as XML. The first two parameters are always the userid/password combination, and for this function call we need a third parameter, which is the code of the location that we require the name of. The second section is identical to the previous function and creates an instance of the XML-RPC client class. The third section then creates an instance of the message class, with the first parameter being the full name of the API function being called, in this case kwamoja.xmlrpc_GetLocationDetails, and then the second parameter is an array of the encoded parameters, (location code, userid, password). This message is then sent to the server, and the response decoded into an array called $ReturnValue.

As last time the first element of the array signifies whether the function was successful (a zero), or any other integer for an error code. The second element is an associative array of details for that location. The key of each element is the field name for that value. In our case we just want the location name, so we return the element ['locationname']. If it was the telephone number we were interested in we would just return the ['tel'] element.

Changing the line in the HTML where we fill the drop down box to:

echo '<option value="'.$LocationCode.'">'.LocationName($LocationCode).'</option>';

we can see that the web page in our browser now looks a little better.

The full name of the location appears in the drop down the list, but the value returned by the form is still just the code.

All that is left to complete our client, is to type a stock code in the text box, submit the form and return the amount of stock for that code at the chosen location. First we need to insert some PHP code in the HTML to handle the form being sent:

<?php
        if (isset($_POST['submit'])) {
            echo 'The quantity of '.$_POST['StockID'].' at '.$_POST['location'] . ' is : ''.GetStockQuantity($_POST['StockID'], $_POST['location']);
        }
 ?>

As you can see this calls another PHP function - GetStockQuantity() - that retrieves the stock quantity for the required item at the required location. Looking at the API function reference in the manual the API function we require is kwamoja.xmlrpc_GetStockBalance. However this time there is a small addition we require as this function returns an array containing the stock balances at all the locations for the given stock item.

The full code for the PHP function is:


    function GetStockQuantity($StockID, $LocationCode) {
        //Encode the data items
        $UserID = php_xmlrpc_encode("admin");
        $Password = php_xmlrpc_encode("kwamoja");
        $StockCode = php_xmlrpc_encode($StockID);

        //Create a client object to use for xmlrpc call and set its debug level to zero
        $Client = new xmlrpc_client("http://localhost/KwaMoja/api/api_xml-rpc.php");
        $Client->setDebug(0);
        //Create a message object, containing the parameters and the function name
        $Message = new xmlrpcmsg('kwamoja.xmlrpc_GetStockBalance', array($StockCode, $UserID, $Password));
        //Use the client object to send the message object to the server, returning the response
        $Response = $Client->send($Message);
        //Decode the response and return the array
        $ReturnValue = php_xmlrpc_decode($Response->value());
        if ($ReturnValue[0] == 0) {
            $Items = $ReturnValue[1];
            for ($i=0; $i<sizeOf($Items); $i++) {
                if ($Items[$i]['loccode']==$LocationCode) {
                    return $Items[$i]['quantity'];
                }
            }
        }
    }

I wont go through this in details as it is mostly the same as the previous functions. The key section is the last:

        $ReturnValue = php_xmlrpc_decode($Response->value());
        if ($ReturnValue[0] == 0) {
            $Items = $ReturnValue[1];
            for ($i=0; $i<sizeOf($Items); $i++) {
                if ($Items[$i]['loccode']==$LocationCode) {
                    return $Items[$i]['quantity'];
                }
            }
        }

Here the RPC returns an array of locations with the stock quantities for each location, and we filter out the location we need.

Putting all this together we get the following when we run the script in our browser:

Looking at the stock status in KwaMoja we see:

Showing that we have returned the correct numbers.

I have uploaded the source for this tutorial to http://www.kwamoja.com/documentation/xml-rpc_tutorial.zip please feel free to download and try it out.

In the next part I will introduce some error checking into the code.