hi5 platform via PHP - Part 1

Both the hi5 platform and PHP support SOAP fairly well.  Here's a simple example of using the TestApiService and the AuthApiService to get your PHP app up and running fast.  The TestApiService includes an echo() call that returns what you pass in, and an auth() call that does the same thing, except it requires that you be authenticated.  The AuthApiService supports plenty of different methods that get you a hi5AuthToken, which allows access to authenticated methods.  We're going to use auth_plain() method to do a simple, insecure authentication.

First off, the machine we're working on here is a Linux host running Fedora 7.  We have the following PHP RPMs installed:

php-pear-1.5.0-3
php-common-5.2.4-1.fc7
php-mbstring-5.2.4-1.fc7
php-pdo-5.2.4-1.fc7
php-mysql-5.2.4-1.fc7
php-soap-5.2.4-1.fc7
php-xmlrpc-5.2.4-1.fc7
php-cli-5.2.4-1.fc7
php-gd-5.2.4-1.fc7
php-5.2.4-1.fc7
php-xml-5.2.4-1.fc7

You may or may not need all of these.  You will definitely need php-soap and php-xml.

Here's our PHP script:


<?php
    
    $testclient = new SoapClient( "http://api.hi5.com/hi5test.wsdl"); 

    try { 
       $result = $testclient->echo(array("message"=>"I love Hi5"));
       print $result->return->message . "\n";
    } catch (SoapFault $exception) {
       echo $exception;
    }

    try {
       $result = $testclient->auth(array("message"=>"I love Hi5"));
       print $result->return->message . "\n";
    } catch (SoapFault $exception) {
       print "Caught a problem with an auth method\n";
    }

    $authclient = new SoapClient( "http://api.hi5.com/hi5auth.wsdl");

    $result = $authclient->auth_plain(array("username"=>"USERNAME", 
                                            "password"=>"PASSWORD",
                                            "api_key"=> "APIKEY"));
    $authtoken = $result->return->_;
    print "AuthToken = $authtoken\n";

    # Now make the call with the AuthToken
    $testclient->__setCookie("Hi5AuthToken", $authtoken);
    $result = $testclient->auth(array("message"=>"I love Hi5"));
    print $result->return->message . "\n";

?>

Enter php filename.php to run this code.  You should see output like this:

I love hi5
Caught a problem with an auth method
AuthToken = Bunch of Garbled Encrypted Text
I love hi5

Let's walk through the code so we can understand it. 

The first thing we do is initialize a SOAP client service.  This is quite easy, all we need to do is pass in the wsdl file from the hi5 API site.  Next we try to call a method.  When we do this a SOAP request is sent to the server and results are returned.  Since SOAP understands exceptions we use this in a try/catch block.  In this case the call succeeds and we get back the text we passed in, "I love hi5" by from the message response.  Note that it's easy to pass a $result variable to the var_dump() method to find out how to get at the data you need.

In the next section, you'll see that we're calling the auth() method for $testclient.  Since we have not given any credentials, this will fail.  We can catch that easily with the try/catch block.

Next, we create $authclient for the AuthApiService.  This allows us to pass in our API key, a username and password.  The result is a hi5AuthToken.  Fill in these values as appropriate.  With a valid hi5AuthToken, we can try that auth() method again.  We pass that in by specifying in as a cookie value to send with the request.

And, that's it!  Simple and elegant access to hi5.  Try it out and let us know what you think.

(Note: At this point, the objects created by the PHP SOAP library are generic.  At some point we may gain this support in our Web services framework enunciate.)