Rdf Interface Laravel Package

There are some corner cases (e.g. parsing reference test outputs for the RDF-XML parser) where it is required to preserve blank node identifiers from the input data source. In such a case the rdfInterface\ParserInterface::BLANK_NODES_PRESERVE should be passed as the $baseUri parameter to the rdfInterface\ParserInterface::parse()/rdfInterface\ParserInterface::parseStream().

To properly parse blank nodes the parser has to be aware of the URI of the document being parsed. So far there was no way to provide this information. Not the rdfInterface\ParserInterface::parse() and rdfInterface\ParserInterface::parseStream() take optional second parameter string $baseUri allowing to specify the document URI.

See also https://github.com/sweetrdf/quickRdfIo/issues/11

rdfInterface\DatesetInterface::getPredicate() and rdfInterface\DatesetNodeInterface::getPredicate() return type narrowed down to rdfInterface\NamedNodeInterface|null.

While technically this is a backward-incompatible change and thus marks major version bump, there is no known RDF extension nor implementation which would depend on the getPredicate() method returning anything else than NamedNodeIterface|null.

rdfInterface\DatasetInterface::delete($filter) now accepts null as a $filter. Also, null is now a default $filter parameter value.

Backward-incompatible changes

• rdfInterface\DatasetCompareInterface, rdfInterface\DatasetMapReduceInterface and rdfInterface\DatasetQuadPartsInterface merged into rdfInterface\DatasetInterface.
• rdfInterface\DatasetInterface
  • copyExcept($filter) does not accept null as the $filter. If you want to copy all quads, use the copy() method.
  • delete($filter) does not accept null as the $filter. If you want an empty dataset, just create a new one.
  • offsetExists($offset), offsetGet($offset), offsetSet($offset, $value) and offsetUnset($offset) method now must throw a newly introduced rdfInterface\MultipleQuadsMatchedException if the offset matches multiple quads.

New features

• rdfInterface\DatasetNodeInterface interface added for a node-oriented RDF graph operations. It extends the rdfInterface\DatasetInterface, just methods are (generally) applied only to quads with a subject matching a given rdfInterface\TermInterface term.
• rdfInterface\TermIteratorInterface extended
  • contains(rdfInterface\TermCompareInterface $term): bool method added allowing to perform in_array-like check.
  • getValues(): array<string> method added.
  • intersect($terms): rdfInterface\TermIteratorInterface method added.
  • skip($terms): rdfInterface\TermIteratorInterface method added.
• rdfInterface\DatasetNode
  • Static method factory() added as a replacement for the rdfInterface\DatasetNode::__construct(). This follows the convention not to enforce constructor signatures.
  • Getter shorthands added (a reference implementation is provided by the rdfHelpers\DatasetGettersTrait class of the sweetrdf/rdf-helpers package):
    • getSubject(), getPredicate(), getObject(), getGraph() returning an rdfInterface\TermInterface | null
    • getSubjectValue(), getPredicateValue(), getObjectValue(), getGraphValue() returning mixed | null
• rdfInterface\QuadNoSubjectInterface added for convenient adding quads to the rdfInterface\DatasetNode.
• rdfInterface\DataFactory
  • quadNoSubject($predicate, $object, $graph): rdfInterface\QuadNoSubjectInterface method added.
• rdfInterface\MultipleQuadsMatchedException exception added to make it possible to easily distinguish between standard PHP array access errors (the \UnexpectedValueException when an offset does not exist) and rdfInterface-specific "multiple quads matched" error.
• rdfInterface\QuadInterface::getValue() must throw the \BadMethodCall exception.

Relaxed definitions

• rdfInterface\BlankNodeInterface, rdfInterface\NamedNodeInterface, rdfInterface\LiteralInterface and rdfInterface\QuadInterface constructor definition dropped. These constructors are anyway not meant to be called directly as terms should be instantiated trough the rdfInterface\DataFactoryInterface class so it makes no sense to enforce their signatures.
• rdfInterface\DatasetNode:
  • __construct() method dropped. This follows the convention not to enforce constructor signatures. A static factory() method signature is defined instead.
  • add() accepts QuadInterface|\Traversable<rdfInterface\QuadInterface>|array<rdfInterface\QuadInterface> (instead of rdfInterface\QuadInterface|rdfInterface\QuadIteratorInterface|rdfInterface\QuadIteratorAggregateInterface).
  • forEach($filter) accepts null as a $filter.
• rdfInterface\SerializerInterface
  • serialize() and serializeStream() accept \Traversable<QuadInterface>|array<QuadInterface> (instead of rdfInterface\QuadIteratorInterface|rdfInterface\QuadIteratorAggregateInterface).

Minor changes

• rdfInterface\TermInterface now extends rdfInterface\TermCompareInterface instead of defining equals() and __toString() methods explicitly.
• rdfInterface\TermCompareInterface, rdfInterface\QuadCompareInterface and rdfInterface\DatasetInterface extend Stringable instead of declaring __toString() explicitly.
• rdfInterface\QuadCompareInterface methods: getSubject(), getPredicate(), getObject() and getGraph() return type is rdfInterface\TermCompareInterface | null (instead of rdfInterface\TermInterface | rdfInterface\TermCompareInterface | null).

Allow both psr/http-message ^1 and ^2

Backward-incompatible changes

• All interfaces have been renamed so that their name ends with Interface to follow an interface naming convention which is predominant in modern PHP.
• rdfInterface\DatasetInterface extends rdfInterface\QuadIteratorAggregateInterface (a strongly-typed IteratorAggregate with an optional filtering) instad of rdfInterface\QuadIteratorInterface (a strongly-typed Iterator) which laregely decouples implementation of the iterator from the dataset implementation.

New features

• Allowing rdfInterface\Dataset::getOffset(0) and rdfInterface\Dataset::offsetExists(0) as a syntax for getting any quad out of a dataset and checking if a dataset is not empty. This allows the $dataset[0] ?? $defaultQuad syntax for safely getting a single quad out of a dataset.
• rdfInterface\QuadIteratorAggregateInterface added.

It's worth noting rdfInterface\DatasetListQuadParts methods now return rdfInterface\TermIterator.

• rdfInterface\Dataset::map(), rdfInterface\Dataset::reduce() and rdfInterface\Dataset::forEach() take optional QuadCompare | QuadIterator | callable $filter = null parameter. As exactly the same filter parameter is already a part of many other dataset method signature it shouldn't make dataset implementation harder and it allows user to prepare much simple callbacks when quads filtering is needed.
• rdfInterface\DatasetCompare::every() signature is now the same as all other rdfInterface\DatasetCompare method signatures.
• rdfInterface\DatasetMapReduce::map() returns an instance of rdfInterface\DatasetMapReduce now.
• rdfInterface\DatasetListQuadParts interface added allowing simple ordered dataset traversal.

• QuadIterator::current() and Dataset::current() allowed to return null making it possible to use constructs like $dataset->copy(filterMatchingUnknownNumberOfQuads)->current() ?? $defaultValue to get any quad in the dataset (coupled with the ?? for handling an empty dataset scenario when needed). Specification now explicitely requires Dataset::current() to return null for empty dataset and a quad on non-empty dataset which hasn't been traversed with the \Iterable interface yet.
• TermCompare and QuadCompare extends TermCompare interfaces replaced the QuadTemplate interface. This allows flexible implementation of "term template" (especially "quad template") classes as the only thing the rdfInterface enforces on them is to implement equals() and __toString() for term template classes and subject/predicate/object/graph getters for quad template classes. Constructor is no longer enforced (as it was with the QuadTemplate). As a consequence of this change:
  • DataFactory::quadTemplate() method has been dropped.
  • All Dataset methods used to accept QuadTemplate now accept QuadCompare.
  • NamedNode, BlankNode and DefaultGraph interfaces extend TermCompare now.
  • Quad interface extends QuadCompare now.
• In-code documentation describing expected implementations behavior greatly extended for Literal and Dataset.
  • The Literal constructor is now required to automatically assign a datatype if a value is bool/int/float and the datatype hasn't been specified. This allows to keep the original PHP type of the value by Literal::getValue() (if an implementation supports such a behavior) while avoiding the problem of having many instances of literals which are equal to each other according to the RDF specification.
• Compliance tests extracted to a separate repository (and composer package).

Yet another approach to the \rdfInterface\Literal. Still shouldn't be considered stable.

This affects rdfInterface\DefaultGraph, rdfInterface\Quad, rdfInterface\QuadInterface and rdfInterface\DataFactory APIs.

• Tests for terms added.
• rdfInterface\RdfNamespace documentation provided.
• Default values of rdfInterface\DataFactory::literal and rdfInterface\Literal constructor made in line.
• Comments on rdfInterface\Literal::getDatatype() and rdfInterface\Literal::getLang() return type design decisions added.
• DataFactory tests split into separate methods to allow easier overriding (e.g. if a given library doesn't implement a given kind of term).
• README updated with an example of test class reuse.

A set of test classes to be used by implementations added.

Set default value of the $iri parameter of rdfInterface::DataFactory::defaultGraph($iri) to null.

The rdfInterface\Parser class constructor takes the rdfInterface\DataFactory instance now allowing a parser to work with any rdfInterface\DataFactory implementation.

Previously there was a Serializer class with serialise() and serialiseStream() methods. Method names are serialize() and serializeStream() now.