Phesame: PHP5-Sesame interface

Introduction

Phesame is a php class for querying the sesame db. As at the time of writing the java integration has been removed from php5, we wrote this small library to query sesame via http.

Requirements

Sesame running in a servlet container
PEAR
PEAR HTTP_Request

Features

performs select Queries
performs data uploads
works on multiple repositories
clear repository

Limitations

Not tested for "construct queries"
Only XML currently accepted as query result format
One repository at a time
Only SeRQL supported as query language

Support

Please reports bugs and suggestions to:
Michele Barbera <barbera 'AT' netseven.it>
or
Riccardo Giomi <giomi 'AT' netseven.it>

Manual

The class is very easy to use. There are comments in the source code explaining how to use it.
Someday I'll write a short tutorial :-) In the meantime, if you have problems, feel free to drop us an email!

Download

phesame_phesameExt.tar.gz

Phesame Extensions

PhesameExt

Phesame was originally written for a project we are working on ( www.hjournal.org ). While using the class in the project, Riccardo noticed that writing queries in XML is a bit tedious and created a small "query parser" to be able to write simple queries in a "php array format". Feel free to experiment if you like it.

PhesameExt Tutorial

The PhesameExt class contains some useful utilities for Phesame. Its methods were used to build application specific methods to execute
particular queries.

The main feature of the class is the buildSeRQLQueryAndReturnArray method:

It accepts Sesame queries in a compact array format which is clearer and easier to write, once the general concept has been understood. This method creates only "select" queries, it cannot execute updates of any type, and I can't guarantee it will work for any kind of query.

To see what the method do, you can set the $showSeRQL parameter to true, and the method will print the resulting query on screen.

Let's see some examples:

select siglum
from {siglum}<rdf:type>{hj:Contribution}
using namespace hj = <!http://www.hjournal.org/hjournal#>

the array format for the query divides a query in three main arrays: $destinations, $paths and $values.

$destinations indicates the values "we want to arrive to" which is, the select clause parameters. In the $paths array we indicate "how we arrive", which is the chain of triples in the from clause. We'll see the $values array shortly.

So, we want to arrive to siglum by passing through the {siglum}<rdf:type>{hj:Contribution} triple:

$destinations = array ( 'siglum' => 'siglum' );
$paths        = array ( 'siglum' => array ( 'rdf:type' => 'hj:Contribution' ) );

The $end parameter contains a string which is appended to the end of the query. We'll use it to add the namespace:

$end = "using namespace hj = <!http://www.hjournal.org/hjournal#>";

The result of the method call is an array like this:

Array
(
    [0] => Array
        (
            [siglum] => siglum-1
        )

    [1] => Array
        (
            [siglum] => siglum-2
        )
)

By using the ofResultsReturnJust method with $key='siglum':

Array
(
    [0] => siglum-1
    [1] => siglum-2
)

It is possible to use placeholders inside queries. A place holder is a '%' symbol followed by an identifier, like %x. If in the $values array is present an entry 'x', then in the final query the identifier is substituted with the entry's value:

select location
from {hj:x}<hj:location>{location}
using namespace hj = <!http://www.hjournal.org/hjournal#>

We want x to be a variable:

$destinations = array ( 'hj:%siglum' => array ( 'hj:location' => 'location' ) );
$paths = array ();
$values = array ( 'siglum' => $siglum );

the value of the php variable $siglum, after being properly encoded, is substituted into the query instead of %siglum.

We also use a special placeholder, '%' followed by a digit (the digit itself has no meaning). Any such placeholder is substituted by nothing, and is useful to indicate empty nodes in the query or avoid problems in the arrays with entries with the same name.

The $where parameter accepts strings which are used to build the where clause of the query.

A last example:

select siglum,title,abstract,language,contributor,editor,pubyear,location

from {siglum}<rdf:type>{hj:ExternalContribution};
             <hj:authorIs>{hj:<x>},{siglum}<hj:title>{title};
                                         <hj:abstract>{abstract};
                                         <hj:language>{language};
                                         <hj:contributor>{contributor};
                                         <hj:editor>{editor};
                                         <hj:pubyear>{pubyear};
                                         <hj:location>{location}

where <x> is variable.

using namespace hj = <!http://www.hjournal.org/hjournal#>

Note that, of he from clause, the first part is used to arrive to siglum, while the rest identifies an interval of "nodes" around siglum to consider in the select clause. Note also the presence of the ';' separator.

the 'siglumData' identifier is not used, it is needed to build the 'siglumData' => 'siglum' form, which indicates that 'siglum' must be part of the select clause.

$destinations = array(
                      'siglumData' => 'siglum',
                      'siglum' => array (
                                         'hj:title'       => 'title',
                                         'hj:abstract'    => 'abstract',
                                         'hj:language'    => 'language',
                                         'hj:contributor' => 'contributor',
                                         'hj:editor'      => 'editor',
                                         'hj:pubyear'     => 'pubyear',
                                         'hj:location'    => 'location'
                                        )
                     );

$paths = array(
               'siglum' => array (
                                  'rdf:type'    => 'hj:ExternalContribution',
                                  'hj:authorIs' => 'hj:%x'
                                 )
              );

$values = array ( 'x' => $x );