feat: extend utopia-php/query, add Query::cursor and count($max)

[lohanidamodar]

Summary

• The audit Query class becomes a thin extension of Utopia\Query\Query, so audit consumers share the canonical query type — including cursorAfter / cursorBefore — with the rest of the utopia ecosystem. Audit's lenient single-value factory signatures (equal, lessThan, greaterThan, between) are preserved as overrides so existing callers keep working with mixed values (including DateTime on the time column). The custom Query::in() alias is replaced by the inherited Query::contains().
• The ClickHouse adapter gains keyset-pagination cursor support. Cursor values accept a Log/ArrayObject or a plain associative array; an id tiebreaker is auto-appended to ORDER BY for deterministic pagination on non-unique columns; cursorBefore flips direction at SQL build time and reverses results post-fetch.
• count() and the four countBy* helpers (plus their abstract definitions and Audit facade wrappers) accept an optional ?int $max argument. When non-null, the ClickHouse path uses a bounded LIMIT subquery so very large tables can short-circuit; the Database path forwards $max to utopia-php/database's existing $max parameter. The countBy* helpers also stop loading rows just to count them — they call count() directly now.

Test plan

• composer lint passes
• composer check (PHPStan level max) passes
• tests/Audit/Adapter/ClickHouseTest.php passes — 39/39, including 5 new cursor + count($max) tests
• tests/Audit/QueryTest.php passes — 11/11
• Database adapter tests verified in CI (local environment lacks PDO MySQL driver)

Notes

The transitive PHP requirement is now >=8.4 because utopia-php/query 0.1.x requires it; the explicit >=8.0 in composer.json is preserved for consistency with other utopia libraries (composer resolves the actual minimum from the transitive dep).

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR makes Utopia\Audit\Query a thin extension of utopia-php/query, adds keyset cursor pagination (cursorAfter/cursorBefore) to the ClickHouse adapter, and introduces an optional ?int $max bound on all count / countBy* methods. The implementation is well-structured: a new getParamType/formatTypedValue layer centralises column-type–aware parameter binding, resolveCursorOrder auto-appends an id tiebreaker for deterministic pages, and cursorBefore correctly flips ORDER BY direction at SQL build time then reverses results post-fetch.

Confidence Score: 5/5

Safe to merge; only a P2 suggestion about guarding a negative $max value.

No P0/P1 findings. The single P2 (missing non-positive guard on $max) requires a deliberate bad call and results in a clear exception rather than silent data corruption. All previously flagged issues (null DateTime cursor, $id/id key cleanup, empty-values silent full-scan) have been addressed in this revision.

src/Audit/Adapter/ClickHouse.php — the new cursor and bounded-count paths are the largest surface area.

Important Files Changed

Filename	Overview
src/Audit/Adapter/ClickHouse.php	Adds cursor-based keyset pagination, bounded count($max), and a type-aware param-binding layer (getParamType/formatTypedValue). One minor issue: $max is not validated as positive before being bound to a UInt64 parameter.
src/Audit/Query.php	Refactored to extend Utopia\Query\Query, preserving legacy mixed-value factory overrides for equal, lessThan, greaterThan, and between; removes the standalone in() alias.
src/Audit/Adapter/Database.php	Adds ?int $max to all four countBy* methods and count(), forwarding it to utopia-php/database's count() max parameter; also skips cursor queries in count translation.
tests/Audit/Adapter/ClickHouseTest.php	Adds 11 new test cases for cursor pagination, bounded count, and new query types; ClickHouse connection now env-configurable. Tests rely on setUp/cleanup isolation correctly inherited from AuditBase.

_{Reviews (5): Last reviewed commit: "fix: reject empty values for filter meth..." | Re-trigger Greptile}