Arangodb Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require triagens/arangodb
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Triagens\ArangoDb\ArangoDbServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Triagens\ArangoDb\ArangoDbServiceProvider"
   

   Update .env with your ArangoDB credentials:

   ARANGODB_HOST=your-arango-host
   ARANGODB_PORT=8529
   ARANGODB_USER=root
   ARANGODB_PASSWORD=your-password
   

3. First Query Inject the client into a controller or service:

   use Triagens\ArangoDb\Client;
   
   public function __construct(Client $arangodb)
   {
       $this->client = $arangodb;
   }
   
   public function fetchDocuments()
   {
       $collection = $this->client->collection('your_collection');
       $documents = $collection->all();
       return $documents;
   }
   

Implementation Patterns

Common Workflows

1. CRUD Operations

   // Create
   $document = $collection->insert(['name' => 'Test', 'value' => 123]);
   
   // Read
   $document = $collection->findOne(['name' => 'Test']);
   
   // Update
   $collection->update($document['_key'], ['value' => 456]);
   
   // Delete
   $collection->delete($document['_key']);
   

2. AQL Queries

   $query = $this->client->query('
       FOR doc IN your_collection
       FILTER doc.value > 100
       RETURN doc
   ');
   $results = $query->execute();
   

3. Graph Operations

   $graph = $this->client->graph('your_graph');
   $vertices = $graph->vertices('your_vertex_collection');
   $edges = $graph->edges('your_edge_collection');
   
   // Add edge
   $graph->addEdge('vertex1', 'vertex2', ['type' => 'relation']);
   

4. Transactions

   $this->client->transaction(function ($tx) {
       $tx->collection('collection1')->insert(['data' => 'test']);
       $tx->collection('collection2')->insert(['data' => 'test2']);
   });
   

Integration Tips

• Eloquent Integration: Use jenssegers/arangodb alongside triagens/arangodb for ORM-like syntax if preferred.
• Event Listeners: Attach listeners to collections for real-time updates:

  $collection->listen('document.inserted', function ($event) {
      Log::info('New document inserted:', $event->document);
  });
  

• Batching: Use batch() for bulk operations:

  $collection->batch(function ($batch) {
      $batch->insert(['name' => 'Batch1']);
      $batch->insert(['name' => 'Batch2']);
  });
  

Gotchas and Tips

Pitfalls

1. Connection Issues

   • Ensure ARANGODB_HOST and ARANGODB_PORT are correct (default: 8529).
   • Verify firewall rules allow traffic on the port.
   • Use ARANGODB_SSL=true if connecting via HTTPS.

2. Query Performance

   • Avoid FULLTEXT or complex AQL queries in loops; cache results when possible.
   • Use EXPLAIN in AQL queries to analyze performance:

     $query = $this->client->query('EXPLAIN FOR doc IN your_collection RETURN doc');
     

3. Collection Existence

   • Always check if a collection exists before operations:

     if (!$this->client->hasCollection('your_collection')) {
         $this->client->createCollection('your_collection');
     }
     

4. Transaction Isolation

   • Long-running transactions may lock resources. Keep them short and atomic.

Debugging

• Enable debug mode in config:

  'debug' => env('ARANGODB_DEBUG', false),
  

• Log raw queries for troubleshooting:

  $this->client->setLogger(function ($query) {
      Log::debug('ArangoDB Query:', ['query' => $query]);
  });
  

Extension Points

1. Custom Middleware Override request/response handling:

   $client->middleware(function ($request) {
       $request->setOption('timeout', 10000); // Custom timeout
   });
   

2. Query Builders Extend the QueryBuilder class for domain-specific methods:

   class CustomQueryBuilder extends \Triagens\ArangoDb\QueryBuilder
   {
       public function byName($name)
       {
           return $this->where('name', $name);
       }
   }
   

3. Event Customization Subscribe to ArangoDB events globally:

   $client->on('collection.created', function ($event) {
       // Post-creation logic
   });
   

Config Quirks

• Default Database: Set ARANGODB_DATABASE in .env to avoid hardcoding.
• Authentication: For basic auth, ensure ARANGODB_USER and ARANGODB_PASSWORD are set. For JWT, configure:

  'auth' => [
      'driver' => 'jwt',
      'token' => env('ARANGODB_JWT_TOKEN'),
  ],