feat: CommentQuery (WP_Comment_Query)

README.md

@@ -1868,6 +1868,33 @@ UserQuery::select()
 
 The deprecated `who` parameter is not supported: use `capability()`.
 
+## CommentQuery
+
+`CommentQuery` builds `WP_Comment_Query` arguments. `metaQuery()`, `dateQuery()` and the `meta*()` methods are the same ones as on `PostQuery`.
+
+```php
+use Pollora\Query\CommentQuery;
+
+CommentQuery::select()
+    ->postId(42)
+    ->approved()
+    ->threaded()
+    ->latest()
+    ->get();                        // WP_Comment_Query
+```
+
+- **Comments**: `whereIn()` (`comment__in`), `whereNotIn()`, `authorEmail()`, `authorUrl()`, `authorIn()`, `authorNotIn()`, `userId()`, `karma()`, `search()`, `includeUnapproved()`. `CommentQuery::find(5)` or `find([1, 2])` is `comment__in`.
+- **Status and type**: `status()`, `approved()` (`approve`), `pending()` (`hold`), `type()`, `typeIn()`, `typeNotIn()`.
+- **Replies**: `parentId()`, `rootOnly()`, `parentIn()`, `parentNotIn()`, `hierarchical('threaded' | 'flat' | false)`, `threaded()`, `flat()`.
+- **Post**: `postId()`, `postIn()`, `postNotIn()`, `postAuthor()`, `postAuthorIn()`, `postAuthorNotIn()`, `postName()`, `postParent()`, `postStatus()`, `postType()`.
+- **Order**: `orderBy($field, $direction)` can be chained (fields and directions are sent as a map); `orderByDate()`, `orderByAuthor()`, `orderByInclude()`, `latest()`, `oldest()`, `withoutOrder()`, `orderByMeta()`.
+- **Limit**: `limit()` / `take()` (`number`), `offset()` / `skip()`, `paged()`.
+- **Fields**: `select('ids')` or `fields('ids')`; `'all'` (or `'*'`) is WP's default.
+- **Cache**: `noFoundRows()`, `updateMetaCache()`, `updatePostCache()`, `cacheDomain()`.
+- **Results**: `get()` returns the `WP_Comment_Query`; `first()`, `ids()`, `count()` and `exists()` run it on a copy of the builder. `count()` ignores `limit()`, `offset()` and `paged()`.
+
+> WP's default status is `all`, which is `hold` and `approve`: **spam and trash comments are left out** unless you ask for them with `status()`. `CommentQuery` does not change that. WP also skips counting the total rows by default (`no_found_rows`), call `noFoundRows(false)` if you need it.
+
 ## Testing
 
 ```bash

src/CommentQuery.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pollora\Query;
+
+use Pollora\Query\Traits\Comments\Caching;
+use Pollora\Query\Traits\Comments\Fields;
+use Pollora\Query\Traits\Comments\Filters;
+use Pollora\Query\Traits\Comments\Order;
+use Pollora\Query\Traits\Comments\PostFilters;
+use Pollora\Query\Traits\Comments\Retrieval;
+use Pollora\Query\Traits\Concerns\BuildsArguments;
+use Pollora\Query\Traits\Concerns\LimitsResults;
+use Pollora\Query\Traits\Concerns\PagedResults;
+use Pollora\Query\Traits\DateQuery;
+use Pollora\Query\Traits\MetaField;
+use Pollora\Query\Traits\MetaQuery;
+use WP_Comment_Query;
+
+class CommentQuery
+{
+    use BuildsArguments, Caching, DateQuery, Fields, Filters, LimitsResults, MetaField, MetaQuery, Order, PagedResults, PostFilters, Retrieval;
+
+    /**
+     * @param  array<int>|int|null  $commentId  A comment ID, or a list of comment IDs.
+     */
+    public function __construct(array|int|null $commentId = null, ?string $fields = null)
+    {
+        if (is_int($commentId)) {
+            $this->whereIn([$commentId]);
+        } elseif (is_array($commentId)) {
+            $this->whereIn($commentId);
+        }
+
+        if ($fields) {
+            $this->fields($fields);
+        }
+    }
+
+    /**
+     * @param  array<int>|int|null  $commentId
+     */
+    public static function find(array|int|null $commentId = null): self
+    {
+        return new static($commentId);
+    }
+
+    public static function select(?string $fields = 'all'): self
+    {
+        return new static(null, $fields);
+    }
+
+    public function get(): WP_Comment_Query
+    {
+        return new WP_Comment_Query($this->getArguments());
+    }
+}

src/Traits/Comments/Caching.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pollora\Query\Traits\Comments;
+
+trait Caching
+{
+    protected ?bool $noFoundRows = null;
+
+    protected ?bool $updateCommentMetaCache = null;
+
+    protected ?bool $updateCommentPostCache = null;
+
+    protected ?string $cacheDomain = null;
+
+    /**
+     * Whether the total number of comments is skipped. WP skips it by default, call `noFoundRows(false)`
+     * if you need the total or the number of pages.
+     */
+    public function noFoundRows(bool $value = true): self
+    {
+        $this->noFoundRows = $value;
+
+        return $this;
+    }
+
+    public function updateMetaCache(bool $value = true): self
+    {
+        $this->updateCommentMetaCache = $value;
+
+        return $this;
+    }
+
+    /**
+     * Primes the cache of the posts the comments belong to.
+     */
+    public function updatePostCache(bool $value = true): self
+    {
+        $this->updateCommentPostCache = $value;
+
+        return $this;
+    }
+
+    public function cacheDomain(string $domain): self
+    {
+        $this->cacheDomain = $domain;
+
+        return $this;
+    }
+}

src/Traits/Comments/Fields.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pollora\Query\Traits\Comments;
+
+use Pollora\Query\QueryException;
+use Pollora\Query\Traits\Concerns\ValidatesChoices;
+
+trait Fields
+{
+    use ValidatesChoices;
+
+    protected ?string $fields = null;
+
+    /**
+     * 'ids' returns comment IDs only, 'all' (or '*') whole comments, which is WP's default.
+     *
+     * @throws QueryException
+     */
+    public function fields(string $value): self
+    {
+        $value = $value === '*' ? 'all' : $value;
+        $this->assertOneOf($value, ['all', 'ids'], 'fields value');
+
+        $this->fields = $value === 'all' ? null : $value;
+
+        return $this;
+    }
+}