Php Driver Laravel Package

Getting Started

Minimal Setup

1. Install the PECL extension:

   pecl install cassandra
   

   Add to php.ini:

   extension=cassandra.so
   

2. Basic Laravel Integration: Create a service provider (app/Providers/CassandraServiceProvider.php):

   use Cassandra;
   
   class CassandraServiceProvider extends ServiceProvider {
       public function register() {
           $this->app->singleton('cassandra', function() {
               $cluster = Cassandra::cluster()
                   ->withContactPoints(['127.0.0.1'])
                   ->withPort(9042)
                   ->build();
               return $cluster->connect('your_keyspace');
           });
       }
   }
   

3. First Query:

   $session = app('cassandra');
   $result = $session->execute('SELECT * FROM users LIMIT 10');
   foreach ($result as $row) {
       dd($row); // Debug row data
   }
   

Key First Use Cases

• CRUD Operations: Simple queries with SimpleStatement.
• Prepared Statements: Secure parameter binding for writes.
• Async Execution: Parallel queries with executeAsync().
• Schema Inspection: Fetch metadata via $session->schema().

Implementation Patterns

Core Workflows

1. Connection Management:

   // Singleton pattern (recommended)
   $cluster = Cassandra::cluster()
       ->withContactPoints(config('cassandra.contact_points'))
       ->withPort(config('cassandra.port'))
       ->withLoadBalancingPolicy(new \Cassandra\LoadBalancing\DCAwareRoundRobinPolicy(
           config('cassandra.local_dc')
       ))
       ->build();
   

2. Query Execution:

   // Simple query
   $result = $session->execute('SELECT * FROM users WHERE id = ?', [1]);
   
   // Prepared statement (reused)
   $prepared = $session->prepare('INSERT INTO users (id, name) VALUES (?, ?)');
   $session->execute($prepared, [2, 'John Doe']);
   

3. Async + Parallelism:

   $future1 = $session->executeAsync('SELECT * FROM table1');
   $future2 = $session->executeAsync('SELECT * FROM table2');
   $result1 = $future1->get();
   $result2 = $future2->get();
   

4. Pagination:

   $statement = new \Cassandra\SimpleStatement('SELECT * FROM large_table');
   $statement->setFetchSize(100);
   $result = $session->execute($statement);
   while ($result->hasMorePages()) {
       $result = $session->execute($statement, [], ['result_set' => $result->getPagingStateToken()]);
   }
   

Laravel-Specific Patterns

1. Eloquent Integration (Custom Model):

   class CassandraUser extends Model {
       protected $connection = 'cassandra';
       protected $table = 'users';
       public $incrementing = false;
       protected $primaryKey = 'id';
   
       public static function boot() {
           static::addGlobalScope('cassandra', function (Builder $builder) {
               $builder->getQuery()->from('users');
           });
       }
   }
   

2. Query Builder Wrapper:

   // app/Database/Cassandra/QueryBuilder.php
   class CassandraQueryBuilder {
       protected $session;
   
       public function __construct($session) {
           $this->session = $session;
       }
   
       public function select($columns, $table) {
           $query = "SELECT " . implode(', ', $columns) . " FROM $table";
           return $this->session->execute($query);
       }
   }
   

3. Event Listeners for Schema Changes:

   // Listen for model events to sync Cassandra schema
   Model::saved(function ($model) {
       if ($model->connection === 'cassandra') {
           // Trigger schema update logic
       }
   });
   

4. Caching Layer:

   // Use Cassandra as a cache backend
   Cache::extend('cassandra', function ($app) {
       return Cache::repository(new CassandraStore(
           $app['cassandra'],
           config('cache.cassandra')
       ));
   });
   

Gotchas and Tips

Common Pitfalls

1. Memory Leaks:

   • Issue: FutureSession or Timestamp::toDateTime() may leak memory.
   • Fix: Avoid long-lived sessions; use executeAsync() with explicit timeouts:

     $future = $session->executeAsync($statement, [], ['timeout' => 5]);
     

2. Hashing Quirks:

   • Issue: IS_TRUE/IS_FALSE hash inconsistently to 1 in PHP 7.
   • Fix: Normalize boolean values before hashing:

     $hash = spl_object_hash($row['is_active'] ? true : false);
     

3. Type Mismatches:

   • Issue: tinyint/smallint may not map cleanly to PHP integers.
   • Fix: Cast explicitly:

     $value = (int) $row['tiny_column'];
     

4. Async Deadlocks:

   • Issue: Unreleased futures can block PHP’s event loop.
   • Fix: Always call get() or wait() on futures:

     $future->get(); // Release resources
     

5. Schema Metadata:

   • Issue: Default schema metadata updates can slow queries.
   • Fix: Disable if unused:

     $cluster = Cassandra::cluster()->withSchemaMetadata(false);
     

Debugging Tips

1. Enable Logging:

   $cluster = Cassandra::cluster()
       ->withLogLevel(\Cassandra\Logger::LOG_DEBUG)
       ->withLogFile('/var/log/cassandra_driver.log');
   

2. Query Tracing:

   $options = ['tracing' => true];
   $result = $session->execute($statement, [], $options);
   dd($result->getTracingInfo());
   

3. Connection Pooling:

   • Issue: Too many connections may crash Cassandra.
   • Fix: Limit connections per host:

     $cluster = Cassandra::cluster()
         ->withConnectionsPerHost(3)
         ->withIoThreads(4);
     

Extension Points

1. Custom Load Balancing:

   $cluster = Cassandra::cluster()
       ->withLoadBalancingPolicy(new CustomPolicy());
   

2. Retry Policies:

   $cluster = Cassandra::cluster()
       ->withRetryPolicy(new \Cassandra\RetryPolicy\DowngradingConsistencyRetryPolicy());
   

3. Type Serialization: Override Cassandra\Type\Type::serialize() for custom types.

4. Event Hooks: Extend Cassandra\Event\EventListener for pre/post-query hooks.

Laravel-Specific Quirks

1. Service Container Binding:

   • Bind the cluster/session as a singleton to avoid reconnection overhead:

     $this->app->singleton('cassandra.cluster', function () {
         return Cassandra::cluster()->build();
     });
     

2. Configuration: Use Laravel’s config system:

   // config/cassandra.php
   return [
       'contact_points' => env('CASSANDRA_CONTACT_POINTS', '127.0.0.1'),
       'port' => env('CASSANDRA_PORT', 9042),
       'keyspace' => env('CASSANDRA_KEYSPACE', 'default'),
       'timeout' => env('CASSANDRA_TIMEOUT', 5),
   ];
   

3. Migration Support: Create a custom migrator for Cassandra schema changes:

   class CassandraSchema {
       public static function createTable($table, $columns) {
           $query = "CREATE TABLE $table (" . implode(', ', $columns) . ")";
           app('cassandra')->execute($query);
       }
   }
   

4. Testing: Use Cassandra\Future for async testing:

   public function testAsyncQuery() {
       $future = $this->session->executeAsync('SELECT * FROM test');
       $this->assertTrue($future->isReady());
       $result = $future->get();
       $this->assertCount(1, $result);
   }