Schema Api Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**: Add the package via Composer:
   ```bash
   composer require effectiveactivism/sparql-client

2. Configuration: Define endpoints in config/packages/sparql_client.yaml:

   sparql_client:
     query_endpoint: "http://your-sparql-endpoint/sparql"
     update_endpoint: "http://your-sparql-endpoint/sparql"
   

3. First Use Case: Query for a simple triple pattern:

   use EffectiveActivism\SparQlClient\Client\SparQlClientInterface;
   use EffectiveActivism\SparQlClient\Syntax\Term\Variable\Variable;
   use EffectiveActivism\SparQlClient\Syntax\Term\Iri\PrefixedIri;
   use EffectiveActivism\SparQlClient\Syntax\Pattern\Triple\Triple;
   
   public function index(SparQlClientInterface $client) {
       $client->setExtraNamespaces(['schema' => 'http://schema.org/']);
       $subject = new Variable('subject');
       $predicate = new PrefixedIri('schema', 'name');
       $triple = new Triple($subject, $predicate, new Variable('object'));
       $result = $client->select([$subject])->where([$triple])->execute();
       return $result->getRows();
   }
   

Implementation Patterns

Query Workflows

1. CRUD Operations:

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

2. Complex Queries:

   • Aggregations: Use Count, Sum, etc., in groupBy()/having():

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

   • Subqueries: Chain select() statements or use Subquery in where():

     $subquery = $client->select([$var])->where([$triple])->subquery();
     $select->where([new Filter(new In($var, $subquery))]);
     

3. Graph Management:

   • Bulk Operations: Use load() or clear() for graph-level actions:

     $client->load(new Iri('urn:dataset'), new Iri('urn:source'))
            ->execute();
     

4. Validation:

   • Integrate SHACL validation via the shacl_endpoint:

     $validator = $client->getShaclValidator();
     $result = $validator->validate($data, $shaclShape);
     

Integration Tips

1. Dependency Injection:
   • Bind SparQlClientInterface in services.yaml for reusable queries:

     services:
         App\Service\SparqlService:
             arguments:
                 $client: '@effectiveactivism.sparql_client.client'
     

2. Query Builders:
   • Create reusable query builders for common patterns:

     class ArticleQueryBuilder {
         public function findByHeadline(SparQlClientInterface $client, string $headline) {
             $subject = new Variable('subject');
             $predicate = new PrefixedIri('schema', 'headline');
             $object = new PlainLiteral($headline);
             return $client->select([$subject])
                           ->where([new Triple($subject, $predicate, $object)]);
         }
     }
     

3. Error Handling:
   • Wrap executions in try-catch for SPARQL errors:

     try {
         $result = $client->execute($statement);
     } catch (SparqlClientException $e) {
         $this->addFlash('error', $e->getMessage());
     }
     

Gotchas and Tips

Common Pitfalls

1. Endpoint Mismatch:

   • Issue: Forgetting to separate query_endpoint and update_endpoint for SPARQL 1.1.
   • Fix: Always configure both endpoints explicitly (e.g., Oxigraph requires /query and /update paths).

2. Namespace Scope:

   • Issue: Prefixed IRIs failing due to missing namespaces.
   • Fix: Set namespaces before building queries:

     $client->setExtraNamespaces(['schema' => 'http://schema.org/']);
     

   • Tip: Use setDefaultNamespace() for global defaults.

3. Variable Binding:

   • Issue: Variables in SELECT not matching WHERE clauses.
   • Fix: Ensure variable names are consistent:

     $var = new Variable('x'); // Reuse the same instance/object
     

4. Update Operations:

   • Issue: execute() on update statements returning UpdateResultInterface (not QueryResultInterface).
   • Fix: Check getStatusCode() for HTTP errors:

     $result = $client->execute($insertStatement);
     if ($result->getStatusCode() !== 200) {
         throw new RuntimeException('Update failed');
     }
     

5. Performance:

   • Issue: Slow queries due to unbound variables or large WHERE clauses.
   • Fix:
     • Use limit()/offset() for pagination.
     • Pre-filter with FILTER clauses:

       $select->where([$triple])
              ->filter(new GreaterThan($var, new TypedLiteral(100)));
       

Debugging Tips

1. Raw SPARQL:

   • Extract the raw query string for debugging:

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

2. Logging:

   • Enable debug mode in config:

     sparql_client:
       debug: true
     

   • Logs will include query execution details.

3. SHACL Validation:

   • Issue: Validation failing silently.
   • Fix: Check the validator’s getResults() for detailed errors:

     $results = $validator->validate($data, $shape);
     foreach ($results->getConforms() as $conforms) {
         if (!$conforms) {
             dump($results->getMessages());
         }
     }
     

Extension Points

1. Custom Functions:

   • Extend with custom ExtensionFunction implementations:

     class MyCustomFunction extends ExtensionFunction {
         public function getName(): string { return 'my:customFunc'; }
         public function evaluate(array $args, array $bindings): TermInterface {
             // Implement logic
             return new PlainLiteral('result');
         }
     }
     

   • Register via service:

     services:
         App\Function\MyCustomFunction:
             tags: ['effectiveactivism.sparql_client.extension_function']
     

2. Query Modifiers:

   • Create decorators for StatementInterface to add reusable modifiers:

     class PaginatedSelectDecorator implements StatementInterface {
         private StatementInterface $statement;
         public function __construct(StatementInterface $statement) {
             $this->statement = $statement;
         }
         public function limit(int $limit): self {
             $this->statement->limit($limit);
             return $this;
         }
         // Implement other StatementInterface methods
     }
     

3. Result Transformers:

   • Convert QueryResultInterface to domain objects:

     class SparqlToArticleTransformer {
         public function transform(QueryResultInterface $result): array {
             return array_map(function ($row) {
                 return new Article(
                     $row['subject']->getValue(),
                     $row['headline']->getValue()
                 );
             }, $result->getRows());
         }
     }
     

Configuration Quirks

1. Default Namespaces:

   • Issue: Overriding default namespaces (e.g., rdf, xsd) accidentally.
   • Fix: Avoid setting them unless necessary; use setExtraNamespaces() for custom ones.

2. SHACL Endpoint:

   • Issue: SHACL validation failing with CORS or auth errors.
   • Fix: Configure the endpoint with proper headers or credentials:

     sparql_client:
       shacl_endpoint: "http://validator/shacl"
       shacl_headers:
         Authorization: "Bearer token123"
     

3. Timeouts:

   • Issue: Queries timing out on large datasets.
   • Fix: Adjust HTTP client timeouts in config/packages/http_client.yaml:

     framework:
         http_client:
             timeout: 60
             max_duration: 120
     

---