sweetrdf / sparql-client
0.6.2
2023-09-01 15:26 UTC
Requires
- php: >=8.0
- guzzlehttp/guzzle: ^7.2
- halaxa/json-machine: ^1.1.3
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- sweetrdf/rdf-helpers: ^1.0.2
- sweetrdf/rdf-interface: ^1.0.0 | ^2.0.0-RC1
Requires (Dev)
- http-interop/http-factory-guzzle: ^1.0
- php-coveralls/php-coveralls: ^2.4
- phpstan/phpstan: *
- phpunit/phpunit: ^10
- sweetrdf/quick-rdf: ^1.0.0 | ^2.0.0-RC1
Suggests
This package is auto-updated.
Last update: 2024-10-30 01:48:25 UTC
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 troughexecute()
is allowed.- The only constraint is that all parameters have to be set.
- Parameters passed to
execute()
overwrite ones set withbindParam()
/bindValue()
.
- As strong typing is used parameter values have to be of type
rdfInterface\Term
.- It makes unnecessary specifying the type in
bindParam()
/bindvalue()
.
- It makes unnecessary specifying the type in
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.