Merge branch '4.3' into merge-4.2-into-4.3-1712671033107

Author: GromNaN

CHANGELOG.md

@@ -3,8 +3,10 @@ All notable changes to this project will be documented in this file.
 
 ## [unreleased]
 
+* New aggregation pipeline builder by @GromNaN in [#2738](https://github.com/mongodb/laravel-mongodb/pull/2738)
+* Drop support for Composer 1.x by @GromNaN in [#2784](https://github.com/mongodb/laravel-mongodb/pull/2784)
 
-## [4.2.0] - 2024-12-14
+## [4.2.0] - 2024-03-14
 
 * Add support for Laravel 11 by @GromNaN in [#2735](https://github.com/mongodb/laravel-mongodb/pull/2735)
 * Implement Model::createOrFirst() using findOneAndUpdate operation by @GromNaN in [#2742](https://github.com/mongodb/laravel-mongodb/pull/2742)

composer.json

@@ -24,20 +24,25 @@
     "require": {
         "php": "^8.1",
         "ext-mongodb": "^1.15",
+        "composer-runtime-api": "^2.0.0",
         "illuminate/support": "^10.0|^11",
         "illuminate/container": "^10.0|^11",
         "illuminate/database": "^10.30|^11",
         "illuminate/events": "^10.0|^11",
         "mongodb/mongodb": "^1.15"
     },
     "require-dev": {
+        "mongodb/builder": "^0.2",
         "phpunit/phpunit": "^10.3",
         "orchestra/testbench": "^8.0|^9.0",
         "mockery/mockery": "^1.4.4",
         "doctrine/coding-standard": "12.0.x-dev",
         "spatie/laravel-query-builder": "^5.6",
         "phpstan/phpstan": "^1.10"
     },
+    "suggest": {
+        "mongodb/builder": "Provides a fluent aggregation builder for MongoDB pipelines"
+    },
     "minimum-stability": "dev",
     "replace": {
         "jenssegers/mongodb": "self.version"

src/Connection.php

@@ -16,7 +16,6 @@
 use MongoDB\Laravel\Concerns\ManagesTransactions;
 use Throwable;
 
-use function class_exists;
 use function filter_var;
 use function implode;
 use function is_array;
@@ -324,14 +323,10 @@ private static function getVersion(): string
 
     private static function lookupVersion(): string
     {
-        if (class_exists(InstalledVersions::class)) {
-            try {
-                return self::$version = InstalledVersions::getPrettyVersion('mongodb/laravel-mongodb');
-            } catch (Throwable) {
-                return self::$version = 'error';
-            }
+        try {
+            return self::$version = InstalledVersions::getPrettyVersion('mongodb/laravel-mongodb') ?? 'unknown';
+        } catch (Throwable) {
+            return self::$version = 'error';
         }
-
-        return self::$version = 'unknown';
     }
 }

src/Eloquent/Builder.php

@@ -11,6 +11,7 @@
 use MongoDB\Laravel\Collection;
 use MongoDB\Laravel\Helpers\QueriesRelationships;
 use MongoDB\Laravel\Internal\FindAndModifyCommandSubscriber;
+use MongoDB\Laravel\Query\AggregationBuilder;
 use MongoDB\Model\BSONDocument;
 use MongoDB\Operation\FindOneAndUpdate;
 
@@ -56,6 +57,18 @@ class Builder extends EloquentBuilder
         'tomql',
     ];
 
+    /**
+     * @return ($function is null ? AggregationBuilder : self)
+     *
+     * @inheritdoc
+     */
+    public function aggregate($function = null, $columns = ['*'])
+    {
+        $result = $this->toBase()->aggregate($function, $columns);
+
+        return $result ?: $this;
+    }
+
     /** @inheritdoc */
     public function update(array $values, array $options = [])
     {
@@ -215,7 +228,7 @@ public function createOrFirst(array $attributes = [], array $values = []): Model
                 $document = $collection->findOneAndUpdate(
                     $attributes,
                     // Before MongoDB 5.0, $setOnInsert requires a non-empty document.
-                    // This is should not be an issue as $values includes the query filter.
+                    // This should not be an issue as $values includes the query filter.
                     ['$setOnInsert' => (object) $values],
                     [
                         'upsert' => true,

src/Eloquent/Model.php

@@ -49,6 +49,7 @@
 use function uniqid;
 use function var_export;
 
+/** @mixin Builder */
 abstract class Model extends BaseModel
 {
     use HybridRelations;

src/Query/AggregationBuilder.php

@@ -0,0 +1,98 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MongoDB\Laravel\Query;
+
+use Illuminate\Support\Collection as LaravelCollection;
+use Illuminate\Support\LazyCollection;
+use InvalidArgumentException;
+use Iterator;
+use MongoDB\Builder\BuilderEncoder;
+use MongoDB\Builder\Stage\FluentFactoryTrait;
+use MongoDB\Collection as MongoDBCollection;
+use MongoDB\Driver\CursorInterface;
+use MongoDB\Laravel\Collection as LaravelMongoDBCollection;
+
+use function array_replace;
+use function collect;
+use function sprintf;
+use function str_starts_with;
+
+class AggregationBuilder
+{
+    use FluentFactoryTrait;
+
+    public function __construct(
+        private MongoDBCollection|LaravelMongoDBCollection $collection,
+        private readonly array $options = [],
+    ) {
+    }
+
+    /**
+     * Add a stage without using the builder. Necessary if the stage is built
+     * outside the builder, or it is not yet supported by the library.
+     */
+    public function addRawStage(string $operator, mixed $value): static
+    {
+        if (! str_starts_with($operator, '$')) {
+            throw new InvalidArgumentException(sprintf('The stage name "%s" is invalid. It must start with a "$" sign.', $operator));
+        }
+
+        $this->pipeline[] = [$operator => $value];
+
+        return $this;
+    }
+
+    /**
+     * Execute the aggregation pipeline and return the results.
+     */
+    public function get(array $options = []): LaravelCollection|LazyCollection
+    {
+        $cursor = $this->execute($options);
+
+        return collect($cursor->toArray());
+    }
+
+    /**
+     * Execute the aggregation pipeline and return the results in a lazy collection.
+     */
+    public function cursor($options = []): LazyCollection
+    {
+        $cursor = $this->execute($options);
+
+        return LazyCollection::make(function () use ($cursor) {
+            foreach ($cursor as $item) {
+                yield $item;
+            }
+        });
+    }
+
+    /**
+     * Execute the aggregation pipeline and return the first result.
+     */
+    public function first(array $options = []): mixed
+    {
+        return (clone $this)
+            ->limit(1)
+            ->get($options)
+            ->first();
+    }
+
+    /**
+     * Execute the aggregation pipeline and return MongoDB cursor.
+     */
+    private function execute(array $options): CursorInterface&Iterator
+    {
+        $encoder = new BuilderEncoder();
+        $pipeline = $encoder->encode($this->getPipeline());
+
+        $options = array_replace(
+            ['typeMap' => ['root' => 'array', 'document' => 'array']],
+            $this->options,
+            $options,
+        );
+
+        return $this->collection->aggregate($pipeline, $options);
+    }
+}

src/Query/Builder.php

@@ -21,6 +21,7 @@
 use MongoDB\BSON\ObjectID;
 use MongoDB\BSON\Regex;
 use MongoDB\BSON\UTCDateTime;
+use MongoDB\Builder\Stage\FluentFactoryTrait;
 use MongoDB\Driver\Cursor;
 use Override;
 use RuntimeException;
@@ -65,6 +66,7 @@
 use function strlen;
 use function strtolower;
 use function substr;
+use function trait_exists;
 use function var_export;
 
 class Builder extends BaseBuilder
@@ -74,7 +76,7 @@ class Builder extends BaseBuilder
     /**
      * The database collection.
      *
-     * @var \MongoDB\Collection
+     * @var \MongoDB\Laravel\Collection
      */
     protected $collection;
 
@@ -83,7 +85,7 @@ class Builder extends BaseBuilder
      *
      * @var array
      */
-    public $projections;
+    public $projections = [];
 
     /**
      * The maximum amount of seconds to allow the query to run.
@@ -538,9 +540,26 @@ public function generateCacheKey()
         return md5(serialize(array_values($key)));
     }
 
-    /** @inheritdoc */
-    public function aggregate($function, $columns = [])
+    /** @return ($function is null ? AggregationBuilder : mixed) */
+    public function aggregate($function = null, $columns = ['*'])
     {
+        if ($function === null) {
+            if (! trait_exists(FluentFactoryTrait::class)) {
+                // This error will be unreachable when the mongodb/builder package will be merged into mongodb/mongodb
+                throw new BadMethodCallException('Aggregation builder requires package mongodb/builder 0.2+');
+            }
+
+            if ($columns !== ['*']) {
+                throw new InvalidArgumentException('Columns cannot be specified to create an aggregation builder. Add a $project stage instead.');
+            }
+
+            if ($this->wheres) {
+                throw new BadMethodCallException('Aggregation builder does not support previous query-builder instructions. Use a $match stage instead.');
+            }
+
+            return new AggregationBuilder($this->collection, $this->options);
+        }
+
         $this->aggregate = [
             'function' => $function,
             'columns' => $columns,