Skip to content

liblod-php_usage.md

Latest commit

 

History

History
230 lines (165 loc) · 5.67 KB

liblod-php_usage.md

File metadata and controls

230 lines (165 loc) · 5.67 KB

liblod usage

This document describes some common patterns for using res/liblod in a PHP project.

Full code samples can be found in the examples directory inside this project.

LOD: wrapper for an RDF graph

The main entrypoint to using bbcarchdev/liblod is through the LOD class.

use bbcarchdev\liblod\LOD;

$lod = new LOD();

The LOD is a wrapper for an RDF graph, enabling statements for individual resources to be fetched and queried.

Resolving URIs

You can resolve Linked Data URIs with:

$lodinstance = $lod->resolve('http://foo.bar/something');

or its equivalent abbreviation:

$lodinstance = $lod['http://foo.bar/something']

where http://foo.bar/something is the URI of some RDF resource. If the LOD object has already retrieved some data about this URI, that data is returned. If not, the URI is first fetched (via HTTP GET) and added to the LOD's index.

Finding resources

If a resource has already been fetched, you can locate it in the graph with:

$lod->locate('http://foo.bar/something');

This returns FALSE if there are no statements in the graph with the specified URI as a subject; else it returns a LODInstance containing all statements with that URI as a subject.

Fetching URIs

If you want to explicitly fetch a resource, you can do so with:

$lodinstance = $lod->fetch('http://foo.bar/something');

The $lodinstance returned is a LODInstance object, representing a single resource.

This can be useful where some data about a resource exists in the graph, but you want to fetch additional data and add it to that resource.

You can also fetch multiple resources in parallel into a LOD:

$lod->fetchAll(array(
  'http://foo.bar/something',
  'http://foo.bar/anothersomething',
  'http://foo.bar/yetanothersomething'
));

Note that this doesn't return the LODInstances generated by these fetches, but these are easy enough to retrieve with a $lod['<uri>'] call.

Set RDF prefixes

The LOD class includes a default list of prefixes which covers many of the common RDF vocabularies (see COMMON_PREFIXES in src/Rdf.php for the full list).

If you are going to be loading RDF which uses other prefixes, you can add these to the LOD with:

$lod->setPrefix('prefix', 'fullURI');

Load RDF

If you just want to use a LOD as a receptacle for RDF you've got via some other means (e.g. read in from a file), you can load it with the loadRdf() method; for example:

$rdf = <<<TURTLE
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix schema: <http://schema.org/> .

<http://foo.bar/something>
  dcterms:title "Bar" ;
  rdfs:label "Foo" ;
  schema:name "Baz" .
TURTLE;

$lod->loadRdf($rdf, 'text/turtle');

The second argument can be either text/turtle or application/rdf+xml.

Query resources

It can sometimes be useful to find resources which are owl:sameAs another resource. A LOD object can be queried for such resources as follows:

$lod->getSameAs('objectURI');

This will return all subject URIs where:

?subjectUri owl:sameAs ?objectURI

Note that if you want to find all other resources which are owl:sameAs a known subject, you can use the LODInstance class, as described below.

LODInstance: Working with resources

A $lodinstance represents a single resource, such that all of the statements it contains have the same subject URI. Typically, a LODInstance is generated by resolving a subject URI with a LOD object (see previous sections).

These statements can be queried in a few different ways.

Iterate all objects for statements with a specified predicate

foreach($lodinstance['rdfs:label'] as $labelObject)
{
    // $labelObject is a RESTerm, which may be a RESResource or RESLiteral;
    // you can test which with:
    if($labelObject->isResource())
    {
        // you can get a RESTerm's value with:
        echo $labelObject->value;

        // or convert it to a string implicitly with:
        echo "$labelObject";
    }
}

Note that this can also be used to find all resources which are owl:sameAs the LODInstance resource:

$sameAsObjects = $lodinstance['owl:sameAs'];

You can also specify multiple predicates; the object of the first statement which matches the predicate is returned:

/* RDF/Turtle
<http://foo.bar/something>
  dcterms:title "Bar" ;
  rdfs:label "Foo" ;
  schema:name "Baz" .
*/

foreach($lodinstance['rdfs:label,dcterms:title,schema:name'] as $labelObject)
{
    echo "$labelObject";
}

// => "Bar" (as the dcterms:title statement appears first in the RDF)

Find an object literal for a predicate with preferred language

If you specify an array of preferred languages on the LOD which originated the LODInstance, the first matching literal with the specified language will be returned:

/* RDF/Turtle
<http://foo.bar/fred>
  rdfs:label "Mr. Fred"@en-gb ;
  rdfs:label "Monsieur Fred"@fr-fr .
*/

$lod = new LOD();
$lod->languages = array('fr-fr', 'en-gb');

$lodinstance = $lod['http://foo.bar/fred'];
echo $lodinstance['rdfs:label'];

// => "Monsieur Fred"

Iterate all statements for a resource

Use the model property of a LODInstance to get an array of LODStatement objects representing all the statements in this graph:

/* RDF/Turtle
<http://foo.bar/fred>
  rdfs:label "Mr. Fred"@en-gb ;
  rdfs:label "Monsieur Fred"@fr-fr .
*/

foreach($lodinstance->model as $lodstatement)
{
  // outputs N-Triples style statement
  echo "$lodstatement\n .";
}

// =>
// <http://foo.bar/fred> <http://www.w3.org/2000/01/rdf-schema#label> "Mr. Fred"@en-gb .
// <http://foo.bar/fred> <http://www.w3.org/2000/01/rdf-schema#label> "Monsieur Fred"@fr-fr .