README

A SPARQL client library for the rdfInterface ecosystem with the API inspired by the PDO.

It can work with any PSR-17 / PSR-18 compliant HTTP libraries.
It can work with huge query results.
The response is parsed in a lazy way as a stream (the next row is parsed only when you try to read it). This assures iterating through results without acumulating them in an array, which has neglectable memory footprint.

Installation

Obtain the Composer
Run composer require sweetrdf/sparql-client
Run composer require guzzlehttp/guzzle to install an HTTP client (but you can use any client supporting PSR-18).
Run composer require http-interop/http-factory-guzzle to install PSR-17 bindinds for Guzzle (but you can use any PSR-17 implementation)
Run composer require sweetrdf/quick-rdf to install RDF terms factory (you can use any terms factory compatible with the rdfInterface).

Automatically generated documentation

https://sweetrdf.github.io/sparqlClient/namespaces/sparqlclient.html

It's very incomplete but better than nothing.
RdfInterface documentation is included which provides documentation for terms (objects representing RDF named nodes, literals, etc.).

Usage

include 'vendor/autoload.php';
$connection = new \sparqlClient\StandardConnection('https://query.wikidata.org/sparql', new \quickRdf\DataFactory());
$results    = $connection->query('select * where {?a ?b ?c} limit 10');
foreach ($results as $i) {
    print_r($i);
}

Parameterized queries

The StandardConnection class provides a PDO-like API for parameterized queries (aka prepared statements). Parameterized queries:

Are the right way to assure all named nodes/blank nodes/literals/quads/etc. in the SPARQL query are properly escaped.
Protect against SPARQL injections.
Don't provide any speedup (in contrary to SQL parameterized queries).

include 'vendor/autoload.php';
$factory    = new \quickRdf\DataFactory();
$connection = new \sparqlClient\StandardConnection('https://query.wikidata.org/sparql', $factory);

// pass parameters using execute()
// the single `?` is a positional parameter while the `:sf` is a named parameter
$query      = $connection->prepare('SELECT * WHERE {?a ? ?c . ?a :sf ?d .} LIMIT 10');
$query->execute([
    $factory::namedNode('http://creativecommons.org/ns#license'),
    'sf' => $factory::namedNode('http://schema.org/softwareVersion'),
]);
foreach ($query as $i) {
    print_r($i);
}

// bind a (positional) parameter to a variable
$query = $connection->prepare('SELECT * WHERE {?a ? ?c .} LIMIT 2');
$value = $factory::namedNode('http://creativecommons.org/ns#license');
$query->bindParam(0, $value);
$query->execute();
foreach ($query as $i) {
    print_r($i);
}
$value = $factory::namedNode('http://schema.org/softwareVersion');
$query->execute();
foreach ($query as $i) {
    print_r($i);
}

There are some differences comparing to the PDO API:

Mixing positional and named parameters in one query is allowed (see the example above).
Mixing bindParam()/bindValue() and passing (some or all) parameters trough execute() is allowed.
- The only constraint is that all parameters have to be set.
- Parameters passed to execute() overwrite ones set with bindParam()/bindValue().
As strong typing is used parameter values have to be of type rdfInterface\Term.
- It makes unnecessary specifying the type in bindParam()/bindvalue().

Advanced usage

You may also provide any PSR-18 HTTP client and/or PSR-17 HTTP request factory to the \sparqlClient\StandardConnection constructor. E.g. let's assume your SPARQL endpoint requires authorization and you want to benefit from Guzzle connection allowing to set global request options:
```
$connection = new \sparqlClient\StandardConnection(
    'https://query.wikidata.org/sparql', 
    new \quickRdf\DataFactory(),
    new \GuzzleHttp\Client(['auth' => ['login', 'pswd']])
);
```
If your SPARQL endpoint doesn't follow the de facto standard of accepting the SPARQL query as the query request parameter, you may use the \sparqlClient\Connection class which takes PSR-7 requests instead of a query string and allows you to use any specific HTTP request you need.

FAQ

What about integration of INSERT/UPDATE/DELETE queries with the \rdfInterface\Dataset or \rdfInterface\QuadIterator?
Will be added in the future.

sweetrdf / sparql-client

Maintainers

Details