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

your1 / laravel-sparql

Maintainers

Details