Getting started with ARC2

ARC2 is a complete rewrite of ARC1. We tried to incorporate all the feedback we received, especially requests by people used to PHP frameworks, and new to RDF. Here we go:

Setup (via composer)

It is recommended to setup ARC2 using composer.

require 'vendor/autoload.php';

Setup (classic way)

ARC2 introduces a static class which is all that needs to be included. Any other component can then be loaded via ARC2, without the need to know the exact path to the class file.

include_once("path/to/arc/ARC2.php");

Be warned though that this method might have issues loading certain classes (See e.g. this issue). If you run into such problems, use the composer-based method above instead.

Accessing and using ARC components

Once the static ARC2 class is made available, you can load the components with simple method calls and start using them:

$parser = ARC2::getRDFParser();
$parser->parse('http://example.com/foaf.ttl');
$triples = $parser->getTriples();

Requirements

ARC2 requires the XML PHP extension.

Some components need a MySQL database (for example the RDF store and the SPARQL engine). The database has to be set up in advance, but ARC will auto-create the necessary tables. A single DB can be used for multiple ARC stores, you can provide a custom name for each store which is then used as a table prefix.

Configuration options

Configuration options can be provided during any class instantiation. Dynamically loaded sub-components will inherit their caller's configuration. This allows you to specify certain settings once, without having to worry about them later:

$config = array(
  /* db */
  'db_host' => '127.0.0.1', /* default: localhost */
  'db_name' => 'my_db',
  'db_user' => 'user',
  'db_pwd' => 'secret',
  /* store */
  'store_name' => 'arc_tests',
  /* network */
  'proxy_host' => '192.168.1.1',
  'proxy_port' => 8080,
  /* parsers */
  'bnode_prefix' => 'bn',
  /* sem html extraction */
  'sem_html_formats' => 'rdfa microformats',
);
$store = ARC2::getStore($config);
// since version 2.3+
$store->createDBCon();
$store->setup();

Error collection

Similar to the configuration settings that are passed to sub-components, any processing error that occurs will be logged and forwarded to the calling component:

$rs = $store->query('...');
if ($errs = $store->getErrors()) {
  /* $errs contains errors from the store and any called 
     sub-component such as the query processor, parsers, or
     the web reader */
  ...
}

Sometimes, the error log can grow quite large which can cause memory issues. ARC lets you set the maximum number of errors before it stops proceeding via the "max_errors" configuration option (see example below, default is 25).

A complete example

Detailed component descriptions are available in the other documentation sections. Here is a quick example that hopefully illustrates how ARC2 works:

include_once("path/to/arc/ARC2.php");

$config = array(
  /* db */
  'db_name' => 'my_db',
  'db_user' => 'user',
  'db_pwd' => 'secret',
  /* store */
  'store_name' => 'arc_tests',
  /* stop after 100 errors */
  'max_errors' => 100,
);
$store = ARC2::getStore($config);
// since version 2.3+
$store->createDBCon();

if (!$store->isSetUp()) {
  $store->setUp();
}

/* LOAD will call the Web reader, which will call the
format detector, which in turn triggers the inclusion of an
appropriate parser, etc. until the triples end up in the store. */
$store->query('LOAD <http://example.com/home.html>');

/* list names */
$q = '
  PREFIX foaf: <http://xmlns.com/foaf/0.1/> .
  SELECT ?person ?name WHERE {
    ?person a foaf:Person ; foaf:name ?name .
  }
';
$r = '';
if ($rows = $store->query($q, 'rows')) {
  foreach ($rows as $row) {
    $r .= '<li>' . $row['name'] . '</li>';
  }
}

echo $r ? '<ul>' . $r . '</ul>' : 'no named persons found';