Schema Api Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require effectiveactivism/sparql-client
   

2. Configure Endpoints in config/packages/sparql_client.yaml:

   sparql_client:
     query_endpoint: "http://your-sparql-endpoint/sparql"
     update_endpoint: "http://your-sparql-endpoint/sparql"
     shacl_endpoint: "http://validator-endpoint/shacl"  # Optional
   

3. First Query (e.g., in a controller):

   use EffectiveActivism\SparQlClient\Client\SparQlClientInterface;
   
   public function index(SparQlClientInterface $client) {
       $client->setExtraNamespaces(['schema' => 'http://schema.org/']);
       $result = $client->select(['?subject'])
           ->where([new Triple(new Variable('subject'), new PrefixedIri('schema', 'headline'), new PlainLiteral('Test'))])
           ->execute();
       return $result->getRows();
   }
   

Key First Use Case

Fetching Data:

$result = $client->select(['?article'])
    ->where([new Triple(new Variable('article'), new PrefixedIri('schema', 'headline'), new PlainLiteral('Laravel'))])
    ->execute();

Updating Data:

$client->insert([new Triple(
    new Iri('urn:example:article1'),
    new PrefixedIri('schema', 'headline'),
    new PlainLiteral('Updated Title')
)])
->execute();

Implementation Patterns

Query Workflows

1. CRUD Operations:

   • Create: Use insert() with a Triple or Quad.
   • Read: Use select() with where() clauses.
   • Update: Use replace() (DELETE+INSERT) or delete() + insert().
   • Delete: Use delete() with a where() filter.

2. Complex Queries:

   • Aggregations:

     $select->groupBy([new Variable('subject')])
         ->having(new GreaterThan(new Count(new Variable('subject')), new TypedLiteral(5)));
     

   • Subqueries:

     $subquery = $client->select([new Variable('temp')])
         ->where([new Triple(new Variable('temp'), new PrefixedIri('schema', 'headline'), new PlainLiteral('Subquery'))]);
     $select->where([new Triple(new Variable('main'), new PrefixedIri('schema', 'related'), $subquery)]);
     

3. Graph Patterns:

   • Optional Clauses:

     $select->where([new Triple($subject, $predicate, $object)])
         ->optional([new Triple($subject, new PrefixedIri('schema', 'author'), new Variable('author'))]);
     

Integration Tips

• Dependency Injection: Autowire SparQlClientInterface in controllers/services.
• Namespaces: Register prefixes globally via setExtraNamespaces() or per-query:

  $client->setExtraNamespaces(['foaf' => 'http://xmlns.com/foaf/0.1/']);
  

• Error Handling: Wrap execute() in try-catch:

  try {
      $client->execute($statement);
  } catch (SparQlClientException $e) {
      // Log or handle error
  }
  

• SHACL Validation: Validate data before updates:

  $validator = $client->getShaclValidator();
  $validator->validate($data, 'http://shapes-graph');
  

Common Patterns

1. Dynamic Queries:

   $variables = ['?subject', '?predicate'];
   $select = $client->select($variables)
       ->where([new Triple(new Variable('subject'), new Variable('predicate'), new Variable('object'))]);
   

2. Bulk Operations:

   $triples = [];
   foreach ($articles as $article) {
       $triples[] = new Triple(
           new Iri($article['id']),
           new PrefixedIri('schema', 'headline'),
           new PlainLiteral($article['title'])
       );
   }
   $client->insert($triples)->execute();
   

Gotchas and Tips

Pitfalls

1. Endpoint Mismatch:

   • Issue: Using query_endpoint for updates (e.g., insert()).
   • Fix: Ensure update_endpoint is configured for write operations.
   • Debug: Check UpdateResultInterface status codes (e.g., getStatusCode()).

2. Namespace Scope:

   • Issue: Prefixes defined in setExtraNamespaces() are not inherited by subqueries.
   • Fix: Redefine namespaces in nested queries or use full IRIs.

3. Variable Binding:

   • Issue: Forgetting to declare variables in select() but using them in where().
   • Fix: Always list variables explicitly in select():

     $select = $client->select([new Variable('subject')])->where([...]);
     

4. Literal Datatypes:

   • Issue: Incorrect datatype handling (e.g., PlainLiteral vs TypedLiteral).
   • Fix: Use TypedLiteral for typed values (e.g., new TypedLiteral('2023-01-01', 'xsd:date')).

5. SHACL Validation:

   • Issue: Validation fails silently if the endpoint is misconfigured.
   • Fix: Verify the shacl_endpoint and handle ShaclValidationException.

Debugging Tips

1. Raw SPARQL:
   • Extract the generated query for debugging:

     $query = $statement->getQueryString();
     dump($query);
     

2. Logging:
   • Enable Symfony’s profiler to inspect SPARQL queries and responses.
3. Endpoint Testing:
   • Test endpoints manually (e.g., via SPARQL Playground) to isolate issues.

Performance Quirks

1. Large Datasets:
   • Use limit() and offset() for pagination:

     $select->limit(100)->offset(200);
     

2. Indexing:
   • Ensure your SPARQL endpoint (e.g., Blazegraph, Oxigraph) has proper indexes for predicates/objects used in where() clauses.

Extension Points

1. Custom Terms:
   • Extend TermInterface for domain-specific terms (e.g., CustomIri).
2. Query Builders:
   • Create helper methods for common queries:

     public function findArticlesByHeadline(SparQlClientInterface $client, string $headline) {
         return $client->select(['?article'])
             ->where([new Triple(new Variable('article'), new PrefixedIri('schema', 'headline'), new PlainLiteral($headline))])
             ->execute();
     }
     

3. Result Transformers:
   • Convert results to domain objects:

     $rows = $result->getRows();
     return array_map(function ($row) {
         return new Article($row['article']->getIri());
     }, $rows);
     

4. Middleware:
   • Add interceptors for logging/validation:

     $client->addMiddleware(function ($statement, callable $next) {
         // Pre-process statement
         $result = $next($statement);
         // Post-process result
         return $result;
     });
     

Configuration Quirks

1. Default Graphs:
   • If using FROM NAMED, ensure the named graph exists in your endpoint.
2. Update Endpoint:
   • Some endpoints (e.g., Virtuoso) require PATCH for updates. Configure the client to use the correct HTTP method if needed.
3. Timeouts:
   • Adjust HTTP client timeouts in Symfony’s http_client configuration if queries hang.

Validation Tips

1. SHACL Shapes:
   • Define shapes for your data model to catch errors early:

     <http://example/shapes/ArticleShape>
       a sh:NodeShape ;
       sh:targetClass schema:Article ;
       sh:property [
         sh:path schema:headline ;
         sh:datatype xsd:string ;
       ] .
     

2. Manual Validation:
   • Validate terms before building queries:

     $iri = new Iri('http://example.org/resource');
     if (!$iri->isValid()) {
         throw new \InvalidArgumentException('Invalid IRI');
     }