Cassandra Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require amigosdelrigor/cassandra-bundle

(Note: This package is deprecated. For new projects, use datastax/php-driver + M6Web/CassandraBundle.)

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       AmigosDelRigor\CassandraBundle\AmigosDelRigorCassandraBundle::class => ['all' => true],
   ];
   

3. Configure Cassandra Connection in config/packages/amigos_del_rigor_cassandra.yaml:

   amigos_del_rigor_cassandra:
       connections:
           default:
               hosts: ['127.0.0.1']
               port: 9042
               keyspace: 'your_keyspace'
   

4. First Use Case: Querying Data Inject the CassandraConnection service and execute a CQL query:

   use AmigosDelRigor\CassandraBundle\Connection\CassandraConnection;
   
   class SomeService {
       public function __construct(private CassandraConnection $cassandra) {}
   
       public function fetchUsers() {
           $result = $this->cassandra->execute('SELECT * FROM users');
           return $result->all();
       }
   }
   

Implementation Patterns

Common Workflows

1. Connection Management:

   • Use dependency injection to get the CassandraConnection service.
   • Configure multiple connections in amigos_del_rigor_cassandra.yaml:

     amigos_del_rigor_cassandra:
         connections:
             analytics:
                 hosts: ['analytics-node1', 'analytics-node2']
                 keyspace: 'analytics_db'
     

   • Inject the specific connection by ID:

     $analyticsConnection = $this->container->get('amigos_del_rigor_cassandra.connection.analytics');
     

2. Query Execution:

   • Prepared Statements (recommended for security):

     $stmt = $this->cassandra->prepare('INSERT INTO users (id, name) VALUES (?, ?)');
     $stmt->bind([1, 'John Doe']);
     $stmt->execute();
     

   • Batch Operations:

     $batch = $this->cassandra->createBatch();
     $batch->insert('users', ['id' => 1, 'name' => 'Alice']);
     $batch->insert('users', ['id' => 2, 'name' => 'Bob']);
     $batch->execute();
     

3. Entity Mapping (Legacy Approach):

   • Use CassandraEntityManager (if using Doctrine-like ORM):

     $user = new User();
     $user->setId(1);
     $user->setName('Jane');
     $this->cassandra->persist($user);
     $this->cassandra->flush();
     

   (Note: This is outdated; prefer raw CQL or a modern bundle.)

4. Async Operations:

   • Use executeAsync() for non-blocking queries:

     $future = $this->cassandra->executeAsync('SELECT * FROM users');
     $result = $future->get(); // Blocks until result is ready
     

5. Schema Management:

   • Execute schema changes via raw CQL:

     $this->cassandra->execute('CREATE TABLE IF NOT EXISTS users (id int PRIMARY KEY, name text)');
     

Integration Tips

• Symfony Console Commands: Use the bundle’s CassandraCommand base class for CLI tools:

  use AmigosDelRigor\CassandraBundle\Command\CassandraCommand;
  
  class ImportUsersCommand extends CassandraCommand {
      protected function execute(InputInterface $input, OutputInterface $output) {
          $result = $this->getCassandraConnection()->execute('SELECT * FROM users');
          // Process results...
      }
  }
  

• Event Listeners: Listen to Cassandra events (e.g., connection failures) via Symfony’s event dispatcher:

  $dispatcher->addListener(
      'amigos_del_rigor_cassandra.connection.failure',
      function ($event) {
          // Handle failure (e.g., retry logic)
      }
  );
  

• Testing: Use the Mockery dev dependency to mock CassandraConnection in tests:

  $mock = Mockery::mock('AmigosDelRigor\CassandraBundle\Connection\CassandraConnection');
  $mock->shouldReceive('execute')->andReturn(new ResultSet([]));
  $this->container->set('amigos_del_rigor_cassandra.connection.default', $mock);
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • This bundle is deprecated due to phpcassa being unsupported. Migrate to:
     • datastax/php-driver (official Cassandra driver).
     • M6Web/CassandraBundle (modern Symfony bundle).

2. Connection Pooling:

   • phpcassa does not support connection pooling natively. For high traffic, consider:
     • Using a connection pool library (e.g., php-cassandra-connection-pool).
     • Switching to the newer driver.

3. CQL vs. Thrift:

   • This bundle uses Thrift (legacy protocol). Modern Cassandra uses CQL3. Ensure your queries are CQL-compliant:

     // Avoid Thrift-style queries (e.g., "get_slice")
     $this->cassandra->execute('SELECT * FROM users WHERE id = ?', [1]); // CQL
     

4. Keyspace Switching:

   • Keyspaces are not automatically switched between queries. Explicitly set the keyspace in each connection or use a connection per keyspace:

     amigos_del_rigor_cassandra:
         connections:
             app_keyspace:
                 keyspace: 'app_db'
             analytics_keyspace:
                 keyspace: 'analytics_db'
     

5. Error Handling:

   • phpcassa throws generic exceptions. Wrap queries in try-catch:

     try {
         $this->cassandra->execute('SELECT * FROM nonexistent_table');
     } catch (\Exception $e) {
         // Handle (e.g., log, retry)
     }
     

6. PHP Version:

   • Requires PHP 5.3.3+. If using PHP 7+, consider upgrading to the newer driver/bundle for better performance.

Debugging Tips

1. Enable Logging: Add to config/packages/monolog.yaml:

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

   Then enable the channel in your connection config:

   amigos_del_rigor_cassandra:
       logging: true
   

2. Query Tracing: Use TRACING ON in CQL for slow queries:

   $this->cassandra->execute('TRACING ON');
   $result = $this->cassandra->execute('SELECT * FROM large_table');
   

3. Connection Issues:

   • Verify Cassandra nodes are reachable (telnet <host> 9042).
   • Check firewall rules and authentication (if enabled).

Extension Points

1. Custom Connection Factories: Override the default connection factory to add logic (e.g., SSL):

   // src/Cassandra/CustomConnectionFactory.php
   use AmigosDelRigor\CassandraBundle\Connection\ConnectionFactory;
   
   class CustomConnectionFactory extends ConnectionFactory {
       public function createConnection(array $config) {
           $connection = parent::createConnection($config);
           $connection->setSsl(true); // Example extension
           return $connection;
       }
   }
   

   Register it as a service:

   services:
       amigos_del_rigor_cassandra.connection_factory:
           class: App\Cassandra\CustomConnectionFactory
           tags: ['amigos_del_rigor_cassandra.connection_factory']
   

2. Query Builders: Create a custom query builder to abstract CQL:

   class UserQueryBuilder {
       private $connection;
   
       public function __construct(CassandraConnection $connection) {
           $this->connection = $connection;
       }
   
       public function findById($id) {
           return $this->connection->execute('SELECT * FROM users WHERE id = ?', [$id]);
       }
   }
   

3. Event Subscribers: Extend functionality via Symfony events (e.g., pre-query hooks