Download the PHP package mroosz/php-cassandra without Composer

php-cassandra: A modern Cassandra client for PHP

php-cassandra is a pure-PHP client for Apache Cassandra with support for CQL binary protocol v3, v4 and v5 (Cassandra 4.x/5.x), synchronous and asynchronous APIs, prepared statements, batches, result iterators, object mapping, SSL/TLS, and LZ4 compression.

Package: https://packagist.org/packages/mroosz/php-cassandra

Highlights

• Protocol v3/v4/v5, auto-negotiated
• Two transports: sockets and PHP streams (streams support SSL/TLS and persistent connections)
• Synchronous and asynchronous requests
• Prepared statements with named or positional binding
• Batches: logged, unlogged, counter
• Full data type coverage (collections, tuples, UDTs, custom)
• Iterators plus multiple fetch styles (ASSOC, NUM, BOTH) and object mapping
• Events (schema/status/topology) with a simple listener interface
• Optional LZ4 compression and server overload signalling

Requirements

• PHP 8.1+
• 64-bit PHP for 64-bit types like Bigint, Counter, Duration, Time, Timestamp
• For socket transport: PHP sockets extension; stream transport has no extra extension requirements

Installation

Using Composer:

Or load the library without Composer:

Running tests

• Unit tests:

• Integration tests (Dockerized Cassandra 5):

You can manage steps manually:

Quick start

Connecting

Create NodeConfig instances and pass them to Connection:

Startup options (third constructor argument) support:

• COMPRESSION = lz4 if enabled on server
• THROW_ON_OVERLOAD = '1' or '0' (v4+)

Keyspace selection:

• v5: can also be sent per-request via Query/Execute options (see below)
• v3/v4: call $conn->setKeyspace('ks') or run USE ks

Consistency levels

Use the Consistency enum:

• ALL, ANY, EACH_QUORUM, LOCAL_ONE, LOCAL_QUORUM, LOCAL_SERIAL, ONE, QUORUM, SERIAL, THREE, TWO

Apply per call or as default via setConsistency().

Queries

Synchronous:

Asynchronous:

Query options (QueryOptions):

• pageSize (int)
• pagingState (string)
• serialConsistency (int; use Consistency::SERIAL->value or Consistency::LOCAL_SERIAL->value)
• defaultTimestamp (ms since epoch)
• namesForValues (bool): true to use associative binds
• keyspace (string; protocol v5 only)
• nowInSeconds (int; protocol v5 only)

Prepared statements

Pagination with prepared statements:

Batches

Batch options (BatchOptions): serialConsistency, defaultTimestamp, keyspace (v5), nowInSeconds (v5).

Results and fetching

querySync()/executeSync() return a RowsResult for row-returning queries. Supported methods:

• fetch(FetchType::ASSOC|NUM|BOTH) returns next row or false
• fetchAll(FetchType) returns all remaining rows
• fetchColumn(int $index)/fetchAllColumns(int $index)
• fetchKeyPair(int $keyIndex, int $valueIndex)/fetchAllKeyPairs(...)
• getIterator() returns a ResultIterator so you can foreach ($rowsResult as $row)

Example:

Object mapping

You can fetch rows into objects by implementing RowClassInterface or by using the default RowClass:

Data types

All native Cassandra types are supported via classes in Cassandra\Type\*. You may pass either:

• A concrete Type\... instance, or
• A PHP scalar/array matching the type; the driver will convert it when metadata is available

Examples:

Nested complex example (Set inside a row):

Special values:

• new \Cassandra\Value\NotSet() encodes a bind variable as NOT SET (distinct from NULL)

Events

Register a listener and subscribe for events on the connection:

Tracing and custom payloads (advanced)

You can enable tracing and set a custom payload on any request:

Compression

Enable LZ4 compression if supported by the server by passing the startup option:

Error handling

All operations throw \Cassandra\Exception for client errors and \Cassandra\Response\Exception for server-side errors (e.g., invalid query, unavailable, timeouts). Prepared statements are transparently re-prepared when needed.

API reference (essentials)

• Cassandra\Connection

  • connect(), disconnect()
  • setConsistency(Consistency)
  • querySync(string, array = [], ?Consistency, QueryOptions) / queryAsync(...)
  • prepareSync(string, PrepareOptions) / prepareAsync(...)
  • executeSync(PreparedResult|RowsResult, array = [], ?Consistency, ExecuteOptions) / executeAsync(...)
  • batchSync(Batch) / batchAsync(Batch)
  • syncRequest(Request) / asyncRequest(Request)
  • addEventListener(EventListener)
• Cassandra\Request\Options\QueryOptions | ExecuteOptions | BatchOptions
• Cassandra\Request\Batch, BatchType
• Cassandra\Response\Result\RowsResult (iterable, fetch helpers)
• Cassandra\Response\Result\RowClassInterface, RowClass
• Cassandra\Consistency (enum)
• Cassandra\Type (enum) and Cassandra\Type\* classes

License

MIT

Credits

Inspired by and building upon work from:

• duoshuo/php-cassandra
• arnaud-lb/php-cassandra