Use a constant to store SCHEMA_VERSION

Author: GromNaN

src/Eloquent/HasSchemaVersion.php

@@ -4,75 +4,79 @@
 
 namespace MongoDB\Laravel\Eloquent;
 
-trait HasSchemaVersion
-{
-    public int $currentSchemaVersion = 1;
+use Error;
+use LogicException;
 
-    /**
-     * Auto call on model instance as booting
-     *
-     * @return void
-     */
-    public static function bootHasSchemaVersion(): void
-    {
-        static::saving(function ($model) {
-          if (!$model->getSchemaVersion()) {
-              $model->setSchemaVersion($model->currentSchemaVersion);
-          }
-        });
-
-        static::retrieved(function ($model) {
-            $model->upgradeSchemaVersion();
-        });
-    }
+use function sprintf;
 
+/**
+ * Use this trait to implement schema versioning in your models. The document
+ * is updated automatically when its schema version retrieved from the database
+ * is lower than the current schema version of the model.
+ *
+ *     class MyVersionedModel extends Model
+ *     {
+ *         use HasSchemaVersion;
+ *
+ *         public const int SCHEMA_VERSION = 1;
+ *
+ *         public function migrateSchema(int $fromVersion): void
+ *         {
+ *             // Your logic to update the document to the current schema version
+ *         }
+ *     }
+ *
+ * @see https://www.mongodb.com/docs/manual/tutorial/model-data-for-schema-versioning/
+ *
+ * Requires PHP 8.2+
+ */
+trait HasSchemaVersion
+{
     /**
-     * Migrate document to the current schema version.
+     * This method should be implemented in the model to migrate a document from
+     * an older schema version to the current schema version.
      */
     public function migrateSchema(int $fromVersion): void
     {
     }
 
-    /**
-     * migrate schema and set current model version
-     * @return void
-     */
-    public function upgradeSchemaVersion(): void
+    public static function bootHasSchemaVersion(): void
     {
-        $version = $this->getSchemaVersion();
+        static::saving(function ($model) {
+            if ($model->getAttribute($model::getSchemaVersionKey()) === null) {
+                $model->setAttribute($model::getSchemaVersionKey(), $model->getModelSchemaVersion());
+            }
+        });
 
-        if ($version && $version < $this->currentSchemaVersion) {
-            $this->migrateSchema($version);
-            $this->setSchemaVersion($this->currentSchemaVersion);
-        }
+        static::retrieved(function (self $model) {
+            $version = $model->getSchemaVersion();
+
+            if ($version < $model->getModelSchemaVersion()) {
+                $model->migrateSchema($version);
+                $model->setAttribute($model::getSchemaVersionKey(), $model->getModelSchemaVersion());
+            }
+        });
     }
 
     /**
-     * Get Current document version
-     *
-     * @return int
+     * Get Current document version, fallback to 0 if not set
      */
     public function getSchemaVersion(): int
     {
         return $this->{static::getSchemaVersionKey()} ?? 0;
     }
 
-    /**
-     * @param int $version
-     * @return void
-     */
-    public function setSchemaVersion(int $version): void
+    protected static function getSchemaVersionKey(): string
     {
-        $this->{static::getSchemaVersionKey()} = $version;
+        return 'schema_version';
     }
 
-    /**
-     * Get document version key
-     *
-     * @return string
-     */
-    public static function getSchemaVersionKey(): string
+    protected function getModelSchemaVersion(): int
     {
-       return 'schema_version';
+        try {
+            return $this::SCHEMA_VERSION;
+        } catch (Error) {
+            throw new LogicException(sprintf('Constant %s::SCHEMA_VERSION is required when using HasSchemaVersion', $this::class));
+        }
     }
 }

tests/Models/SchemaVersion.php

@@ -11,18 +11,16 @@ class SchemaVersion extends Eloquent
 {
     use HasSchemaVersion;
 
+    public const SCHEMA_VERSION = 2;
+
     protected $connection       = 'mongodb';
     protected $collection       = 'documentVersion';
     protected static $unguarded = true;
 
-    public function migrateSchema($fromVersion): void
+    public function migrateSchema(int $fromVersion): void
     {
-        if ($fromVersion) {
-            if ($fromVersion < 2) {
-                $this->age = 35;
-
-                $this->setSchemaVersion(2);
-            }
+        if ($fromVersion < 2) {
+            $this->age = 35;
         }
     }
 }

tests/SchemaVersionTest.php

@@ -4,8 +4,11 @@
 
 namespace MongoDB\Laravel\Tests;
 
+use Illuminate\Support\Facades\DB;
+use LogicException;
+use MongoDB\Laravel\Eloquent\HasSchemaVersion;
+use MongoDB\Laravel\Eloquent\Model;
 use MongoDB\Laravel\Tests\Models\SchemaVersion;
-use MongoDB\Laravel\Tests\Models\User;
 
 class SchemaVersionTest extends TestCase
 {
@@ -20,26 +23,36 @@ public function testWithBasicDocument()
         $this->assertEmpty($document->getSchemaVersion());
         $document->save();
 
-        $this->assertEquals(1, $document->getSchemaVersion());
-        $this->assertNull($document->age);
-
-        $document->currentSchemaVersion = 2;
-        $document->migrateSchema($document->getSchemaVersion());
+        // The current schema version of the model is stored by default
+        $this->assertEquals(2, $document->getSchemaVersion());
 
-        $this->assertEquals(35, $document->age);
+        // Test automatic migration
+        SchemaVersion::insert([
+            ['name' => 'Vador', 'schema_version' => 1],
+        ]);
+        $document = SchemaVersion::where('name', 'Vador')->first();
         $this->assertEquals(2, $document->getSchemaVersion());
+        $this->assertEquals(35, $document->age);
+
+        $document->save();
 
-        // Test without migration
-        $newDocument = new SchemaVersion(['name' => 'Vador']);
-        $newDocument->setSchemaVersion(2);
-        $newDocument->save();
-        $newDocument->currentSchemaVersion = 2;
-        $newDocument->migrateSchema($newDocument->getSchemaVersion());
+        // The migrated version is saved
+        $data = DB::connection('mongodb')
+            ->collection('documentVersion')
+            ->where('name', 'Vador')
+            ->get();
 
-        $this->assertEquals(2, $newDocument->getSchemaVersion());
-        $this->assertNull($newDocument->age);
+        $this->assertEquals(2, $data[0]['schema_version']);
+    }
 
-        $newDocument = SchemaVersion::query()->where('name', 'Vador')->first();
-        $this->assertNull($newDocument->age);
+    public function testIncompleteImplementation(): void
+    {
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('::SCHEMA_VERSION is required when using HasSchemaVersion');
+        $document = new class extends Model {
+            use HasSchemaVersion;
+        };
+
+        $document->save();
     }
 }