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

composer.json

@@ -27,9 +27,10 @@
         }
     },
     "require": {
-        "php": ">=8.0",
+        "php": ">=8.4",
         "utopia-php/database": "5.*",
         "utopia-php/fetch": "0.5.*",
+        "utopia-php/query": "0.1.*",
         "utopia-php/validators": "0.2.*"
     },
     "require-dev": {

src/Audit/Adapter.php

@@ -100,6 +100,7 @@ abstract public function countByUser(
         string $userId,
         ?\DateTime $after = null,
         ?\DateTime $before = null,
+        ?int $max = null,
     ): int;
 
     /**
@@ -131,6 +132,7 @@ abstract public function countByResource(
         string $resource,
         ?\DateTime $after = null,
         ?\DateTime $before = null,
+        ?int $max = null,
     ): int;
 
     /**
@@ -166,6 +168,7 @@ abstract public function countByUserAndEvents(
         array $events,
         ?\DateTime $after = null,
         ?\DateTime $before = null,
+        ?int $max = null,
     ): int;
 
     /**
@@ -201,6 +204,7 @@ abstract public function countByResourceAndEvents(
         array $events,
         ?\DateTime $after = null,
         ?\DateTime $before = null,
+        ?int $max = null,
     ): int;
 
     /**
@@ -226,10 +230,15 @@ abstract public function find(array $queries = []): array;
     /**
      * Count logs using custom queries.
      *
+     * When $max is non-null the count is bounded at the database level so
+     * very large tables can short-circuit once the cap is reached. Pass
+     * `null` for an unbounded total.
+     *
      * @param array<\Utopia\Audit\Query> $queries
+     * @param int|null $max Optional upper bound (inclusive) for the count
      * @return int
      *
      * @throws \Exception
      */
-    abstract public function count(array $queries = []): int;
+    abstract public function count(array $queries = [], ?int $max = null): int;
 }