feat(cluster): php.ini configuration, execution profiles and ScyllaDB settings

[CodeLieutenant]

What this does

Adds a configuration layer for the driver and exposes a large part of the C driver surface the extension never reached. Coverage goes from 356 to 435 of 621 public cass_* functions, surfaced as 50 php.ini directives and a new ExecutionProfile class.

php.ini configuration

• Seeds for every Cluster\Builder default. Each with*() method still wins.
• Caps on the per-worker persistent caches, plus cassandra.allow_persistent as an operator kill switch.
• Every directive is PHP_INI_SYSTEM by design: the values form the persistent-cluster cache key, so a request-scoped ini_set() would grow EG(persistent_list) without bound.
• A bad value is ignored in favour of the documented default and writes one E_WARNING, so ini_get() and phpinfo() always report what the driver actually uses.

Execution profiles

enum Profile: string { case Analytics = 'analytics'; }

$cluster = Cassandra::cluster()
    ->withExecutionProfile(Profile::Analytics, (new Cassandra\ExecutionProfile)
        ->withConsistency(Cassandra::CONSISTENCY_LOCAL_ONE)
        ->withRequestTimeout(30.0))
    ->build();

$session->execute($stmt, null, Profile::Analytics);

All sixteen driver settings are covered. Name and selector take a string or an enum case: a string-backed enum contributes its value, any other enum its case name.

CassExecProfile is opaque, so each setter folds its arguments into a fingerprint that reaches the cluster cache key. Without that, two clusters differing only in a profile would share one CassCluster and silently get the wrong settings.

ScyllaDB and connection settings

Rack-aware load balancing, application name/version (visible in system.clients), exponential reconnect with jitter, speculative execution, event-loop tuning, and fourteen further cluster directives that each default to the C driver's own value.

Breaking changes

Change	Was	Revert with
Default consistency	LOCAL_ONE	cassandra.default_consistency = LOCAL_ONE
Persistent caches bounded	unlimited	cassandra.max_persistent_* = -1

Caps are 16 clusters, 16 sessions, 1000 prepared statements, sized from measured per-entry cost: ~12 KB, ~2.2 MB plus 2 sockets per node, and ~7.4 KB.

Fixes found on the way

• DefaultCluster::connect() leaked the connect CassFuture on the non-persistent path. Confirmed with leaks: one 192-byte root leak per call, now zero.
• withConnectionHeartbeatInterval() and withTCPKeepalive() passed a value 1000x too large. Both C functions take seconds; the builder stored milliseconds, so a 30 second heartbeat asked for 30000 seconds and effectively disabled heartbeats.
• cassandra.log = syslog created a file named syslog in the working directory instead of using syslog(3).

Verification

• Unit suite 879 passed, 0 failures, on the rebased branch.
• Baseline check: the pre-existing test set gives 867 / 12390 assertions both at trunk and with these changes, so no regression.
• clang-tidy: 0 findings on every touched file.
• leaks: 0 bytes across the cap, rack-aware, exponential, speculative and profile paths.
• Builds clean on DebugPHP8.4NTS, DebugPHP8.5NTS, RelWithDebInfoPHP8.5NTS.
• Live checks against ScyllaDB while it was up: rack-aware connect, APPLICATION_NAME in system.clients.client_options, and cap enforcement.

Reviewer notes

Rebased onto trunk. The branch is now 0 commits behind. Three conflicts were resolved: the sidebar moved into the new versioned website/.vitepress/versions.ts, the logging table merged expose_credentials with the new syslog target, and the Cluster\Builder reference merged both sets of rows.

Stale defect notes removed. trunk documents the heartbeat and TCP keepalive unit bug as a Known defect in 1.4.x and tells readers to divide by 1000 as a workaround. This branch fixes the bug, so that advice would now produce values 1000 times too short. Those notes are replaced with an upgrade note in connection-tuning.md, and the references in performance.md, connecting.md and the builder reference are removed.

Mixed content. The working tree already had uncommitted work when this was written, and it is included here at the author's request: release/packaging/CI changes (release.yml, compile-php.sh, FindLibGMP.cmake, README.md) and the removal of the legacy tests-old/ tree. Those are not part of the driver-configuration work and can be split out if you prefer.

Not verified. Execution profiles have not run against a live cluster (the local ScyllaDB went down partway through). ZTS is untested locally; CI's ts matrix is the first real check. syslog delivery is confirmed only in that it no longer creates a stray file or falls through to stderr.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request