Phorient Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require biberltd/phorient
   

   Add to config/services.php (if using Laravel):

   'phorient' => [
       'root' => [
           'username' => env('ORIENTDB_ROOT_USERNAME', 'root'),
           'password' => env('ORIENTDB_ROOT_PASSWORD', 'root'),
       ],
       'database' => [
           'Dbname' => [
               'username' => env('ORIENTDB_DB_USERNAME', 'root'),
               'password' => env('ORIENTDB_DB_PASSWORD', 'root'),
               'hostname' => env('ORIENTDB_HOST', 'localhost'),
               'port' => env('ORIENTDB_PORT', 2424),
               'token' => null,
           ],
       ],
   ],
   

2. First Use Case: Define an entity class (e.g., User.php) in AppBundle/Entity/ with annotations:

   use Phorient\Annotation as PH;
   
   class User {
       /**
        * @PH\Id
        */
       public $id;
   
       /**
        * @PH\Field(type="string")
        */
       public $name;
   
       /**
        * @PH\Field(type="datetime")
        */
       public $createdAt;
   }
   

3. Initialize Connection:

   use Phorient\ClassManager;
   
   $classManager = new ClassManager();
   $classManager->setEntityPath('AppBundle', '\\AppBundle\\Entity\\');
   $connection = $classManager->createConnection('Dbname');
   

Implementation Patterns

Workflows

1. CRUD Operations:

   // Create
   $user = new User();
   $user->name = 'John Doe';
   $user->createdAt = new DateTime();
   $connection->save($user);
   
   // Fetch
   $user = $connection->find(User::class, $user->id);
   
   // Update
   $user->name = 'Jane Doe';
   $connection->update($user);
   
   // Delete
   $connection->delete($user);
   

2. Querying with Conditions:

   $users = $connection->findBy(User::class, ['name' => 'John Doe']);
   $users = $connection->findWhere(User::class, ['createdAt >' => '2023-01-01']);
   

3. Relationships (Embedded/Linked):

   // Embedded (e.g., Address)
   class User {
       /**
        * @PH\Embedded
        */
       public $address;
   }
   
   // Linked (e.g., Posts)
   class User {
       /**
        * @PH\LinkMany(mappedBy="user")
        */
       public $posts;
   }
   

4. Transactions:

   $connection->beginTransaction();
   try {
       $connection->save($user);
       $connection->save($post);
       $connection->commit();
   } catch (\Exception $e) {
       $connection->rollBack();
       throw $e;
   }
   

Integration Tips

• Laravel Eloquent Hybrid: Use traits to bridge Phorient with Eloquent:

  use Phorient\Eloquent\PhorientTrait;
  
  class User extends Model {
      use PhorientTrait;
      protected $connection = 'phorient';
  }
  

• Custom Annotations: Extend Phorient\Annotation\Field for domain-specific types:

  namespace App\Annotation;
  
  use Doctrine\Common\Annotations\Annotation;
  
  class CustomField extends Annotation {
      public $type;
  }
  

• Event Listeners: Hook into lifecycle events (e.g., preSave, postLoad):

  $connection->addListener(new class implements Phorient\Listener\ListenerInterface {
      public function preSave($entity) {
          if ($entity instanceof User) {
              $entity->updatedAt = new DateTime();
          }
      }
  });
  

Gotchas and Tips

Pitfalls

1. Annotation Parsing:

   • Issue: Column type annotations (e.g., @PH\Field(type="datetime")) may fail if malformed or missing.
   • Fix: Validate annotations with:

     $metadata = $connection->getMetadata(User::class);
     if (!$metadata->hasField('createdAt')) {
         throw new \RuntimeException('Missing annotation for createdAt');
     }
     

2. Datetime Torsion:

   • Issue: Timezone handling in DateTime objects may cause "torsion" (e.g., 2023-01-01 00:00:00 becoming 2022-12-31 18:00:00 in UTC).
   • Fix: Normalize datetimes before saving:

     $user->createdAt = (new DateTime())->setTimezone(new \DateTimeZone('UTC'));
     

3. Connection Management:

   • Issue: Reusing ClassManager across requests may cause stale connections.
   • Fix: Instantiate per request or use a service container:

     $container->bind(ConnectionInterface::class, function () {
         return (new ClassManager())->createConnection('Dbname');
     });
     

4. Embedded Objects:

   • Issue: Nested embedded objects may not serialize/deserialize correctly.
   • Fix: Ensure all embedded classes have proper annotations and implement __serialize()/__unserialize() if needed.

Debugging

• Enable Logging:

  $connection->setLogger(new \Monolog\Logger('phorient', [
      new \Monolog\Handler\StreamHandler(storage_path('logs/phorient.log')),
  ]));
  

• Query Inspection: Use Phorient\Debug\QueryLogger to dump raw OrientDB queries:

  $connection->setQueryLogger(new QueryLogger());
  

Extension Points

1. Custom Types: Override Phorient\Type\TypeRegistry to add support for custom types (e.g., enum):

   $registry = new TypeRegistry();
   $registry->register('enum', new CustomEnumType());
   $connection->setTypeRegistry($registry);
   

2. Event Dispatcher: Replace the default event system with Laravel’s:

   $connection->setEventDispatcher(app('events'));
   

3. Metadata Customization: Extend Phorient\Metadata\Driver\AnnotationDriver to support additional annotation sources (e.g., YAML):

   $driver = new AnnotationDriver();
   $driver->addAnnotationSource(new YamlAnnotationSource());
   $connection->setMetadataDriver($driver);
   

Configuration Quirks

• Token Authentication: If using token in config, ensure it’s a valid OrientDB security token (not a password).
• Port Defaults: OrientDB’s default port is 2424 (not 2480, which is the HTTP port). Verify in config/services.php.
• Case Sensitivity: Entity class paths are case-sensitive. Use absolute paths (e.g., \\AppBundle\\Entity\\User) to avoid issues.