Cassandra Bundle Laravel Package

Getting Started

This is a Symfony 2/3 bundle wrapping datastax/php-driver; it is not a Laravel package. As a Laravel developer, the practical first step is to decide whether you are maintaining a legacy Symfony app or trying to use Cassandra from Laravel.

• Legacy Symfony app: install the DataStax PHP extension (ext-cassandra) first, then composer require hendrahuang/cassandra-bundle. Register the bundle in AppKernel and configure contact points/keyspace in app/config/config.yml. Inject the bundle’s Cassandra session service into a small repository class.
• Laravel app: do not install this bundle. Install ext-cassandra and datastax/php-driver, then bind a Cassandra\Cluster/Cassandra\Session singleton in a service provider and wrap CQL access in repository classes.
• First use case: a single keyspace used for append-heavy data such as event logs, analytics rows, or session/activity records. Start with one prepared INSERT and one prepared SELECT by partition key before expanding — and if you are creating the table through the bundle (v1.8.0 expands the table-option surface considerably), set default_time_to_live at creation time so TTL/expiry is a schema property rather than application logic.

Look first at the bundle README/config reference to confirm the exact service ID and config keys; the package is old enough that assumptions from modern Symfony Flex bundles will not hold. As of v1.8.0 the table-option list to check is: comment, speculative_retry, additional_write_policy, gc_grace_seconds, bloom_filter_fp_chance, default_time_to_live, compaction, compression, caching, memtable_flush_period_in_ms, read_repair.

Implementation Patterns

Treat the bundle as a thin connection/service layer, not an ORM. Day-to-day usage should look like explicit CQL repositories:

• Inject the session, not the cluster. Keep one session per app/keyspace and inject it into repositories. Let the bundle manage connection setup where possible.
• Prepare statements once. Prepare write/read statements in repository constructors or lazily cache them. Re-preparing on every request is a common performance killer.
• Use bound values, never string interpolation. execute($stmt, ['id' => $id]) style binding is essential for correctness and injection safety.
• Batch deliberately. Use logged batches for atomic multi-partition writes and unlogged batches for same-partition bulk inserts. Do not treat batches as a generic bulk loader.
• Use async futures for parallel work. Execute independent queries asynchronously and resolve results together when latency matters.
• Paginate with paging state. Cassandra does not support OFFSET; use driver paging state or token-based ranges.
• Manage schema as CQL, but own the table options. Keep CQL schema files in the repo and apply them with cqlsh or a custom console command. v1.8.0 gives you a fuller set of table options to express at creation time — treat them as part of your schema contract and review them in code review like an index or primary key:
  • default_time_to_live — set on append-only tables (events, activity, sessions) so retention is enforced by the database instead of a cron job.
  • compaction / compression / caching — the three options that actually move read/write cost on write-heavy tables; pick TimeWindowCompactionStrategy for time-series and size-tiered/leveled for everything else, and be explicit rather than relying on server defaults.
  • gc_grace_seconds — pair it with your repair cadence; leaving it at the default while running infrequent repairs is how you resurrect deleted rows.
  • speculative_retry — a cheap latency win on tail-heavy reads; tune per table rather than globally.
  • additional_write_policy — Cassandra 4.0+ only; verify server version before adding it, or table creation will fail.
  • bloom_filter_fp_chance, memtable_flush_period_in_ms, read_repair, comment — set deliberately or not at all; comment is genuinely useful for documenting why the other options are what they are.
• Laravel integration pattern: create CassandraServiceProvider, bind Cassandra\Session as a singleton, and define repository interfaces so tests can fake them without a live cluster. If you need schema management, write an Artisan command that runs your CQL files with the same option set rather than trying to wire this bundle in.
• Testing: mock repository interfaces rather than the driver session; use Docker/local Cassandra for integration tests only. Add one integration test that asserts your schema actually applies with the options you specified — option typos surface as opaque server errors.

Gotchas and Tips

• Symfony-only and old. The bundle targets Symfony 2/3 and has no Flex recipe and no modern Symfony/Laravel support. v1.8.0 widens table-option coverage; it does not modernize the package. Pin the version and expect to own compatibility.
• The extension is the real dependency. Most failures are ext-cassandra install/mismatch issues, not bundle bugs. Verify with php -m | grep cassandra and confirm the driver supports your PHP and Cassandra versions.
• New table options are server-version-sensitive. additional_write_policy requires Cassandra 4.0+; older clusters reject it outright. Passing an option your cluster doesn't recognize typically fails at table-creation time with a generic "invalid table option" error that points at the query, not your config — check the server version first, then the option spelling.
• Options are creation-time. Changing compaction, compression, or default_time_to_live after the fact needs an ALTER TABLE; confirm whether the bundle emits CREATE only or also handles alters before assuming config changes take effect on an existing table. Assume CREATE only until you've read the source.
• default_time_to_live overrides your intent silently. Once set, every insert into that table expires — including rows you wanted to keep. Do not casually add it to a table that mixes durable and ephemeral data; split the table instead.
• Low maintenance signal. Eight stars, zero dependents, and an old release mean you should read the source before relying on undocumented behavior — the terse release notes here (a bare list of options) are a good example of the documentation quality to expect.
• Config quirks: confirm contact points, port, keyspace existence, consistency level, and timeout settings. A missing keyspace often surfaces as a connection-time error rather than a clear config error.
• Debug with the driver first. Test the same CQL — including the full CREATE TABLE ... WITH ... statement — via cqlsh, enable driver logging, and catch Cassandra\Exception subclasses to distinguish unavailable clusters, timeouts, and invalid queries. Reproducing the generated DDL in cqlsh is the fastest way to debug a rejected table option.
• Avoid long-lived stale sessions. In workers/queue consumers, handle reconnects and monitor driver health rather than assuming a singleton session survives forever.
• Extension points are thin. For anything beyond basic session wiring, add your own repository/service layer or a custom session factory. In Laravel, that means your own service provider is the correct integration point, not this bundle — and that includes schema management, where you should own the DDL and the option set rather than depend on bundle config for it.