PHPLARA-225 Support relation aggregates on document models (#3560)

withCount, withExists, withSum, withAvg, withMin and withMax now work on
MongoDB models, as well as loadCount, loadExists and loadAggregate.

MongoDB has no correlated subquery, so the values cannot be selected with the
parent documents as Eloquent does. They are computed with one additional query
per aggregate, after the parent documents are read, then set as attributes.
Embedded relations need no extra query at all. Unsupported cases (MorphTo,
hybrid relations, ordering by an aggregate alias) throw instead of silently
returning a wrong value.

Author: GromNaN

resources/boost/skills/laravel-mongodb/SKILL.md

@@ -8,14 +8,14 @@ metadata:
 
 # Laravel MongoDB
 
-Implementation skill for `mongodb/laravel-mongodb`. Exists to prevent the common mistakes: auto-increment IDs, `withCount()`, `toSql()`, SQL `JOIN`, `distinct()->get()` expecting scalar arrays, and `belongsTo()` over native ObjectId FKs.
+Implementation skill for `mongodb/laravel-mongodb`. Exists to prevent the common mistakes: auto-increment IDs, `toSql()`, SQL `JOIN`, `distinct()->get()` expecting scalar arrays, and `belongsTo()` over native ObjectId FKs.
 
 ## Core Workflow
 
 1. Identify layer: model, query builder, relationship, schema/index, queue/cache/session, search, or transaction.
 2. Confirm model extends `MongoDB\Laravel\Eloquent\Model` (or uses `DocumentModel` trait).
 3. Map every FK and `_id`: ObjectId in DB, **string** in Eloquent — cast accordingly.
-4. Replace unsupported helpers (`withCount`, `toSql`, `groupByRaw`, `whereFulltext`, `union`, `inRandomOrder`, `whereColumn`) with MongoDB alternatives.
+4. Replace unsupported helpers (`toSql`, `groupByRaw`, `whereFulltext`, `union`, `inRandomOrder`, `whereColumn`) with MongoDB alternatives.
 5. Validate: `php artisan migrate`, Pest tests, `phpcs`/`phpstan`.
 
 ## Related MongoDB tooling
@@ -35,7 +35,7 @@ Suggest installing the MongoDB agent skills plugin if not already installed. Ins
 | Topic | Reference file | Load When |
 |---|---|---|
 | Models, casts, `_id` mapping | `references/eloquent-models.md` | Defining or modifying a model |
-| Query builder gotchas, aggregation | `references/query-builder.md` | Writing queries, `withCount`, `distinct`, grouping |
+| Query builder gotchas, aggregation | `references/query-builder.md` | Writing queries, relation aggregates, `distinct`, grouping |
 | Embedded, hybrid, cross-database relations | `references/relationships.md` | `belongsTo`, `hasMany`, `embedsMany`, `hasManyIn` |
 | Connection setup | `references/connection.md` | `config/database.php`, multiple connections |
 | Indexes, migrations | `references/schema.md` | Creating indexes, migrations, collections |
@@ -56,12 +56,13 @@ Suggest installing the MongoDB agent skills plugin if not already installed. Ins
 - Cast FK fields to `string` via `$casts` on the child model when FK values may come from outside model attributes (imports, raw ObjectIds) — prevents BSON type mismatches on direct `where('author_id', $id)` queries.
 - Eager-load with `::with()` — MongoDB does no server-side joins for Eloquent relations.
 - Use aggregation pipeline for grouping, counting per group, `$lookup`, and `$sample`.
+- Relation aggregates (`withCount()`, `withExists()`, `withSum()`, `withAvg()`, `withMin()`, `withMax()`) are supported. Use a `$lookup` pipeline when the aggregated value must be filtered, sorted or paginated on.
 - Create indexes in migrations: `Schema::connection('mongodb')->create('posts', fn (Blueprint $c) => $c->index('user_id'))`.
 - Use `DB::connection('mongodb')->transaction(...)` only on replica set / sharded cluster.
 
 ### MUST NOT DO
 
-- `withCount()` / `withAvg()` / `withSum()` — silently wrong or throws. Use `$lookup` + `$size`/`$avg`/`$sum` aggregation.
+- `orderBy()` on a `withCount()` / `withAggregate()` alias — the value is computed after the documents are read, so it throws. Use `$lookup` + `$size` aggregation, or sort the resulting collection.
 - `toSql()` / `toRawSql()` — no SQL. Use `->dump()` / `->dd()`.
 - `distinct('field')->get()` expecting scalars — returns a Collection. Use `->distinct()->pluck('field')`.
 - `groupByRaw()`, `orderByRaw()`, `havingRaw()`, `whereFulltext()`, `union()`, `whereColumn()` — use aggregation.
@@ -128,27 +129,7 @@ final class User extends Model
 }
 ```
 
-### 3. Aggregation replacing `withCount`
-
-```php
-<?php
-
-use App\Models\Post;
-
-// WRONG: Post::withCount('comments')->get();
-$posts = Post::raw(fn ($collection) => $collection->aggregate([
-    ['$lookup' => [
-        'from'         => 'comments',
-        'localField'   => '_id',
-        'foreignField' => 'post_id',
-        'as'           => 'comments',
-    ]],
-    ['$addFields' => ['comments_count' => ['$size' => '$comments']]],
-    ['$project'   => ['comments' => 0]],
-]));
-```
-
-### 4. Queue job
+### 3. Queue job
 
 ```php
 <?php
@@ -173,7 +154,7 @@ final class IndexPostJob implements ShouldQueue
 IndexPostJob::dispatch((string) $post->_id)->onConnection('mongodb');
 ```
 
-### 5. Feature test (Pest)
+### 4. Feature test (Pest)
 
 ```php
 <?php

resources/boost/skills/laravel-mongodb/references/query-builder.md

@@ -5,7 +5,6 @@
 | Standard Eloquent | Status | MongoDB replacement |
 |---|---|---|
 | `toSql()` / `toRawSql()` | unsupported | `->dump()` / `->dd()` / `->toMql()` |
-| `withCount()` / `withAvg()` / `withSum()` | unsupported | aggregation `$lookup` + `$size` / `$avg` / `$sum` |
 | `groupByRaw()` / `orderByRaw()` / `havingRaw()` | unsupported | aggregation `$group` / `$sort` |
 | `whereFulltext()` | unsupported | Atlas Search `$search` stage |
 | `union()` | unsupported | aggregation `$unionWith` |
@@ -33,15 +32,41 @@ $genres = Movie::raw(fn ($c) => $c->aggregate([
 
 Do **not** use `Movie::raw(fn ($c) => $c->distinct('field'))` via Eloquent if you expect a Collection — use `->distinct()->pluck()` instead.
 
-## Replacing `withCount`
+## Relation aggregates
 
-`withCount()`, `withAvg()`, and `withSum()` are **not supported** on MongoDB models — they silently return wrong results or throw. Replace with a `$lookup` + `$size` / `$avg` / `$sum` aggregation pipeline.
+`withCount()`, `withExists()`, `withSum()`, `withAvg()`, `withMin()` and `withMax()` are supported, as well as
+`loadCount()`, `loadExists()` and `loadAggregate()`. They set the aggregated value as an attribute on the
+parent models, exactly like the base Eloquent builder.
 
 ```php
-// WRONG — withCount is not supported on MongoDB models
-$posts = Post::withCount('comments')->get();
+$posts = Post::withCount('comments')
+    ->withExists('author')
+    ->withMax('comments as top_score', 'score')
+    ->get();
 
-// CORRECT
+$posts[0]->comments_count;   // int, 0 when there is no related document
+$posts[0]->author_exists;    // bool
+$posts[0]->top_score;        // null when there is no related document
+
+// Constrained aggregate
+Post::withCount(['comments' => fn ($query) => $query->where('approved', true)])->get();
+```
+
+Supported relations: `hasOne`, `hasMany`, `morphOne`, `morphMany`, `belongsTo`, `belongsToMany`, `morphToMany`,
+`morphedByMany`, `embedsOne` and `embedsMany`.
+
+Anything else throws a `LogicException` rather than returning a wrong value: `morphTo`, `hasManyThrough`, and
+hybrid relations where the related model is not stored in MongoDB.
+
+Limitations:
+
+- `orderBy()` on an aggregate alias throws, because the value does not exist server side. Sort the resulting
+  collection with `sortBy()` instead.
+- `cursor()` and `lazy()` do not eager load, so the aliases are absent on those paths.
+- Constraint closures on embedded relations are not supported.
+- Use a `$lookup` pipeline instead when you need to filter, sort or paginate on the aggregated value:
+
+```php
 $posts = Post::raw(fn ($c) => $c->aggregate([
     ['$lookup' => [
         'from'         => 'comments',
@@ -51,6 +76,7 @@ $posts = Post::raw(fn ($c) => $c->aggregate([
     ]],
     ['$addFields' => ['comments_count' => ['$size' => '$comments']]],
     ['$project'   => ['comments' => 0]],
+    ['$sort'      => ['comments_count' => -1]],
 ]));
 ```
 

src/Eloquent/Builder.php

@@ -15,6 +15,7 @@
 use MongoDB\Driver\CursorInterface;
 use MongoDB\Driver\Exception\BulkWriteException;
 use MongoDB\Laravel\Connection;
+use MongoDB\Laravel\Helpers\QueriesRelationshipAggregates;
 use MongoDB\Laravel\Helpers\QueriesRelationships;
 use MongoDB\Laravel\Query\AggregationBuilder;
 use MongoDB\Model\BSONDocument;
@@ -38,6 +39,7 @@
 class Builder extends EloquentBuilder
 {
     use QueriesRelationships;
+    use QueriesRelationshipAggregates;
 
     private const DUPLICATE_KEY_ERROR = 11000;