RDF API for PHP

Using the SPARQL client

This turorial is part of the RAP - Rdf API for PHP documentation.


Tobias Gauss <tobias.gauss@web.de>
June 2006


RAP's SPARQL client provides the functionality to execute a SPARQL query against a SPARQL server and retrieve the result as an array which contains the variables an their bindings.

Usage

First of all create a new SparqlClient object:

$client = ModelFactory::getSparqlClient("http://www.exampleSparqlService.net:2020/example");

This line creates a new SparqlClient object $client which is linked with the SPARQL Service http://www.exampleSparqlService.net:2020/example.

Then create a ClientQuery object:

$query = new ClientQuery();

The ClientQuery object provides three methods:

$query->addDefaultGraph($default);

To add a Default Graph name to the ClientQuery object,

$query->addNamedGraph($named);

To add a Named Graph name to the ClientQuery object. And

$query->query($queryString);

to add a query string to the ClientQuery object.

Now You can execute the query by calling the method query($query):

$result = $client->query($query);

Now the query is executed and result ist returned. The result format is either a MemModel if the query is a CONSTRUCT query or an array which contains the variables and their bindings. You can also change the result format to SPARQL Query Results XML Format by calling the method:

$client->setOutputFormat("xml");

Example

To clearify the usage here is a simple example. We start with including the RAP package and creating a SPARQL client linked to a SPARQL service:

// Include all RAP classes
define("RDFAPI_INCLUDE_DIR", "C:/Apache/htdocs/rdfapi-php/api/");
include(RDFAPI_INCLUDE_DIR . "RdfAPI.php");

// Create a new MemModel and load the document

$client = ModelFactory::getSparqlClient("http://www.exampleSparqlService.net:2020/example");

Once the client has been created, we can perform our first query which will be: "Find the full name of all employees". So, we create a variable $querystring and assign the corresponding query string:

$querystring = '
PREFIX vcard <http://www.w3.org/2001/vcard-rdf/3.0#>
SELECT ?fullName
WHERE { ?x vcard:FN ?fullName }';

To execute the query, we create a new ClientQuery object:

$query = new ClientQuery();
$query->query($querystring);
$result = $client->query($query);

The result of the query is an two dimension array of variable bindings ($result[]['?varname'] ). The values of these variables are RAP objects (Resource, Literal or BlankNode) or an empty string if the variable is unbound . The following code loops over the result set and prints out all bindings of the variable ?fullName.

foreach($result as $line){
  $value = $line['?fullName'];
    if($value != "")
      echo $value->toString()."<br>";
    else
      echo "undbound<br>";
}

Another, even more convenient way to display the results of a query is to use the writeQueryResultAsHtmlTable() method of the SPARQL engine. All we have to do is to pass the query result to this method:

SPARQLEngine::writeQueryResultAsHtmlTable($result);

Which will result in the following output in the browser window:

No. ?fullName
1.

Literal: Bill Parker

2.

Literal: George Simpson

3.

Literal: Monica Murphy

If we want the engine to return the query result in SPARQL Query Results XML Format, we have to add 'xml' as second parameter to the function call:

$client->setOutputFormat("xml");
$result = $client->query($query);

Now the variable $result2 contains a string which represents the results in SPARQL Query Results XML Format:

<?xml version="1.0"?>
<sparql xmlns="http://www.w3.org/2005/sparql-results#">
<head>
<variable name="fullName"/>
</head>
<results ordered="false" distinct="false">
<result>
<binding name="fullName">
<literal>Bill Parker</literal>
</binding>
</result>
<result>
<binding name="fullName">
<literal>George Simpson</literal>
</binding>
</result>
<result><binding name="fullName">
<literal>Monica Murphy</literal>
</binding>
</result>
</results>
</sparql>

The result of an ASK query is a boolean value.

The result of a CONSTRUCT query is a MemModel:

$querystring = '
PREFIX vcard <http://www.w3.org/2001/vcard-rdf/3.0#>
PREFIX rdf <http://www.w3.org/1999/02/22-rdf-syntax-ns#>


CONSTRUCT { ?x vcard:FN ?fullName}
WHERE { ?x vcard:FN ?fullName }';

$result = $employees->sparqlQuery($querystring);

$result->writeAsHtmlTable();

For more SPARQL query examples please refer to the W3C SPARQL Working Draft.