Draft notes after a first review of the full code

README.md

@@ -1179,6 +1179,7 @@ class Message extends Model
 
 ### Authentication
 
+// Could be simplified if we get rid of the custom PasswordResetServiceProvider
 If you want to use Laravel's native Auth functionality, register this included service provider:
 
 ```php

composer.json

@@ -19,6 +19,7 @@
     ],
     "license": "MIT",
     "require": {
+        "ext-mongodb": "*",
         "illuminate/support": "^10.0",
         "illuminate/container": "^10.0",
         "illuminate/database": "^10.0",

phpunit.xml.dist

@@ -38,7 +38,7 @@
         </testsuite>
     </testsuites>
     <php>
-        <env name="MONGODB_URI" value="mongodb://mongodb/" />
+        <env name="MONGODB_URI" value="mongodb://127.0.0.1:27017/?serverSelectionTimeoutMS=100"/>
         <env name="MONGODB_DATABASE" value="unittest"/>
         <env name="MYSQL_HOST" value="mysql"/>
         <env name="MYSQL_PORT" value="3306"/>

src/Auth/DatabaseTokenRepository.php

@@ -18,6 +18,7 @@ protected function getPayload($email, $token)
         return [
             'email' => $email,
             'token' => $this->hasher->make($token),
+            // why is it necessary ? vs "new Carbon" in parent class
             'created_at' => new UTCDateTime(Date::now()->format('Uv')),
         ];
     }
@@ -27,6 +28,7 @@ protected function getPayload($email, $token)
      */
     protected function tokenExpired($createdAt)
     {
+        // Could be removed if Carbon was natively suported?
         $createdAt = $this->convertDateTime($createdAt);
 
         return parent::tokenExpired($createdAt);

src/Connection.php

@@ -112,7 +112,8 @@ public function getSchemaBuilder()
      *
      * @return Database
      */
-    public function getMongoDB()
+    // Should be named getDatabase ?
+    public function getDatabase()
     {
         return $this->db;
     }
@@ -132,7 +133,7 @@ public function getMongoClient()
      */
     public function getDatabaseName()
     {
-        return $this->getMongoDB()->getDatabaseName();
+        return $this->getDatabase()->getDatabaseName();
     }
 
     /**
@@ -147,6 +148,7 @@ public function getDatabaseName()
     protected function getDefaultDatabaseName(string $dsn, array $config): string
     {
         if (empty($config['database'])) {
+            // Use parse_url() to get the database name from dsn
             if (preg_match('/^mongodb(?:[+]srv)?:\\/\\/.+\\/([^?&]+)/s', $dsn, $matches)) {
                 $config['database'] = $matches[1];
             } else {
@@ -195,6 +197,8 @@ protected function createConnection($dsn, array $config, array $options): Client
      */
     public function disconnect()
     {
+        // No need to explicitly disconnect?
+        // What appens if a reference to the connection is kept somewhere?
         unset($this->connection);
     }
 
@@ -260,6 +264,9 @@ protected function getDsn(array $config): string
     /**
      * @inheritdoc
      */
+    // Should be @internal because the parent method is protected
+    // and this method is use in Collection::__call
+    // Otherwise reimplement the method in Collection
     public function getElapsedTime($start)
     {
         return parent::getElapsedTime($start);
@@ -302,6 +309,8 @@ protected function getDefaultSchemaGrammar()
      *
      * @param  \MongoDB\Database  $db
      */
+    // 1 more reason to rename getMongoDB to getDatabase, for consistency with the setter
+    // this is not used in the codebase, use-case may be challenged as it allows to by-pass the connection
     public function setDatabase(\MongoDB\Database $db)
     {
         $this->db = $db;

src/Eloquent/EmbedsRelations.php

@@ -6,6 +6,7 @@
 use Jenssegers\Mongodb\Relations\EmbedsMany;
 use Jenssegers\Mongodb\Relations\EmbedsOne;
 
+// Documentation ?
 trait EmbedsRelations
 {
     /**
@@ -23,7 +24,8 @@ protected function embedsMany($related, $localKey = null, $foreignKey = null, $r
         // the calling method's name and use that as the relationship name as most
         // of the time this will be what we desire to use for the relationships.
         if ($relation === null) {
-            [, $caller] = debug_backtrace(false);
+            // Black magic. The call may be optimized to get only the method name.
+            [, $caller] = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
 
             $relation = $caller['function'];
         }
@@ -58,7 +60,8 @@ protected function embedsOne($related, $localKey = null, $foreignKey = null, $re
         // the calling method's name and use that as the relationship name as most
         // of the time this will be what we desire to use for the relationships.
         if ($relation === null) {
-            [, $caller] = debug_backtrace(false);
+            // Black magic. The call may be optimized to get only the method name.
+            [, $caller] = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
 
             $relation = $caller['function'];
         }

src/Eloquent/HybridRelations.php

@@ -12,6 +12,7 @@
 use Jenssegers\Mongodb\Relations\MorphMany;
 use Jenssegers\Mongodb\Relations\MorphTo;
 
+// Documentation ?
 trait HybridRelations
 {
     /**
@@ -134,7 +135,7 @@ public function belongsTo($related, $foreignKey = null, $otherKey = null, $relat
         // the calling method's name and use that as the relationship name as most
         // of the time this will be what we desire to use for the relationships.
         if ($relation === null) {
-            [$current, $caller] = debug_backtrace(false, 2);
+            [, $caller] = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
 
             $relation = $caller['function'];
         }
@@ -178,7 +179,7 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null
         // since that is most likely the name of the polymorphic interface. We can
         // use that to get both the class and foreign key that will be utilized.
         if ($name === null) {
-            [$current, $caller] = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
+            [, $caller] = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
 
             $name = $caller['function'];
         }

src/Eloquent/Model.php

@@ -2,6 +2,7 @@
 
 namespace Jenssegers\Mongodb\Eloquent;
 
+use Carbon\CarbonInterface;
 use function array_key_exists;
 use DateTimeInterface;
 use function explode;
@@ -86,6 +87,8 @@ public function getQualifiedKeyName()
 
     /**
      * @inheritdoc
+     *
+     * @return UTCDateTime
      */
     public function fromDateTime($value)
     {
@@ -104,6 +107,8 @@ public function fromDateTime($value)
 
     /**
      * @inheritdoc
+     *
+     * @param UTCDateTime|CarbonInterface|DateTimeInterface|int|string $value
      */
     protected function asDateTime($value)
     {
@@ -151,7 +156,7 @@ public function getTable()
     public function getAttribute($key)
     {
         if (! $key) {
-            return;
+            return null;
         }
 
         // Dot notation support.