Download the PHP package intermaterium/cassandra-native without Composer

PHP CQL

Native Apache Cassandra and ScyllaDB connector for PHP applications using the CQL binary protocol (v4), without the need for an external extension.

Requires PHP version >=8, Cassandra >1.2, and any ScyllaDB version.

Much of the API is built to emulate the Datastax PHP Driver. Original work by Uri Hartmann

Installation

Features

• Simple and Prepared Statements
• SSL Encryption
• Persistent Connections
• Compression via LZ4.
• Authentication

Missing Features

• Batch Statements
• Async queries
• Result Paging
• Tuples and User Defined Types

Usage

Cluster

A Cassandra cluster can be built via the ClusterBuilder class. By default, the Cluster will try to connect to localhost.

You can specify a set of IP/hostnames to connect to using the withContactPoints method.

The client will attempt to connect to one of the contact points at random. If the connection fails it will try another host until all contact points have been attempted or max connection attempts, configured with the withMaxConnectionAttempts method, has been reached, default is 3 attempts. If the client cannot connect to any of the provided hosts an NoHostsAvailableException is thrown.

When connecting, the created Cassandra instance doesn't connect to a specific keyspace. Calling connect on the created Cassandra instance is the same as performing a USE $keyspace query against the connection.

SSL

You can turn on SSL Encryption via the SSLBuilder class and pass the result of a call to the build method to the withSSL method of a cluster builder instance.

Compression

Compression can be enabled by calling the withCompression method on the cluster builder.

When enabled, the client checks to see if the LZ4 extension is loaded by PHP. If the extension is not loaded, an exception is thrown.

Originally on creation, the client would send an OPTIONS request and choose which compression algorithm to use based from the response. This uncovered an issue when using persistent connections. Unless we were using a cache, there wasn't a way to tell if the persistent connection had compression enabled unless we queried the cluster again, and Cassandra would return a compressed OPTIONS response before we had set the compressor.

To make things simpler, the client now assumes that the Cassandra cluster supports LZ4 compression when compression is requested and Snappy compression has been removed.

Authentication

Authentication can be enabled by providing an Authentication Provider to the cluster build via the withCredentials method. With this library is the PasswordAuthenticator provider which accepts a plaintext username and password.

For other SASL based authentication methods you'll need to provide/use your own implementation. This can be done by creating a class which implements the AuthProviderInterface.

The mechanism method returns the fully qualified name of the java class cassandra is configured to use. This name can be found in the authenticator.class_name directive of the cassandra.yaml config.

The response method is called when the first auth challenge is issued. Some auth providers will only require sending this response.

For auth providers that require responding to subsequent authentication challenges the AuthChallengeProvderInterface is provided. This interface provides the challengeResponse method. This method accepts an token parameter which contains the binary representation of a token sent back from the Cassandra node describing how to respond to the auth challenge.

If a provider does not implement the AuthChallengeProviderInterface and an auth challenge is issued after the first response, an AuthenticationException is thrown.

Statements

The client currently only supports two types of statements, Simple and Prepared. Both types of statement are executed via the execute method on the Cassandra instance. The execute method accepts the statement, an optional array of values to bind to parameters and an optional consistency level which overrides the default consistency.

The execute method returns a Rows class which implements the ArrayAccess and Iterator interfaces.

Simple Statements

Simple statements use the SimpleStatement class.

Simple statements support parameterised values.

You must specify the bound parameters type when using a simple statement

Prepared Statements

Prepared Statements are created via the prepare method on the Cassandra instance.

Unlike Simple Statements, you don't need to specify the bound values type.

External links

1. Datastax's blog introducing the binary protocol: http://www.datastax.com/dev/blog/binary-protocol

2. CQL definitions https://cassandra.apache.org/doc/latest/cassandra/reference/native-protocol.html#native-protocol-version-4

License

The MIT License (MIT)

Copyright (c) 2023 Uri Hartmann
Copyright (c) 2025 Christopher Birmingham

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.