Now that you've written a basic Hello World application, let's tackle something a little more complicated. We'll build an application that enables users to request and provide suggestions on a topic, such as baby names, band names, etc.

In the Hello World application, you've already learned how to use the Ringside client in order to make API calls to the Ringside Social Application Server. In this trail, you will learn how to write a basic application in PHP that accesses its own MySQL database. From an API perspective, the only thing that is new here is how to query a user's friend list.

Setup

To get started, you can get the source code for this trail from one of three places:

1. In your Ringside installation, at [ringside]/apps/ringside/htdocs/trail_map_3

   At this time, the trail_map_3 found in the Ringside installer is not fully functional. Please get the source from one of the other two locations described below.

2. Download it here as either a tarball (for Linux/Mac) or a zip file (for Windows)
3. Build it yourself. This assumes you have the Ringside source checked out from SVN. Go to your working copy's /demo-apps directory and run the build by executing phing. The source for this trail will then be located here (relative to your SVN working copy): dist\demo-apps\stack\apps\ringside\htdocs\api\trail_map_3

To get the application running, follow the steps described in Trail #2, but this time, create a trail_map_3 application with the code from above. In the remainder of this trail, we will describe important segments of the code and how it works.

friends_get()

First, let's discuss the friends_get() call in index.php:

$friends = $ringsideClient->api_client->friends_get();
...
$utils = new SuggestionUtils();
$suggestions = $utils->getSuggestions( $userid, $friends );

This call utilizes the Ringside REST client to send a request to the Ringside Social Application Server to return a list of the current user's friends. This call returns an array of user IDs that uniquely identify each friend. This friends list is used later in the page to get the list of suggestions made on topics owned by that user or any of their friends.

The same type of code can be used to call most of the other Facebook API, friends_get() is just one example.

Connecting to a Database

SuggestionUtils is a utility class that handles database access for this simple application. The first method of importance to discuss is the one used to get a connection to the database:

public static function get_db_conn()
{
    $link = mysql_connect( Config::$db_ip, Config::$db_user, Config::$db_pass );
    $db = mysql_select_db( Config::$db_name, $link );
    if( $db ) {
        return $link;
    }
    return false;
}

This method relies on some configuration variables in order to connect to a MySQL database server and then select a database. For this to work, the configuration values passed into these methods must be set correctly. Therefore, in config.php, you will need to change the appropriate settings for your environment; as an example:

class Config
{
    public static $api_key = '6e148baf92a5992a5164ec57626ebb9f';
    public static $secret = 'ca4158353e84f1b789ccfb86ab7f93c4';
    // Configure Database
    public static $db_ip = 'localhost:3306';
    public static $db_name = 'ringside_demo';
    public static $db_user = 'root';
    public static $db_pass = 'root';
}

If you did not install Ringside with the Ringside installer (i.e. you are running out of your SVN working space), you'll have to change assignments of Config::$ringsideWeb and Config::$ringsideApi so they include "web/" and "api/" in their URLs as appropriate

index.php

Now that you've got the application configured and you understand how to get a connection to the database, take a closer look at index.php. This page displays a form which contains a pre-populated list of existing topics. That requires a function call to SuggestionUtils:

$utils = new SuggestionUtils();
$suggestions = $utils->getSuggestions( $userid, $friends );
$topics = array();
foreach( $suggestions as $suggestion ) {
    if( !in_array( array( $suggestion['owneruid'], $suggestion['topic'] ), $topics ) )
    {
        $topics[] = array( $suggestion['owneruid'], $suggestion['topic'] );
    }
}
// Only display options if there are existing topics in the user's social network
if( !empty( $topics ) ) {
?>
    <br />
    <div class="suggest_topic_label">Existing Topic:</div>
    <div class="suggest_topic_input">
    <select name="existingtopic">
        <option selected="true" value="none">-</option>
<?php
    foreach( $topics as $topic )
    {
        echo '<option value="' . $topic[0] . ':' . $topic[1] . '">' . $topic[1] . '</option>';
    }
?>
    </select>
    </div>
<?php
}
?>

Querying the database

The previous code segment made a call to getSuggestions(), extracted existing topics, and constructed the selection box in the form. The glue that makes this all work is the implementation of getSuggestions():

/**
 * Returns suggestions for topics from this user or their friends
 */
static public function getSuggestions( $uid, array $friends )
{
    if(!isset( $uid ) && !isset( $friends ))
    {
        print( "UID ($uid) and Friends($friends) must both be set!" );
        return;
    }

    $friends[] = $uid;
    $friends_list = implode( ',', $friends );

    $sql = "SELECT * FROM suggestions WHERE api_key ='".Config::$api_key."'";

    if(strlen($friends_list) > 0)
    {
        $sql .= " AND owneruid IN ($friends_list)";
    }

    $sql .= " ORDER BY topic, sid";

    error_log("executing sql: $sql");
    $suggestionsResults = mysql_query( $sql, SuggestionUtils::get_db_conn() )
                          or print( mysql_error() );
    $displaySuggestions = array();
    while( $row = mysql_fetch_assoc( $suggestionsResults ) )
    {
        $displaySuggestions[] = $row;
    }
    return $displaySuggestions;
}

This method returns the suggestions that are associated with topics owned by the user or their friends. It does so by constructing a SQL statement that performs a query, executing that statement, and constructing an array containing the results to be returned to the caller.

Inserting Data

The form on index.php posts to display.php, which conditionally adds suggestions (see the code segment below), and always displayes existing suggestions.

if( $utils->hasAddParams() ) {
    $result = $utils->suggestion_add( 
       ( $existingtopic == null)? $newtopic : $existingtopic, $_POST['suggestion'], $uid, $owneruid, Config::$api_key );
}

The suggestion_add() function is very simple; it constructs a SQL INSERT statement and executes it, returning the result:

function suggestion_add( $topic, $suggestion, $uid, $owneruid, $api_key ) {
    $sql = 'INSERT INTO suggestions SET topic=\'' . $topic .
 '\', uid=' . $uid . ', suggestion=\'' . $suggestion .
 '\', api_key=\'' . $api_key . '\', `owneruid` = \'' . $owneruid . '\'';
    return mysql_query( $sql, $this->get_db_conn() ) or print( mysql_error() );
}