Merge branch '4.2' into merge-4.1-into-4.2-1716209338791

Author: GromNaN

.github/workflows/build-ci.yml

@@ -24,12 +24,22 @@ jobs:
                     - "8.2"
                     - "8.3"
                 laravel:
-                  - "10.*"
+                    - "10.*"
+                    - "11.*"
                 include:
                     - php: "8.1"
                       laravel: "10.*"
                       mongodb: "5.0"
                       mode: "low-deps"
+                      os: "ubuntu-latest"
+                    - php: "8.4"
+                      laravel: "11.*"
+                      mongodb: "7.0"
+                      mode: "ignore-php-req"
+                      os: "ubuntu-latest"
+                exclude:
+                    - php: "8.1"
+                      laravel: "11.*"
 
         steps:
             -   uses: "actions/checkout@v4"
@@ -76,8 +86,10 @@ jobs:
                     restore-keys: "${{ matrix.os }}-composer-"
 
             -   name: "Install dependencies"
-                run: composer update --no-interaction $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest --prefer-stable')
-
+                run: |
+                  composer update --no-interaction \
+                    $([[ "${{ matrix.mode }}" == low-deps ]] && echo ' --prefer-lowest') \
+                    $([[ "${{ matrix.mode }}" == ignore-php-req ]] && echo ' --ignore-platform-req=php+')
             -   name: "Run tests"
                 run: "./vendor/bin/phpunit --coverage-clover coverage.xml"
                 env:

CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [4.2.2] - 2024-04-25
+
+* Add return types to `FindAndModifyCommandSubscriber`, used by `firstOrCreate` by @wivaku in [#2913](https://github.com/mongodb/laravel-mongodb/pull/2913)
+
+## [4.2.1] - 2024-04-25
+
+* Set timestamps when using `Model::createOrFirst()` by @GromNaN in [#2905](https://github.com/mongodb/laravel-mongodb/pull/2905)
+
+## [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)
+
 ## [4.1.3] - 2024-03-05
 
 * Fix the timezone of `datetime` fields when they are read from the database. By @GromNaN in [#2739](https://github.com/mongodb/laravel-mongodb/pull/2739)

composer.json

@@ -24,20 +24,21 @@
     "require": {
         "php": "^8.1",
         "ext-mongodb": "^1.15",
-        "illuminate/support": "^10.0",
-        "illuminate/container": "^10.0",
-        "illuminate/database": "^10.30",
-        "illuminate/events": "^10.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": {
         "phpunit/phpunit": "^10.3",
-        "orchestra/testbench": "^8.0",
+        "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"
     },
+    "minimum-stability": "dev",
     "replace": {
         "jenssegers/mongodb": "self.version"
     },
@@ -66,9 +67,6 @@
         "cs:fix": "phpcbf"
     },
     "config": {
-        "platform": {
-            "php": "8.1"
-        },
         "allow-plugins": {
             "dealerdirect/phpcodesniffer-composer-installer": true
         }

docs/eloquent-models/model-class.txt

@@ -194,6 +194,24 @@ type, to the Laravel ``datetime`` type.
    :emphasize-lines: 9-11
    :dedent:
 
+.. tip:: Casts in Laravel 11
+
+   In Laravel 11, you can define a ``casts()`` method to specify data type conversions
+   instead of using the ``$casts`` attribute. The following code performs the same
+   conversion as the preceding example by using a ``casts()`` method:
+
+   .. code-block:: php
+
+      protected function casts(): array
+      {
+         return [
+            'discovery_dt' => 'datetime',
+         ];
+      }
+   
+   To learn more, see `Attribute Casting <https://laravel.com/docs/{+laravel-docs-version+}/eloquent-mutators#attribute-casting>`__
+   in the Laravel documentation.
+   
 This conversion lets you use the PHP `DateTime <https://www.php.net/manual/en/class.datetime.php>`__
 or the `Carbon class <https://carbon.nesbot.com/docs/>`__ to work with dates
 in this field. The following example shows a Laravel query that uses the

docs/fundamentals/read-operations.txt

@@ -383,7 +383,7 @@ documents.
             Runtime: 95
             IMDB Rating: 4
             IMDB Votes: 9296
-            Plot: A sci-fi update of the famous 6th Century poem. In a beseiged land, Beowulf must
+            Plot: A sci-fi update of the famous 6th Century poem. In a besieged land, Beowulf must
             battle against the hideous creature Grendel and his vengeance seeking mother.
 
 .. _laravel-sort:

docs/includes/framework-compatibility-laravel.rst

@@ -3,14 +3,21 @@
    :stub-columns: 1
 
    * - {+odm-short+} Version
+     - Laravel 11.x
      - Laravel 10.x
      - Laravel 9.x
 
+   * - 4.2
+     - ✓
+     - ✓
+     -
+
    * - 4.1
+     -
      - ✓
      -
 
    * - 4.0
+     -
      - ✓
      -
-

docs/quick-start.txt

@@ -53,7 +53,7 @@ that connects to a MongoDB deployment.
 .. tip::
 
    You can download the complete web application project by cloning the
-   `laravel-quickstart <https://github.com/mongodb-university/laravel-quickstart>`__
+   `laravel-quickstart <https://github.com/mongodb-university/laravel-quickstart/>`__
    GitHub repository.
 
 .. button:: Next: Download and Install

docs/quick-start/configure-mongodb.txt

@@ -73,13 +73,18 @@ Configure Your MongoDB Connection
 
    .. step:: Add the {+odm-short+} provider
 
-      Open the ``app.php`` file in the ``config`` directory and
-      add the following entry into the ``providers`` array:
+      Open the ``providers.php`` file in the ``bootstrap`` directory and add
+      the following entry into the array:
 
       .. code-block::
 
          MongoDB\Laravel\MongoDBServiceProvider::class,
 
+      .. tip::
+
+         To learn how to register the provider in Laravel 10.x, see
+         `Registering Providers <https://laravel.com/docs/10.x/providers#registering-providers>`__.
+
 After completing these steps, your Laravel web application is ready to
 connect to MongoDB.
 

docs/quick-start/view-data.txt

@@ -67,13 +67,13 @@ View MongoDB Data
 
          public function show()
          {
-           return view('browse_movies', [
-             'movies' => Movie::where('runtime', '<', 60)
-                ->where('imdb.rating', '>', 8.5)
-                ->orderBy('imdb.rating', 'desc')
-                ->take(10)
-                ->get()
-           ]);
+             return view('browse_movies', [
+                 'movies' => Movie::where('runtime', '<', 60)
+                     ->where('imdb.rating', '>', 8.5)
+                     ->orderBy('imdb.rating', 'desc')
+                     ->take(10)
+                     ->get()
+             ]);
          }
 
    .. step:: Add a web route

docs/quick-start/write-data.txt

@@ -32,6 +32,17 @@ Write Data to MongoDB
 
    .. step:: Add an API route that calls the controller function
 
+      Generate an API route file by running the following command:
+
+      .. code-block:: bash
+
+         php artisan install:api
+
+      .. tip::
+
+         Skip this step if you are using Laravel 10.x because the file that
+         the command generates already exists.
+
       Import the controller and add an API route that calls the ``store()``
       method in the ``routes/api.php`` file:
 
@@ -42,7 +53,7 @@ Write Data to MongoDB
          // ...
 
          Route::resource('movies', MovieController::class)->only([
-           'store'
+             'store'
          ]);
 
 
@@ -57,8 +68,8 @@ Write Data to MongoDB
 
          class Movie extends Model
          {
-            protected $connection = 'mongodb';
-            protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot'];
+              protected $connection = 'mongodb';
+              protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot'];
          }
 
    .. step:: Post a request to the API

src/Connection.php

@@ -328,7 +328,7 @@ private static function lookupVersion(): string
             try {
                 return self::$version = InstalledVersions::getPrettyVersion('mongodb/laravel-mongodb');
             } catch (Throwable) {
-                // Ignore exceptions and return unknown version
+                return self::$version = 'error';
             }
         }
 

src/Eloquent/Builder.php

@@ -6,10 +6,15 @@
 
 use Illuminate\Database\ConnectionInterface;
 use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
+use InvalidArgumentException;
 use MongoDB\Driver\Cursor;
+use MongoDB\Laravel\Collection;
 use MongoDB\Laravel\Helpers\QueriesRelationships;
+use MongoDB\Laravel\Internal\FindAndModifyCommandSubscriber;
 use MongoDB\Model\BSONDocument;
+use MongoDB\Operation\FindOneAndUpdate;
 
+use function array_intersect_key;
 use function array_key_exists;
 use function array_merge;
 use function collect;
@@ -183,6 +188,58 @@ public function raw($value = null)
         return $results;
     }
 
+    /**
+     * Attempt to create the record if it does not exist with the matching attributes.
+     * If the record exists, it will be returned.
+     *
+     * @param  array $attributes The attributes to check for duplicate records
+     * @param  array $values     The attributes to insert if no matching record is found
+     */
+    public function createOrFirst(array $attributes = [], array $values = []): Model
+    {
+        if ($attributes === []) {
+            throw new InvalidArgumentException('You must provide attributes to check for duplicates');
+        }
+
+        // Apply casting and default values to the attributes
+        // In case of duplicate key between the attributes and the values, the values have priority
+        $instance = $this->newModelInstance($values + $attributes);
+
+        /* @see \Illuminate\Database\Eloquent\Model::performInsert */
+        if ($instance->usesTimestamps()) {
+            $instance->updateTimestamps();
+        }
+
+        $values = $instance->getAttributes();
+        $attributes = array_intersect_key($attributes, $values);
+
+        return $this->raw(function (Collection $collection) use ($attributes, $values) {
+            $listener = new FindAndModifyCommandSubscriber();
+            $collection->getManager()->addSubscriber($listener);
+
+            try {
+                $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.
+                    ['$setOnInsert' => (object) $values],
+                    [
+                        'upsert' => true,
+                        'returnDocument' => FindOneAndUpdate::RETURN_DOCUMENT_AFTER,
+                        'typeMap' => ['root' => 'array', 'document' => 'array'],
+                    ],
+                );
+            } finally {
+                $collection->getManager()->removeSubscriber($listener);
+            }
+
+            $model = $this->model->newFromBuilder($document);
+            $model->wasRecentlyCreated = $listener->created;
+
+            return $model;
+        });
+    }
+
     /**
      * Add the "updated at" column to an array of values.
      * TODO Remove if https://github.com/laravel/framework/commit/6484744326531829341e1ff886cc9b628b20d73e

src/Eloquent/Model.php

@@ -4,6 +4,7 @@
 
 namespace MongoDB\Laravel\Eloquent;
 
+use BackedEnum;
 use Carbon\CarbonInterface;
 use DateTimeInterface;
 use DateTimeZone;
@@ -23,6 +24,7 @@
 use MongoDB\BSON\UTCDateTime;
 use MongoDB\Laravel\Query\Builder as QueryBuilder;
 use Stringable;
+use ValueError;
 
 use function array_key_exists;
 use function array_keys;
@@ -40,10 +42,12 @@
 use function is_string;
 use function ltrim;
 use function method_exists;
+use function sprintf;
 use function str_contains;
 use function str_starts_with;
 use function strcmp;
 use function uniqid;
+use function var_export;
 
 abstract class Model extends BaseModel
 {
@@ -695,7 +699,7 @@ protected function addCastAttributesToArray(array $attributes, array $mutatedAtt
             }
 
             if ($this->isEnumCastable($key) && (! $castValue instanceof Arrayable)) {
-                $castValue = $castValue !== null ? $this->getStorableEnumValue($castValue) : null;
+                $castValue = $castValue !== null ? $this->getStorableEnumValueFromLaravel11($this->getCasts()[$key], $castValue) : null;
             }
 
             if ($castValue instanceof Arrayable) {
@@ -708,6 +712,23 @@ protected function addCastAttributesToArray(array $attributes, array $mutatedAtt
         return $attributes;
     }
 
+    /**
+     * Duplicate of {@see HasAttributes::getStorableEnumValue()} for Laravel 11 as the signature of the method has
+     * changed in a non-backward compatible way.
+     *
+     * @todo Remove this method when support for Laravel 10 is dropped.
+     */
+    private function getStorableEnumValueFromLaravel11($expectedEnum, $value)
+    {
+        if (! $value instanceof $expectedEnum) {
+            throw new ValueError(sprintf('Value [%s] is not of the expected enum type [%s].', var_export($value, true), $expectedEnum));
+        }
+
+        return $value instanceof BackedEnum
+            ? $value->value
+            : $value->name;
+    }
+
     /**
      * Is a value a BSON type?
      *