Arangodb Ogm Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Symfony project via Composer:

   composer require alguilla/arangodb-ogm-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Alguilla\ArangoDbOgmBundle\AlguillaArangoDbOgmBundle::class => ['all' => true],
   ];
   

2. Configuration Define your ArangoDB connection in config/packages/alguilla_arangodb_ogm.yaml:

   alguilla_arangodb_ogm:
       clients:
           default:
               host: '%env(ARANGO_HOST)%'
               port: '%env(int:ARANGO_PORT)%'
               username: '%env(ARANGO_USER)%'
               password: '%env(ARANGO_PASSWORD)%'
   

3. First Model Create a document model (e.g., src/Document/User.php):

   namespace App\Document;
   
   use Alguilla\ArangoDbOgmBundle\Model\Document;
   
   class User extends Document
   {
       /** @var string */
       public $name;
   
       /** @var string */
       public $email;
   }
   

4. First Query Use the repository to interact with ArangoDB:

   use App\Document\User;
   use Alguilla\ArangoDbOgmBundle\Repository\DocumentRepository;
   
   $repository = $this->get(DocumentRepository::class);
   $user = $repository->findOneBy(['email' => 'user@example.com']);
   

Implementation Patterns

Common Workflows

1. CRUD Operations

   • Create: Use save() on a new document instance.

     $user = new User();
     $user->name = 'John Doe';
     $user->email = 'john@example.com';
     $repository->save($user);
     

   • Update: Modify properties and call save() again.
   • Delete: Use remove() or delete().

     $repository->remove($user);
     

2. Querying

   • Basic Queries: Use find(), findOneBy(), or findBy().

     $users = $repository->findBy(['active' => true]);
     

   • AQL Queries: Execute raw ArangoDB Query Language (AQL) via executeQuery().

     $result = $repository->executeQuery('FOR u IN users FILTER u.active RETURN u');
     

3. Relationships

   • Define edges (relationships) with @var annotations or properties.

     class Post extends Document
     {
         /** @var User */
         public $author;
     }
     

   • Use getRelation() to fetch related documents.

     $post = $repository->findOneBy(['id' => 123]);
     $author = $post->getRelation('author');
     

4. Collections

   • Dynamically switch collections via setCollection().

     $repository->setCollection('custom_users');
     

5. Transactions

   • Use beginTransaction() and commit() for atomic operations.

     $client = $this->get('alguilla_arangodb_ogm.client.default');
     $client->beginTransaction();
     try {
         $repository->save($user);
         $client->commit();
     } catch (\Exception $e) {
         $client->rollback();
     }
     

Integration Tips

1. Symfony Events

   • Bind ArangoDB operations to Symfony events (e.g., kernel.request).

   $this->get('alguilla_arangodb_ogm.client.default')->executeQuery('...');
   

2. Doctrine Bridge

   • If using Doctrine, map ArangoDB documents to Doctrine entities via custom hydrators or listeners.

3. Caching

   • Cache frequent queries using Symfony’s cache system.

   $cache = $this->get('cache.app');
   $key = 'users_active';
   $users = $cache->get($key, function() use ($repository) {
       return $repository->findBy(['active' => true]);
   });
   

4. Migrations

   • Use the bundle’s schema tools to manage collections and indexes.

   $schema = $this->get('alguilla_arangodb_ogm.schema');
   $schema->createCollection('users', ['numberOfShards' => 3]);
   

Gotchas and Tips

Pitfalls

1. Collection Naming

   • By default, the bundle uses the lowercase class name as the collection name (e.g., User → user). Override with @Collection annotation:

     /** @Collection("custom_users") */
     class User extends Document {}
     

2. Primary Key Conflicts

   • Ensure _key (ArangoDB’s primary key) is unique. The bundle auto-generates it if not provided, but manual assignments must be unique.

3. Transactions and Connections

   • Transactions must be managed explicitly. Forgetting to commit() or rollback() will leave transactions open.

4. AQL vs. OGM Queries

   • Complex queries may require raw AQL for performance. The OGM layer abstracts but doesn’t replace AQL entirely.

5. Edge Cases in Relationships

   • Bidirectional relationships require manual synchronization:

     $post->setAuthor($user);
     $user->addPost($post); // Assuming a method like this exists
     

Debugging

1. Enable Logging Configure Monolog to log ArangoDB queries:

   monolog:
       handlers:
           arango:
               type: stream
               path: "%kernel.logs_dir%/arangodb.log"
               level: debug
               channels: ["arangodb"]
   

   Then enable the channel in the bundle config:

   alguilla_arangodb_ogm:
       logging: true
   

2. Query Profiling Use ArangoDB’s built-in profiler or enable slow query logging in the bundle config:

   alguilla_arangodb_ogm:
       clients:
           default:
               slow_query_threshold: 100 # Log queries slower than 100ms
   

3. Connection Issues

   • Verify credentials and network access. Use ping() to test connections:

     $client->ping();
     

Extension Points

1. Custom Hydrators

   • Override document hydration by implementing Alguilla\ArangoDbOgmBundle\Hydrator\HydratorInterface.

2. Event Subscribers

   • Listen to document events (e.g., prePersist, postLoad) via Symfony’s event dispatcher:

     $dispatcher->addListener(DocumentEvents::PRE_PERSIST, function($event) {
         $document = $event->getDocument();
         // Pre-save logic
     });
     

3. Custom Repositories

   • Extend DocumentRepository to add domain-specific methods:

     class UserRepository extends DocumentRepository
     {
         public function findActiveUsers()
         {
             return $this->findBy(['active' => true]);
         }
     }
     

   • Register the service in services.yaml:

     App\Repository\UserRepository:
         arguments:
             $class: App\Document\User
         tags: ['alguilla_arangodb_ogm.repository']
     

4. Schema Customization

   • Extend the schema manager to add custom indexes or constraints:

     $schema->ensureIndex('users', ['email'], ['unique' => true]);