This is a synchronous library, just like Java. Bear in mind that the TourismClient stub uses the $_SESSION var to determine if it should fetch the resources from a CitySDK-enabled server or just to load them from it. You may download the project file here, build the framework and include it in your projects.

Documentation

The documentation of the PHP library can be found here.

Examples

The PHP library resides in two main classes: TourismClient stub and the DataReader.

Creating and using the TourismClient Stub

To generate a TourismClient stub, simply create a new object and pass the home URL. If the URL is a CitySDK-powered tourism server then a TourismClient stub is generated. Such URL is visited only once and further creations with the same URL will just generate another (equal) stub without calling the URL again (these are loaded from the $_SESSION var). If a different URL is passed then the mentioned procedure is repeated. Since the $_SESSION var is used, remember to create such stub before outputting any result to the client. An example of creating a TourismClient stub is shown below:

require_once 'phar://citysdk-tourism.phar/TourismClient.php';
 
private function getClientWithUrl($url) {
    $client = null;
 
    try {
        // create the object by passing it the url
        $client = new TourismClient($url);
    } catch(Exception $e) {
        // return false in case of error
        // (in this case the URL is not a valid CitySDK Tourism server)
        return false;
    }
 
    return $client
}
 
$this->getClientWithUrl('http://some-uri.com');

Using the TourismClient stub

The TourismClient stub allows to call and instantiate the POI objects (like POIs, Events, Routes, Categories and Tags) and its listings. Some examples are shown below:

Getting List of POI-based Objects

A list of POI-based objects is requested through the use of a parameter list which contains the query parameters to make a given request. An example of getting a list of POIs is shown below:

require_once 'phar://citysdk-tourism.phar/TourismClient.php';
 
private function getListEvents($params, $url) {
    $events = null;
 
    try {
        // create the object by passing it the url
        $client = new TourismClient($url);
        // set it to use version 1.0
        $client->useVersion('1.0')
 
        // get the list of events
        $events = $client->getEvents($params);
    } catch(Exception $e) {
        // return false in case of error
        return false;
    }
 
    return $events
}
 
// build the params
$category = array("Music", "Notícias", "Stuff from Stuff");
$params = array(
    "category" => $category,
    "tag" => "rock"
);
 
// and invoke the events
$this->getListEvents($params, 'http://some-uri.com');

Getting a List of Categories or Tags

A list of Categories can be requested by specifying which list is needed (POIs, Events or Routes). Getting a list of Tags will be similar.
An example is shown below:

require_once 'phar://citysdk-tourism.phar/TourismClient.php';
 
private function getCategories($params, $url) {
    $categories = null;
 
    try {
        // create the object by passing it the url
        $client = new TourismClient($url);
        // set it to use version 1.0
        $client->useVersion('1.0')
 
        // get the list of categories
        $categories = $client->getCategories($params);
    } catch(Exception $e) {
        // return false in case of error
        return false;
    }
 
    return $categories
}
 
$params = array(
    "list" => 'poi',
);
$this->getCategories($params, 'http://some-uri.com');

Getting a Single POI-based Object

Getting a single POI-based object (like POIs, Events or Routes) can be made by using the base and the id of such object like shown below:

require_once 'phar://citysdk-tourism.phar/TourismClient.php';
 
private function testPoiWithId($params, $url) {
    $poi = null;
    try {
        // create the object by passing it the url
        $client = new TourismClient($url);
        // set it to use version 1.0
        $client->useVersion('1.0')
 
        // get the list of pois
        $pois = $client->getPois($params);
        // and then the single poi
        $poi = $this->client->getPoi($pois[0]['base'], $pois[0]['id']);
    } catch(Exception $e) {
        // return false in case of error
        return false;
    }
 
    return $poi;
}
 
$category = array('Museum', 'Garden');
$params = array(
    'category' => $category,
    'tag' => 'culture'
);
$this->testPoiWithId($params, 'http://some-uri.com');

Using the DataReader on returned data

The DataReader is used to parse the objects returned by the methods of TourismClient stub. This class allows to parse any type of SINGLE POI-based object and return the desired value. Some examples are shown next.

private function readData() {
    // prepare the parameter list
    $category = array('Music', 'Live');
    $tag = array('rock', 'indie');
    $params = array(
        'category' => $category,
        'tag' => $tag
    );
         
    // get a list of events
    $events = $this->client->getEvents($params);
    $lang = 'pt_PT';
 
    // and print its content
    foreach($events['event'] as $event) {
         $label = DataReader::getLabel($event, 'primary', $lang);
        $description = DataReader::getDescription($event, $lang);
        $img = DataReader::getThumbnails($event);
        $imgContent = null;
        $thumbnail = null;
        if(count($img) > 0) {
            $imgContent = $img[0];
            $thumbnail = $imgContent->content;
        }
                     
        print $label;
        print $description;
        print $imgContent;
    }
}
 
$this->readData();