Arc2 Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require semsol/arc2:^3
   

   Requires PHP 8.4+.

2. Basic RDF Operations:

   use ARC2 as ARC;
   
   // Initialize store (MySQL example)
   $dbConfig = [
       'db_name' => 'your_db',
       'db_user' => 'user',
       'db_pwd'  => 'password',
       'db_host' => 'localhost',
   ];
   $store = ARC::getStore($dbConfig);
   
   // Create a resource
   $resource = $store->getResource('http://example.org/resource');
   $resource->addProperty('http://example.org/property', 'value');
   
   // Save to store
   $store->saveResource($resource);
   

3. First SPARQL Query:

   $query = "
       SELECT ?subject ?property ?value
       WHERE {
           ?subject ?property ?value .
       }
       LIMIT 10
   ";
   $results = $store->query($query);
   

Key Entry Points

• Core RDF: ARC2_Class for resource/property manipulation.
• SPARQL: ARC2_Store for queries (SELECT, INSERT, DELETE, etc.).
• Triplestore: MySQL-backed with PDO/mysqli support.

Implementation Patterns

1. RDF Resource Management

Pattern: Use ARC2_Resource for structured data.

$resource = $store->getResource('http://example.org/person');
$resource->addProperty('http://xmlns.com/foaf/0.1/name', 'John Doe');
$resource->addProperty('http://xmlns.com/foaf/0.1/age', 30);

// Save with inferred triples (if enabled)
$store->saveResource($resource, ['infer' => true]);

Workflow:

1. Create/update resources via getResource().
2. Attach properties with addProperty().
3. Save with optional inference (infer: true).

2. SPARQL Query Workflows

Pattern: Use ARC2_Store::query() for SPARQL 1.0/1.1.

// SELECT with aggregates (note: SUM/AVG have bugs)
$query = "
    SELECT ?person (COUNT(?friend) AS ?friendCount)
    WHERE {
        ?person <http://xmlns.com/foaf/0.1/knows> ?friend .
    }
    GROUP BY ?person
";
$results = $store->query($query);

Integration Tips:

• LOAD Data: Use LOAD <url> to import RDF (Turtle, RDF/XML).

  LOAD <http://example.com/data.ttl> INTO <http://example.com/graph>
  

• Bulk Operations: Combine INSERT/DELETE with CONSTRUCT for dynamic updates.

  INSERT INTO <http://example.org/backup> {
      ?s ?p ?o .
  }
  WHERE {
      ?s <http://example.org/old> ?o .
  }
  

3. Triplestore Configuration

Pattern: Configure DB adapter (PDO/mysqli) and caching.

$dbConfig = [
    'db_adapter' => 'pdo',       // or 'mysqli' (default)
    'db_pdo_protocol' => 'mysql', // for PDO
    'cache' => [
        'enabled' => true,
        'adapter' => 'apcu',      // or 'file', 'memcache'
    ],
];
$store = ARC::getStore($dbConfig);

Laravel Integration:

• Store config in .env:

  ARC2_DB_NAME=laravel_arc2
  ARC2_DB_USER=root
  ARC2_DB_PASSWORD=secret
  ARC2_DB_ADAPTER=pdo
  

• Load via Laravel’s config:

  $config = config('arc2');
  $store = ARC::getStore($config);
  

Gotchas and Tips

Pitfalls

1. PHP 8.4+ Requirement:

   • Older PHP versions (e.g., 7.4) will fail. Use composer require php:^8.4 if needed.

2. SPARQL Bugs:

   • SUM/AVG functions are bugged (see #99). Use COUNT/MIN/MAX as alternatives.
   • LOAD with INTO may fail if the target graph doesn’t exist (create it manually).

3. PDO vs. mysqli:

   • PDO: Throws exceptions on errors; requires manual DB creation.
   • mysqli: Silent failures possible; uses ARC2_Class::queryDB() (deprecated for direct DB access).

4. Caching Quirks:

   • Cache must be explicitly enabled in config. Default: false.
   • apcu cache requires pecl install apcu.

Debugging Tips

1. Query Errors:

   • Enable SPARQL debug mode:

     $store->setDebug(true);
     

   • Check raw SQL via ARC2_Store::getLastQuery().

2. Performance:

   • Index frequently queried properties:

     CREATE INDEX idx_subject ON arc2_triples (subject);
     

   • Use LIMIT in queries to avoid timeouts.

3. Data Corruption:

   • Run ARC2_Store::repair() if triples are missing:

     $store->repair();
     

Extension Points

1. Custom SPARQL Functions:

   • Extend ARC2_SPARQL_Function to add user-defined functions.
   • Example: Register a CUSTOM_FUNC:

     $store->registerSPARQLFunction('CUSTOM_FUNC', function($args) {
         return array_sum($args);
     });
     

2. Database Adapters:

   • Implement ARC2_Store_Adapter_Abstract for new DB backends (e.g., PostgreSQL).

3. Event Hooks:

   • Override ARC2_Store::preSave()/postSave() for pre/post-save logic.