Rdf Helpers Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sweetrdf/rdf-helpers
   

   Ensure your project uses rdfInterface (v1 or v2) as a dependency.

2. First Use Case: Serialize an RDF literal to NTriples format:

   use sweetrdf\rdfHelpers\NtriplesUtil;
   
   $util = new NtriplesUtil();
   $serialized = $util->serializeLiteral("example", "en");
   // Output: "example"@en
   

3. Key Classes to Explore:

   • DefaultGraph for default graph implementations.
   • GenericQuadIterator for iterating over RDF quads.
   • RdfNamespace for managing RDF namespaces.

Implementation Patterns

Core Workflows

1. Namespace Management

Use RdfNamespace to register and resolve IRIs:

$ns = new RdfNamespace();
$ns->add('ex', 'http://example.org/');

$iri = $ns->resolve('ex:resource');
// Returns: "http://example.org/resource"

2. Quad Iteration

Iterate over RDF quads (subject, predicate, object, graph) using GenericQuadIterator:

use sweetrdf\rdfHelpers\GenericQuadIterator;

$quads = [
    ['subj', 'pred', 'obj', 'graph'],
    ['subj2', 'pred2', 'obj2', 'graph2']
];

$iterator = new GenericQuadIterator($quads);
foreach ($iterator as $quad) {
    echo $quad->getSubject(); // Access quad components
}

3. NTriples Serialization

Convert RDF terms to NTriples format:

$util = new NtriplesUtil();
$ntriple = $util->serialize([
    'subject' => 'ex:subj',
    'predicate' => 'ex:pred',
    'object' => 'object value',
    'graph' => 'ex:graph'
]);
// Output: <http://example.org/subj> <http://example.org/pred> "object value" .

4. Term Iteration

Filter and manipulate term iterators:

$terms = ['term1', 'term2', 'term3'];
$iterator = new GenericTermIterator($terms);

// Filter terms
$filtered = $iterator->skip(['term2']);
$filtered->getValues(); // ['term1', 'term3']

// Check for term existence
$iterator->contains('term1'); // true

Integration Tips

Laravel-Specific Patterns

1. Service Provider Binding: Bind RdfNamespace or NtriplesUtil in a service provider for dependency injection:

   $this->app->bind(RdfNamespace::class, function () {
       $ns = new RdfNamespace();
       $ns->add('app', config('app.url'));
       return $ns;
   });
   

2. Query Builder Extensions: Extend Laravel’s query builder to work with RDF quads:

   // Example: Custom RDF query builder
   class RdfQueryBuilder extends Builder {
       public function withQuadIterator(GenericQuadIterator $iterator) {
           // Process quads...
       }
   }
   

3. API Responses: Serialize RDF data for API responses:

   return response()->json([
       'data' => $util->serialize($rdfData)
   ]);
   

Gotchas and Tips

Pitfalls

1. Iterator Validity: GenericQuadIterator::current() returns null if the iterator is invalid (e.g., after next() on an exhausted iterator). Always check for null:

   if ($iterator->valid()) {
       $quad = $iterator->current();
   }
   

2. Namespace Collisions: RdfNamespace::add() throws an exception if the prefix already exists. Use has() to check first:

   if (!$ns->has('ex')) {
       $ns->add('ex', 'http://example.org/');
   }
   

3. NTriples Escaping: NtriplesUtil handles escaping automatically, but manual input (e.g., user-provided strings) may require pre-escaping to avoid malformed output.

Debugging Tips

1. Term Comparison: Use TermIteratorInterface::contains() for debugging term presence:

   if (!$iterator->contains($expectedTerm)) {
       throw new \RuntimeException("Term not found in iterator");
   }
   

2. Quad Validation: Validate quads before serialization:

   $quad = $iterator->current();
   if (!$quad->getSubject() || !$quad->getPredicate()) {
       throw new \InvalidArgumentException("Invalid quad");
   }
   

Extension Points

1. Custom Iterators: Extend GenericQuadIterator to support custom data sources (e.g., database queries):

   class DatabaseQuadIterator extends GenericQuadIterator {
       public function __construct(Connection $connection) {
           $this->connection = $connection;
       }
   
       public function current() {
           return $this->connection->fetchQuad();
       }
   }
   

2. Namespace Strategies: Override RdfNamespace::resolve() for custom IRI resolution logic (e.g., dynamic prefixes):

   class DynamicRdfNamespace extends RdfNamespace {
       public function resolve($prefix) {
           if ($prefix === 'dynamic') {
               return 'http://dynamic.example.com/' . time();
           }
           return parent::resolve($prefix);
       }
   }
   

3. Serialization Hooks: Extend NtriplesUtil for custom serialization rules:

   class CustomNtriplesUtil extends NtriplesUtil {
       public function serializeLiteral($value, $lang = null) {
           if ($lang === 'custom') {
               return '"' . $value . '"^^<http://example.org/custom>';
           }
           return parent::serializeLiteral($value, $lang);
       }
   }