PHPORM-206 Add model schema version feature

[florianJacques]

Added a feature for managing mongoDB document versioning.
The default key is "schema_version"
If the version is not specified, t is automatically set to 1

Usage

use MongoDB\Laravel\Eloquent\HasDocumentVersion;
use MongoDB\Laravel\Eloquent\Model as Eloquent;

/** @property int $schema_version */
class SchemaVersionned extends Eloquent
{
    use HasSchemaVersion;

    public const int SCHEMA_VERSION = 1;

    protected $connection       = 'mongodb';
    protected $collection       = 'documentVersion';
    protected static $unguarded = true;
}

For overwrite version key:

/** @property int $__v */
class DocumentVersion extends Eloquent
{
    use HasSchemaVersion;

    protected $connection       = 'mongodb';
    protected $collection       = 'documentVersion';
    protected static $unguarded = true;

    public static function getSchemaVersionKey(): string
    {
       return '__v';
    }
}

For update document version:

/** @property int $schema_version */
class DocumentVersion extends Eloquent
{
    use HasSchemaVersion;

    public const int SCHEMA_VERSION = 2;

    protected $connection       = 'mongodb';
    protected $collection       = 'documentVersion';
    protected static $unguarded = true;
}

• Add tests and ensure they pass
• Add an entry to the CHANGELOG.md file
• Update documentation for new features

[GromNaN]

Thanks for proposing this feature.

The ability to store documents with different schemas in the same collection is undoubtedly one of the great strengths of the MongoDB model. We have a tutorial on this subject.

I think there's a piece missing: the code to automatically update documents when they're read from the DB. This would probably be done in a listener of the retrieved event.

In the trait:

        static::retrieved(function (self $model) {
            $model->upgradeDocumentVersion($model, $model->{static::getDocumentVersionKey()} ?? 0);
        });

In the code would look like this (example for the docs):

    public function upgradeDocumentVersion(Model $document, int $fromVersion): void
    {
        switch (true) {
            case $fromVersion < 2:
                // Field renamed
                $document->newField = $document->oldField;
            // No break to apply all changes
            case $fromVersion < 3:
                // Field type updated
                $document->price = (float) $document->price;
            // ...
        }
    }

[GromNaN]

Why do you need this public method? All this code can be safely in the "retrieved" closure.

[florianJacques]

I think it's a good idea to let the user choose which method to use, between migrating + upgrading the version or migrating and upgrading the version later.

[GromNaN]

@florianJacques I updated the implementation so that

• the SCHEMA_VERSION constant is required
• the tests ensure the documents are updated when retrieved
• adding documentation in the trait description

[florianJacques]

I don't think this is the best solution, do you have any ideas?

[florianJacques]

I think we need to find a way to give control over the call to this function

[florianJacques]

I think it's a good idea to let the user choose which method to use, between migrating + upgrading the version or migrating and upgrading the version later.

[florianJacques]

Thanks for your work !

[GromNaN]

Thank you @florianJacques