sweetrdf / rdfinterface2easyrdf
Provides methods to convert between EasyRdf and rdfInterface objects.
0.3.1
2024-04-09 18:12 UTC
Requires
- php: >=8.0
- sweetrdf/rdf-helpers: ^2.0.0
- sweetrdf/rdf-interface: ^2.0.0-RC1
Requires (Dev)
- php-coveralls/php-coveralls: ^2.4
- phpstan/phpstan: *
- phpunit/phpunit: ^9.5
- sweetrdf/easyrdf: ^1.4
- sweetrdf/quick-rdf: ^2.0.0-RC1
Suggests
- sweetrdf/easyrdf: ^1.4
- sweetrdf/quick-rdf: ^2.0.0-RC1
This package is auto-updated.
Last update: 2024-10-10 06:53:03 UTC
README
A library providing methods for converting between EasyRdf (original library, still maintained fork) and rdfInterface objects (in both directions).
Helpful especially when you have too much EasyRdf code to port it but you would like to develop new code using the rdfInterface ecosystem.
Installation
- Obtain the Composer
- Run
composer require sweetrdf/rdfInterface2easyRdf
- Install EasyRdf implementation of your choice, e.g.
composer require sweetrdf/easyrdf
. - Install rdfInterface implementation of your choice, e.g.
composer require sweetrdf/quick-rdf
.
Usage
rdfInterface to EasyRdf
Conversion in this direction is straightforward:
- If you don't care about strong result type checks, just use the
rdfInterface2easyRdf\AsEasyRdf::asEasyRdf()
method, e.g.:# let's prepare all kind of rdfInterface objects $blank = quickRdf\DataFactory::blankNode(); $named = quickRdf\DataFactory::namedNode('http://foo'); $literal = quickRdf\DataFactory::literal('bar', 'en'); $quad = quickRdf\DataFactory::quad($blank, $named, $literal); $dataset = new quickRdf\Dataset(); $dataset->add($quad); $node = $dataset->withTerm($named); print_r(rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($blank)); print_r(rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($named)); print_r(rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($literal)); echo rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($quad)->getGraph()->dump('text'); echo rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($node)->getGraph()->dump('text'); echo rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($dataset)->dump('text');
- If you want converted data to be appended to an already existing graph, pass it as a second parameter, e.g.
(continuing the code from the previous example):
$graph = new EasyRdf\Graph(); $graph->resource('http://baz')->addLiteral('https://foo', 'other value'); rdfInterface2easyRdf\AsEasyRdf::AsEasyRdf($quad, $graph); echo $graph->dump('text');
- If you want converted data to be appended to an already existing graph, pass it as a second parameter, e.g.
(continuing the code from the previous example):
- If you care about stictly defined return data types, use
rdfInterface2easyRdf\AsEasyRdf::asLiteral()
,rdfInterface2easyRdf\AsEasyRdf::asResource()
andrdfInterface2easyRdf\AsEasyRdf::asGraph()
.- Each of them accepts only compatible input types, e.g.
rdfInterface2easyRdf\AsEasyRdf::asLiteral()
accepts onlyrdfInterface\LiteralInterface
rdfInterface\NodeInterface
is accepted both byrdfInterface2easyRdf\AsEasyRdf::asResource()
andrdfInterface2easyRdf\AsEasyRdf::asGraph()
- An
EasyRdf\Graph
can be passed as an optional second parameter just as withrdfInterface2easyRdf\AsEasyRdf::AsEasyRdf()
(see the example above)
- Each of them accepts only compatible input types, e.g.
EasyRdf to rdfInterface
Conversion in this direction might get tricky. Important remarks:
- As the rdfInterface defines only an interface but no actual implementation,
you must always pass an RDF terms factory object (the
$dataFactory
parameter). - As the rdfInterface doesn't define a standardized way to create datasets
(
rdfInterface\DatasetInterface
) and dataset nodes (rdfInterface\DatasetNodeInterface
) theasRdfInterface()
method returns anrdfInterface\QuadIteratorInterface
which is a triples iterator. The only way to convert anEasyRdf\Resource
orEasyRdf\Graph
to a dataset or dataset node is to add triples from the EasyRdf object to an existingrdfInterface\DatasetInterface
orrdfInterface\DatasetNodeInterface
. Theadd()
,addDataset()
andaddDatasetNode()
methods can be used for that (see examples below). - There's an ambiguity around the
EasyRdf\Resource
conversion. You may want convert it to an RDF term (rdfInterface\BlankNode
orrdfInterface\NamedNode
) or you may want to convert it to a set of triples (quad iterator, dataset or dataset node).- The
asRdfInterface()
method converts to an RDF term if theEasyRdf\Resource
object has no properties (no triples) and to ardfInterface\QuadIteratorInterface
otherwise. - Use
asTerm()
,asQuadIterator()
,add()
,addDataset()
oraddDatasetNode()
to enforce a more specific behavior.
- The
A sample EasyRdf graph and terms factory used in examples below:
$graph = new EasyRdf\Graph(); $blank = $graph->resource('_:blank'); $res1 = $graph->resource('http://foo'); $res2 = $graph->resource('http://baz'); $res1->add('http://resource', $res2); $lit1 = new EasyRdf\Literal('literal', 'en'); $lit2 = new EasyRdf\Literal(1, null, 'http://www.w3.org/2001/XMLSchema#integer'); $res1->addLiteral('http://langLiteral', $lit1); $res1->addLiteral('http://intLiteral', $lit2); $res3 = $graph->resource('http://marry'); $res3->addLiteral('http://langLiteral', $lit1); $df = new quickRdf\DataFactory();
- Use
asRdfInterface()
to guess the output type based on the input.print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($blank, $df)); # as $res2 contains no properties, it's converted to a named node print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($res2, $df)); print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($lit1, $df)); print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($lit2, $df)); # as $res1 contains properties, it's converted to a quad iterator print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($res1, $df)); foreach (rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($res1, $df) as $i) { print_r($i); } # EasyRdf\Graph is also converted to a quad iterator print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($graph, $df)); foreach (rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($graph, $df) as $i) { print_r($i); }
- Use
asTerm()
to enforce conversion of anEasyRdf\Resource
to a term:print_r(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($res1, $df)); print_r(rdfInterface2easyRdf\AsRdfInterface::asTerm($res1, $df));
- There are two ways of converting an
EasyRdf\Graph
andEasyRdf\Resource
to a dataset:echo $graph->dump('text'); # using quad iterator returned by the asRdfInterface() $dataset = new quickRdf\Dataset(); $dataset->add(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($graph, $df)); echo $dataset; # using add()/addDataset() method # (addDataset() works the same, just has strictly defined return type) $dataset = rdfInterface2easyRdf\AsRdfInterface::add($graph, $df, new quickRdf\Dataset()); echo $dataset; # similarly for an EasyRdf\Resource # (just only given resource triples are converted) $dataset = new quickRdf\Dataset(); $dataset->add(rdfInterface2easyRdf\AsRdfInterface::asRdfInterface($res1, $df)); echo $dataset; $dataset = rdfInterface2easyRdf\AsRdfInterface::add($res1, $df, new quickRdf\Dataset()); echo $dataset; # using add()/addDataset() we can also enforce # a whole graph to be converted based on an EasyRdf\Resource $dataset = rdfInterface2easyRdf\AsRdfInterface::add($res1, $df, new quickRdf\Dataset(), true); echo $dataset;
- Conversion of an
EasyRdf\Resource
to a dataset node is relatively most complex:echo $graph->dump('text'); $emptyDatasetNode = new rdfHelpers\DatasetNode(new quickRdf\Dataset(), $df::blankNode()); $datasetNode = rdfInterface2easyRdf\AsRdfInterface::add($res1, $df, $emptyDatasetNode); print_r($datasetNode->getNode()); # the dataset attached to the dataset node contains all triples echo $datasetNode->getDataset(); # but the dataset node itself returns only triples of the converted EasyRdf\Resource foreach($datasetNode as $i) { echo "$i\n"; } # conversion could be limited to EasyRdf\Resource triples only using the $wholeGraph parameter $emptyDatasetNode = new rdfHelpers\DatasetNode(new quickRdf\Dataset(), $df::blankNode()); $datasetNode = rdfInterface2easyRdf\AsRdfInterface::add($res1, $df, $emptyDatasetNode, false); print_r($datasetNode->getNode()); # the dataset attached to the dataset node contains all triples echo $datasetNode->getDataset(); # addDatasetNode() works in the same way, just has narrower return type $emptyDatasetNode = new rdfHelpers\DatasetNode(new quickRdf\Dataset(), $df::blankNode()); $datasetNode = rdfInterface2easyRdf\AsRdfInterface::addDatasetNode($res1, $df, $emptyDatasetNode); print_r($datasetNode->getNode()); echo $datasetNode->getDataset();
- In case of
add()
,addDataset()
andaddDatasetNode()
the parameter used to pass a dataset/dataset node accepts also a callable, e.g.$dataset = rdfInterface2easyRdf\AsRdfInterface::addDataset($res1, $df, fn() => new quickRdf\Dataset()); $datasetNode = rdfInterface2easyRdf\AsRdfInterface::addDatasetNode( $res1, $df, fn($x) => new rdfHelpers\DatasetNode(new quickRdf\Dataset(), $x) );