Phporient Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ostico/phporient
   

   Ensure your OrientDB 3.x server is running (default: localhost:2424). This release drops support for versions below 3.0.

2. Basic Connection

   use Ostico\PhpOrient\Client;
   
   $client = new Client('localhost', 2424, 'root', 'root', [
       'protocol' => 'binary', // Default, but explicitly supported in 3.x
       'security' => false,    // Enable if using TLS in 3.x
   ]);
   $database = $client->connect('testDB');
   

3. First Query (CRUD Example)

   // Create a record (OrientDB 3.x syntax)
   $record = $database->createRecord('V', ['name' => 'Test']);
   $database->save($record);
   
   // Fetch with 3.x-compatible query
   $result = $database->query("SELECT FROM V WHERE name = 'Test'");
   $record = $result->one();
   

4. Key Files

   • src/Client.php: Updated for OrientDB 3.x protocol handshake.
   • src/Database.php: Added 3.x-specific query optimizations.
   • src/Record.php: Enhanced type validation for 3.x schema constraints.

Implementation Patterns

Common Workflows

1. Schema Management (3.x Features)

   // Create a class with 3.x schema constraints
   $database->createClass('User', [
       'name' => ['type' => 'STRING', 'mandatory' => true],
       'age' => ['type' => 'INTEGER', 'min' => 0],
       'metadata' => ['type' => 'EMBEDDEDMAP']
   ]);
   
   // Drop with 3.x safety checks
   $database->dropClass('User', ['force' => false]); // Defaults to false in 3.x
   

2. Querying with Parameters (3.x Optimized)

   $users = $database->query(
       "SELECT FROM User WHERE age > :age AND name CONTAINS :name",
       ['age' => 25, 'name' => 'A%'],
       ['index' => 'User_age_idx'] // Leverage 3.x indexes
   );
   

3. Transactions (3.x ACID Compliance)

   $database->beginTransaction();
   try {
       $record = $database->createRecord('User', ['name' => 'Alice']);
       $database->save($record);
       $database->commit(); // 3.x enforces stricter transaction isolation
   } catch (\Exception $e) {
       $database->rollback();
   }
   

4. Bulk Operations (3.x Batch API)

   $users = [
       ['name' => 'Bob', 'age' => 30],
       ['name' => 'Charlie', 'age' => 35],
   ];
   $database->bulkInsert('User', $users, ['batchSize' => 50]); // 3.x batch optimization
   

5. Edge (Relationship) Handling (3.x Directed Graphs)

   $user = $database->query("SELECT FROM User WHERE name = 'Alice'")->one();
   $friend = $database->query("SELECT FROM User WHERE name = 'Bob'")->one();
   $user->addEdge('knows', $friend, ['since' => 2020]); // 3.x edge properties
   $database->save($user);
   

Integration Tips

• Laravel Eloquent: Use ostico/phporient-laravel (v1.2+) for 3.x ORM integration.
• Caching: Cache with Laravel’s cache system, but invalidate on schema changes:

  Cache::forget('orientdb:schema:User');
  

• Security: Enable TLS in 3.x:

  $client = new Client('localhost', 2424, 'root', 'root', [
      'security' => true,
      'tls' => ['cert' => '/path/to/cert.pem']
  ]);
  

Gotchas and Tips

Pitfalls

1. Binary Protocol Changes

   • Breaking: OrientDB 3.x uses a revised binary protocol. Downgrade ostico/phporient to ^1.2 for 2.x compatibility.
   • Fix: Update PHP’s ext/protocol or use the new BinaryProtocol3 class:

     $client = new Client(..., ['protocol' => 'binary3']);
     

2. Connection Pooling (3.x Strictness)

   • 3.x enforces connection limits. Reuse $client and $database:

     // Anti-pattern (avoid)
     foreach ($users as $user) {
         $newClient = new Client(...); // Creates new connection per loop
     }
     

3. Type Handling (3.x Schema Enforcement)

   • 3.x validates types strictly. Use MapType::EMBEDDEDMAP for nested data:

     // Wrong (3.x will reject)
     $record->setField('metadata', ['key' => 'value']);
     
     // Correct
     $record->setField('metadata', new EmbeddedMap(['key' => 'value']));
     

4. Query Deprecations

   • Removed: SELECT @rid syntax. Use SELECT FROM V WHERE @rid = #12:0 instead.
   • Added: 3.x supports LET for subqueries:

     $database->query("
         LET $users = SELECT FROM User
         SELECT FROM $users WHERE age > 25
     ");
     

Debugging Tips

• Enable 3.x Debug Mode:

  $client = new Client(..., ['debug' => true, 'logLevel' => 'verbose']);
  

  Check logs for protocol version mismatches.

• Validate Schema Compatibility:

  if (!$database->isSchemaCompatible()) {
      throw new \RuntimeException("Schema version mismatch. Upgrade OrientDB.");
  }
  

• Handle 3.x-Specific Errors:

  try {
      $database->query("INVALID SYNTAX");
  } catch (\Ostico\PhpOrient\Exception\SyntaxError $e) {
      // 3.x throws SyntaxError for malformed queries
  }
  

Extension Points

1. Custom Protocol Handlers (3.x) Extend Ostico\PhpOrient\Protocol\BinaryProtocol3 for 3.x-specific commands:

   class CustomProtocol3 extends BinaryProtocol3 {
       public function customCommand($command) {
           return $this->sendCommand(['custom' => $command]);
       }
   }
   

2. Event Listeners (3.x Schema Events) Hook into 3.x schema change events:

   $database->on('schemaChange', function($event) {
       Log::info("Schema changed: {$event->getClass()}");
   });
   

3. Query Builder (3.x Features) Add 3.x-specific methods:

   class QueryBuilder {
       public function let($alias, $query) {
           return new static("LET $alias = " . $query);
       }
   }