refactor: C23 modernization wave 2

[CodeLieutenant]

Summary

Continues the C++ → C23 migration: adopts the language features the C23 standard added for safety (nullptr, auto, constexpr, [[attributes]], = {}), hardens the public API with [[gnu::nonnull]] / [[gnu::pure]] / [[gnu::const]] / [[nodiscard]], and pushes more correctness into the gen_stub layer so the generated arginfo files stop being a magic-number duplicator.

Highlights

Correctness (these fix latent bugs)

• @not-serializable on 29 native-pointer-holding classes (Cluster/Session/Statement/Future/Rows/TimestampGen/SSL/RetryPolicy/Database meta). Without this, default serialize($cluster) → unserialize(...) produces an object with no native handle; the next method call dereferences uninitialized memory. Now PHP refuses the operation explicitly.
• typeof in SAFE_STR / SAFE_ZEND_STRING — the prior ((a) ? a : "") evaluated a twice; any side-effecting argument was UB.
• ulong portability — removed the project-local typedef unsigned long ulong; and migrated 8 call sites to zend_ulong (the PHP-canonical type). ulong isn't POSIX and needs _BSD_SOURCE on glibc.

Stub-driven codegen

• @cvalue for all enum-backed constants in Cassandra.stub.php — CONSISTENCY_*, VERIFY_*, BATCH_*, LOG_*, VERSION. The generated arginfo emits ZVAL_LONG(&val, CASS_CONSISTENCY_ANY) instead of ZVAL_LONG(&val, 0x0); values stay synchronized with cassandra.h automatically.
• @not-serializable wired into 29 stubs (see above).

Attribute hardening

• [[nodiscard, gnu::nonnull(...)]] on public *_instantiate / *_initialize APIs (DateTime, RetryPolicy, SSLOptions, plus utility headers).
• [[gnu::const]] exception_class(CassError) — pure mapping, CSE-able.
• [[gnu::pure]] / [[gnu::const]] on the FNV cache-key helpers.
• PHP_SCYLLADB_CLEANUP(fn) macro wrapping __attribute__((cleanup(...))). Adopted at 10 sites in bind_argument_by_index / bind_argument_by_name — removes the CassError rc; ...; free(data); CHECK_RESULT(rc); ladder and keeps exception safety.

Language modernization

• nullptr instead of NULL across hand-written sources (~370 sites).
• auto (C23) where the type is spelled twice: auto self = PHP_SCYLLADB_GET_X(zv); (~370 sites across 49 files).
• [[maybe_unused]] on parameter declarations instead of (void)param; suppressions.
• = {} (C23) replacing = {0} at the 9 sites that had it.
• static constexpr for true compile-time constants where the value isn't consumed by the preprocessor (FNV table, default consistency).

Dispatcher refactor

• bind_argument_by_index / bind_argument_by_name: switch (Z_TYPE_P(value)) replaces the if-chain over primitives. One read, one jump table. Object branch unchanged.

Build / lint policy

• .clang-tidy enables modernize-use-nullptr, modernize-use-bool-literals, modernize-macro-to-enum, plus a handful of readability-* checks now that the codebase is C23-ready.
• cmake/TargetOptimizations.cmake: C standard bumped to c_std_23; C++ stays at C++20 for residual .cpp files until ported.
• Dropped dead #ifdef __cplusplus / extern "C" guards in headers we own (no C++ TUs exist in src/). PHP-idiomatic BEGIN_EXTERN_C / END_EXTERN_C kept where the convention applies.

What's deliberately NOT in this PR

• No mass zero-init of bare zval x; locals — they're immediately written by ZVAL_NULL / array_init / etc., which don't read prior state. Mass = {} would emit dead xors.
• No new *_arginfo.h files committed — they're gitignored and regenerated by tools/gen_stub/gen_arginfo.sh at build time.
• No @frameless-function / @compile-time-eval — apply only to global functions, of which we have none.

Test plan

Build verification was not run locally; the toolchain needs libuv + cpp-driver + a compiled PHP source tree + a running ScyllaDB. CI will exercise the full matrix. Highest-attention items:

• cmake --preset DebugPHP8.4NTS && cmake --build out/DebugPHP8.4NTS — compiles clean across the matrix.
• ./scripts/run-scylladb.sh && composer install && php ./vendor/bin/pest — the test suite covers the bind_argument_* paths that got the dispatcher refactor and the cleanup-attribute adoption.
• Spot-check: var_dump(unserialize(serialize($cluster))) should now throw Serialization of 'Cassandra\DefaultCluster' is not allowed instead of producing a half-constructed object.
• [[gnu::nonnull]] annotations may surface new compiler warnings at internal call sites where a nullptr flows in unconditionally — those are real bugs worth reviewing.

🤖 Generated with Claude Code