README

A lean, production-ready Laravel Eloquent adapter for SPARQL triple stores. Query and manage RDF data using familiar Laravel patterns.

Overview

Laravel SPARQL brings the power of RDF triple stores to Laravel with an Eloquent-style interface that feels native to Laravel developers. Built on the original Illuminate Database package by Taylor Otwell.

Key Features

• Familiar Eloquent API - Use standard Laravel patterns like where(), get(), first(), save(), delete()
• Analytical Queries (v1.2.3+) - Build complex queries with custom SELECT expressions, BIND clauses, and GROUP BY
• Hybrid Approach - Scalars for single values, arrays for multi-values (no unnecessary Collections)
• RDF Extensions - Language tags, multi-valued properties, and URI mappings when you need them
• Batch Operations - Efficient bulk insert/update/delete operations
• Sync Trait - Easily sync regular Eloquent models to SPARQL endpoints
• Multi-Tenancy Support - Full support for stancl/tenancy with automatic endpoint switching per tenant
• No Magic - Explicit model definitions, no dynamic class generation
• Production Ready - 514 passing tests, optimized for performance

Requirements

• PHP 8.2+
• Laravel 12.0+
• A SPARQL 1.1 compliant endpoint with Graph Store Protocol support
  • ✅ Apache Jena Fuseki
  • ✅ Blazegraph
  • ✅ Amazon Neptune
  • ✅ GraphDB
  • ✅ Virtuoso
  • ✅ Most modern SPARQL stores

Note: This package uses the W3C SPARQL 1.1 Graph Store HTTP Protocol for efficient bulk operations. This is a standard feature in modern SPARQL endpoints.

Installation

Install via Composer:

composer require your1/laravel-sparql

The service provider will automatically register a sparql database driver with Laravel's database manager.

Quick Start

1. Configure Your SPARQL Endpoint

Add to config/database.php:

'connections' => [
    'sparql' => [
        'driver' => 'sparql',
        'endpoint' => env('SPARQL_ENDPOINT', 'http://localhost:3030/test/sparql'),

        // IMPORTANT: Specify your triple store implementation
        'implementation' => env('SPARQL_IMPLEMENTATION', 'fuseki'),  // fuseki|blazegraph|generic

        'auth' => [
            'type' => 'digest',
            'username' => env('SPARQL_USERNAME'),
            'password' => env('SPARQL_PASSWORD'),
        ],
        'namespaces' => [
            'schema' => 'http://schema.org/',
            'foaf' => 'http://xmlns.com/foaf/0.1/',
        ],
    ],
],

Implementation Options:

• fuseki - Apache Jena Fuseki (default)
• blazegraph - Blazegraph triple store
• generic - W3C standard (Virtuoso, GraphDB, Stardog, Amazon Neptune, etc.)

Add to .env:

SPARQL_ENDPOINT=http://localhost:3030/test/sparql
SPARQL_IMPLEMENTATION=fuseki

2. Define a Model

use LinkedData\SPARQL\Eloquent\Model;

class Person extends Model
{
    protected $connection = 'sparql';
    protected $table = 'http://schema.org/Person';

    protected $propertyUris = [
        'name' => 'http://schema.org/name',
        'email' => 'http://schema.org/email',
        'age' => 'http://schema.org/age',
    ];

    protected $fillable = ['name', 'email', 'age'];
    protected $casts = ['age' => 'integer'];
}

3. Start Using It

// Create
$person = new Person();
$person->id = 'http://example.com/person/1';
$person->name = 'John Doe';
$person->email = 'john@example.com';
$person->save();

// Query
$adults = Person::where('age', '>', 18)->get();
$john = Person::where('name', 'John')->first();

// Update
$person->age = 31;
$person->save();

// Delete
$person->delete();

// Analytical queries (v1.2.3+)
use LinkedData\SPARQL\Query\Expression;

$labelStats = DB::connection('sparql')
    ->query()
    ->selectExpression('?language')
    ->selectExpression('(COUNT(?label) as ?count)')
    ->whereTriple('?concept', 'skos:inScheme', Expression::iri($schemeUri))
    ->whereTriple('?concept', 'skos:prefLabel', '?label')
    ->bind('COALESCE(LANG(?label), "no-lang")', '?language')
    ->groupBy('?language')
    ->get();

What's New in v1.2.3

Analytical Query Support - Build sophisticated SPARQL queries with Laravel's fluent syntax:

• selectExpression() - Custom SELECT with aggregates and computed values
• whereTriple() - Explicit triple patterns with namespace support
• bind() - BIND expressions for computed values
• Enhanced groupBy() for SPARQL variables

See Usage Guide - Analytical Queries for examples.

Documentation

For comprehensive guides and examples, see:

• Usage Guide - Core concepts, CRUD operations, queries, RDF features, batch operations, and syncing regular Eloquent models
• Multi-Tenancy Guide - Complete guide for integrating with stancl/tenancy for multi-tenant applications
• API Reference - Complete API documentation for all classes and methods
• Development Guide - Setup, testing, and development instructions

Philosophy

• Simple is Better - Minimal complexity, maximum clarity
• No Magic - Explicit over implicit, predictable behavior
• Performance First - Optimized for production workloads
• Laravel Native - Feels like standard Eloquent

Credits

Original Author: Roberto Guido - Created the foundational Laravel SPARQL adapter and maintained it as part of the Solid Data Workers project.

Original Repository: https://gitlab.com/solid-data-workers/laravel-sparql

Original Licenses: MIT License and Creative Commons Attribution 3.0 Unported

This fork preserves all original copyright and attribution while adding significant enhancements and modernizations.

Built on Laravel's Illuminate Database package by Taylor Otwell.

License

MIT License. See LICENSE for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions