Merge branch '5.0' into PHPORM-234

Author: GromNaN

Diff for: .github/PULL_REQUEST_TEMPLATE.md

@@ -7,4 +7,3 @@ This will help reviewers and should be a good start for the documentation.
 
 - [ ] Add tests and ensure they pass
 - [ ] Add an entry to the CHANGELOG.md file
-- [ ] Update documentation for new features

Diff for: CHANGELOG.md

@@ -5,7 +5,8 @@ All notable changes to this project will be documented in this file.
 
 * **BREAKING CHANGE** Use `id` as an alias for `_id` in commands and queries for compatibility with Eloquent packages by @GromNaN in [#3040](https://github.com/mongodb/laravel-mongodb/pull/3040)
 * **BREAKING CHANGE** Make Query\Builder return objects instead of array to match Laravel behavior by @GromNaN in [#3107](https://github.com/mongodb/laravel-mongodb/pull/3107)
-* **BREAKING CHANGE** Convert BSON `UTCDateTime` objects into `Carbon` date in query results by @GromNaN in [#3119](https://github.com/mongodb/laravel-mongodb/pull/3119)
+* **BREAKING CHANGE** In DB query results, convert BSON `UTCDateTime` objects into `Carbon` date with the default timezone by @GromNaN in [#3119](https://github.com/mongodb/laravel-mongodb/pull/3119)
+* Remove `MongoFailedJobProvider`, replaced by Laravel `DatabaseFailedJobProvider` by @GromNaN in [#3122](https://github.com/mongodb/laravel-mongodb/pull/3122)
 
 ## [4.8.0] - 2024-08-27
 

Diff for: docs/includes/auth/AppServiceProvider.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Providers;
+
+use Illuminate\Support\ServiceProvider;
+use MongoDB\Laravel\Passport\AuthCode;
+use MongoDB\Laravel\Passport\Client;
+use MongoDB\Laravel\Passport\PersonalAccessClient;
+use MongoDB\Laravel\Passport\RefreshToken;
+use MongoDB\Laravel\Passport\Token;
+
+class AppServiceProvider extends ServiceProvider
+{
+    /**
+     * Register any application services.
+     */
+    public function register(): void
+    {
+    }
+
+    /**
+     * Bootstrap any application services.
+     */
+    public function boot(): void
+    {
+        Passport::useAuthCodeModel(AuthCode::class);
+        Passport::useClientModel(Client::class);
+        Passport::usePersonalAccessClientModel(PersonalAccessClient::class);
+        Passport::useRefreshTokenModel(RefreshToken::class);
+        Passport::useTokenModel(Token::class);
+    }
+}

Diff for: docs/includes/framework-compatibility-laravel.rst

@@ -7,7 +7,7 @@
      - Laravel 10.x
      - Laravel 9.x
 
-   * - 4.2 to 4.7
+   * - 4.2 to 4.8
      - ✓
      - ✓
      -

Diff for: docs/user-authentication.txt

@@ -107,6 +107,7 @@ This section describes how to use the following features to customize the MongoD
 authentication process:
 
 - :ref:`laravel-user-auth-sanctum`
+- :ref:`laravel-user-auth-passport`
 - :ref:`laravel-user-auth-reminders`
 
 .. _laravel-user-auth-sanctum:
@@ -154,6 +155,115 @@ in the Laravel Sanctum guide.
    To learn more about the ``DocumentModel`` trait, see
    :ref:`laravel-third-party-model` in the Eloquent Model Class guide.
 
+.. _laravel-user-auth-passport:
+
+Laravel Passport
+~~~~~~~~~~~~~~~~
+
+Laravel Passport is an OAuth 2.0 server implementation that offers
+API authentication for Laravel applications. Use Laravel Passport if
+your application requires OAuth2 support.
+
+.. tip::
+
+   To learn more about Laravel Passport and the OAuth 2.0 protocol, see
+   the following resources:
+
+   - `Laravel Passport <https://laravel.com/docs/{+laravel-docs-version+}/passport>`__ in the
+     Laravel documentation.
+
+   - `OAuth 2.0 <https://oauth.net/2/>`__ on the OAuth website.
+
+Install Laravel Passport
+````````````````````````
+
+To install Laravel Passport and run the database migrations required
+to store OAuth2 clients, run the following command from your project root:
+
+.. code-block:: bash
+
+   php artisan install:api --passport
+
+Next, navigate to your ``User`` model and add the ``Laravel\Passport\HasApiTokens``
+trait. This trait provides helper methods that allow you to inspect a user's
+authentication token and scopes. The following code shows how to add ``Laravel\Passport\HasApiTokens``
+to your ``app\Models\User.php`` file:
+
+.. code-block:: php
+
+   <?php
+
+   namespace App\Models;
+
+   use MongoDB\Laravel\Auth\User as Authenticatable;
+   use Laravel\Passport\HasApiTokens;
+
+   class User extends Authenticatable
+   {
+      use HasApiTokens;
+      ...
+   }
+
+Then, define an ``api`` authentication guard in your ``config\auth.php``
+file and set the ``driver`` option to ``passport``. This instructs your
+application to use Laravel Passport's ``TokenGuard`` class to authenticate
+API requests. The following example adds the ``api`` authentication guard
+to the ``guards`` array:
+
+.. code-block:: php
+   :emphasize-lines: 6-9
+
+   'guards' => [
+      'web' => [
+         'driver' => 'session',
+         'provider' => 'users',
+      ],
+      'api' => [
+         'driver' => 'passport',
+         'provider' => 'users',
+      ],
+   ],
+
+Use Laravel Passport with Laravel MongoDB
+`````````````````````````````````````````
+
+After installing Laravel Passport, you must enable Passport compatibility with MongoDB by
+defining custom {+odm-short+} models that extend the corresponding Passport models.
+To extend each Passport model class, include the ``DocumentModel`` trait in the custom models.
+You can define the following {+odm-short+} model classes:
+
+- ``MongoDB\Laravel\Passport\AuthCode``, which extends ``Laravel\Passport\AuthCode``
+- ``MongoDB\Laravel\Passport\Client``, which extends ``Laravel\Passport\Client``
+- ``MongoDB\Laravel\Passport\PersonalAccessClient``, which extends ``Laravel\Passport\PersonalAccessClient``
+- ``MongoDB\Laravel\Passport\RefreshToken``, which extends ``Laravel\Passport\RefreshToken``
+- ``MongoDB\Laravel\Passport\Token``, which extends ``Laravel\Passport\Token``
+
+The following example code extends the default ``Laravel\Passport\AuthCode``
+model class when defining a ``MongoDB\Laravel\Passport\AuthCode`` class and includes
+the ``DocumentModel`` trait:
+
+.. code-block:: php
+
+   class MongoDB\Laravel\Passport\AuthCode extends Laravel\Passport\AuthCode
+   {
+      use MongoDB\Laravel\Eloquent\DocumentModel;
+
+      protected $primaryKey = '_id';
+      protected $keyType = 'string';
+   }
+
+After defining custom models that extend each ``Laravel\Passport`` class, instruct
+Passport to use the models in the ``boot()`` method of your application's
+``App\Providers\AppServiceProvider`` class. The following example adds each custom
+model to the ``boot()`` method:
+
+.. literalinclude:: /includes/auth/AppServiceProvider.php
+   :language: php
+   :emphasize-lines: 26-30
+   :dedent:
+
+Then, you can use Laravel Passport and MongoDB in your application.
+
 .. _laravel-user-auth-reminders:
 
 Password Reminders 

Diff for: src/Eloquent/DocumentModel.php

@@ -100,7 +100,7 @@ public function getQualifiedKeyName()
     }
 
     /**
-     * Convert a DateTime to a storable UTCDateTime.
+     * Convert a DateTimeInterface (including Carbon) to a storable UTCDateTime.
      *
      * @see HasAttributes::fromDateTime()
      *
@@ -122,7 +122,7 @@ public function fromDateTime($value): UTCDateTime
     }
 
     /**
-     * Return a timestamp as DateTime object.
+     * Return a timestamp as Carbon object.
      *
      * @see HasAttributes::asDateTime()
      *

Diff for: src/MongoDBQueueServiceProvider.php

@@ -879,11 +879,11 @@ public function delete($id = null)
         $wheres  = $this->aliasIdForQuery($wheres);
         $options = $this->inheritConnectionOptions();
 
-        if (is_int($this->limit)) {
-            if ($this->limit !== 1) {
-                throw new LogicException(sprintf('Delete limit can be 1 or null (unlimited). Got %d', $this->limit));
-            }
-
+        /**
+         * Ignore the limit if it is set to more than 1, as it is not supported by the deleteMany method.
+         * Required for {@see DatabaseFailedJobProvider::prune()}
+         */
+        if ($this->limit === 1) {
             $result = $this->collection->deleteOne($wheres, $options);
         } else {
             $result = $this->collection->deleteMany($wheres, $options);
@@ -1666,13 +1666,13 @@ private function aliasIdForResult(array|object $values): array|object
                 if ($value instanceof UTCDateTime) {
                     $values[$key] = Date::instance($value->toDateTime())
                         ->setTimezone(new DateTimeZone(date_default_timezone_get()));
-                } elseif (is_array($value) || $value instanceof stdClass) {
+                } elseif (is_array($value) || is_object($value)) {
                     $values[$key] = $this->aliasIdForResult($value);
                 }
             }
         }
 
-        if ($values instanceof stdClass) {
+        if (is_object($values instanceof stdClass)) {
             if (property_exists($values, '_id') && ! property_exists($values, 'id')) {
                 $values->id = $values->_id;
                 //unset($values->_id);
@@ -1682,7 +1682,7 @@ private function aliasIdForResult(array|object $values): array|object
                 if ($value instanceof UTCDateTime) {
                     $values->{$key} = Date::instance($value->toDateTime())
                         ->setTimezone(new DateTimeZone(date_default_timezone_get()));
-                } elseif (is_array($value) || $value instanceof stdClass) {
+                } elseif (is_array($value) || is_object($value)) {
                     $values->{$key} = $this->aliasIdForResult($value);
                 }
             }