From 994e9560d04958f4bac3b57cff332f9822aea5a0 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 19 Jul 2024 13:33:21 -0400 Subject: [PATCH 1/6] DOCSP-41241: Laravel Sanctum (#3050) * DOCSP-41241: Laravel Sanctum * apply phpcbf formatting * edits * code edit, change depth * feedback * edits * JM tech review 1 --------- Co-authored-by: norareidy Co-authored-by: rustagir --- docs/includes/auth/PersonalAccessToken.php | 16 ++++++ docs/user-authentication.txt | 62 ++++++++++++++++++++-- 2 files changed, 74 insertions(+), 4 deletions(-) create mode 100644 docs/includes/auth/PersonalAccessToken.php diff --git a/docs/includes/auth/PersonalAccessToken.php b/docs/includes/auth/PersonalAccessToken.php new file mode 100644 index 000000000..2a3c5e29c --- /dev/null +++ b/docs/includes/auth/PersonalAccessToken.php @@ -0,0 +1,16 @@ +`__ +in the Laravel Sanctum guide. + +.. _laravel-user-auth-reminders: + +Password Reminders +~~~~~~~~~~~~~~~~~~ To add support for MongoDB-based password reminders, register the following service provider in your application: @@ -111,7 +165,7 @@ This service provider modifies the internal ``DatabaseReminderRepository`` to enable password reminders. Example -~~~~~~~ +``````` The following code updates the ``providers.php`` file in the ``bootstrap`` directory of a Laravel application to register the ``PasswordResetServiceProvider`` provider: From 4943bcccd0542eb244ca59c50dfadfba578081de Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 19 Jul 2024 14:49:34 -0400 Subject: [PATCH 2/6] DOCSP-41306: schema version trait (#3051) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * DOCSP-41306: schema version trait * MW PR fixes 1 * add test wip * add tests * apply phpcbf formatting * JM tech review 1 * error * comment style * Fix test, expose 2 models, lock laravel version to avoid breaking change * JM tech review 2 * fixes * revert database v * JM tech review 3 * JM tech review 4 --------- Co-authored-by: rustagir Co-authored-by: Jérôme Tamarelle --- docs/eloquent-models/model-class.txt | 101 +++++++++++++++++- .../eloquent-models/PlanetSchemaVersion1.php | 10 ++ .../eloquent-models/PlanetSchemaVersion2.php | 26 +++++ .../eloquent-models/SchemaVersionTest.php | 54 ++++++++++ 4 files changed, 190 insertions(+), 1 deletion(-) create mode 100644 docs/includes/eloquent-models/PlanetSchemaVersion1.php create mode 100644 docs/includes/eloquent-models/PlanetSchemaVersion2.php create mode 100644 docs/includes/eloquent-models/SchemaVersionTest.php diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index f1d1fbdda..ad5565abe 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -33,6 +33,8 @@ to {+odm-short+} models: - :ref:`laravel-model-customize` explains several model class customizations. - :ref:`laravel-model-pruning` shows how to periodically remove models that you no longer need. +- :ref:`laravel-schema-versioning` shows how to implement model schema + versioning. .. _laravel-model-define: @@ -67,7 +69,6 @@ This model is stored in the ``planets`` MongoDB collection. To learn how to specify the database name that your Laravel application uses, :ref:`laravel-quick-start-connect-to-mongodb`. - .. _laravel-authenticatable-model: Extend the Authenticatable Model @@ -333,3 +334,101 @@ models that the prune action deletes: :emphasize-lines: 5,10,12 :dedent: +.. _laravel-schema-versioning: + +Create a Versioned Model Schema +------------------------------- + +You can implement a schema versioning pattern into your application by +using the ``HasSchemaVersion`` trait on an Eloquent model. You might +choose to implement a schema version to organize or standardize a +collection that contains data with different schemas. + +.. tip:: + + To learn more about schema versioning, see the :manual:`Model Data for + Schema Versioning ` + tutorial in the {+server-docs-name+}. + +To use this feature with models that use MongoDB as a database, add the +``MongoDB\Laravel\Eloquent\HasSchemaVersion`` import to your model. +Then, set the ``SCHEMA_VERSION`` constant to ``1`` to set the first +schema version on your collection. If your collection evolves to contain +multiple schemas, you can update the value of the ``SCHEMA_VERSION`` +constant in subsequent model classes. + +When creating your model, you can define the ``migrateSchema()`` method +to specify a migration to the current schema version upon retrieving a +model. In this method, you can specify the changes to make to an older +model to update it to match the current schema version. + +When you save a model that does not have a schema version +specified, the ``HasSchemaVersion`` trait assumes that it follows the +latest schema version. When you retrieve a model that does not contain +the ``schema_version`` field, the trait assumes that its schema version +is ``0`` and performs the migration. + +Schema Versioning Example +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this sample situation, you are working with a collection that was +first modeled by the following class: + +.. literalinclude:: /includes/eloquent-models/PlanetSchemaVersion1.php + :language: php + :dedent: + +Now, you want to implement a new schema version on the collection. +You can define the new model class with the following behavior: + +- Implements the ``HasSchemaVersion`` trait and sets the current + ``SCHEMA_VERSION`` to ``2`` + +- Defines the ``migrateSchema()`` method to migrate models in which the + schema version is less than ``2`` to have a ``galaxy`` field that has a value + of ``'Milky Way'`` + +.. literalinclude:: /includes/eloquent-models/PlanetSchemaVersion2.php + :language: php + :emphasize-lines: 10,12,20 + :dedent: + +In the ``"WASP-39 b"`` document in the following code, the +``schema_version`` field value is less than ``2``. When you retrieve the +document, {+odm-short+} adds the ``galaxy`` field and updates the schema +version to the current version, ``2``. + +The ``"Saturn"`` document does not contain the ``schema_version`` field, +so {+odm-short+} assigns it the current schema version upon saving. + +Finally, the code retrieves the models from the collection to +demonstrate the changes: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/eloquent-models/SchemaVersionTest.php + :language: php + :dedent: + :start-after: begin-schema-version + :end-before: end-schema-version + + .. output:: + :language: none + :visible: false + + [ + { + "_id": ..., + "name": "WASP-39 b", + "type": "gas", + "galaxy": "Milky Way", + "schema_version": 2, + }, + { + "_id": ..., + "name": "Saturn", + "type": "gas", + "schema_version": 2, + } + ] diff --git a/docs/includes/eloquent-models/PlanetSchemaVersion1.php b/docs/includes/eloquent-models/PlanetSchemaVersion1.php new file mode 100644 index 000000000..d4cbff71b --- /dev/null +++ b/docs/includes/eloquent-models/PlanetSchemaVersion1.php @@ -0,0 +1,10 @@ +galaxy = 'Milky Way'; + } + } +} diff --git a/docs/includes/eloquent-models/SchemaVersionTest.php b/docs/includes/eloquent-models/SchemaVersionTest.php new file mode 100644 index 000000000..7bf54f679 --- /dev/null +++ b/docs/includes/eloquent-models/SchemaVersionTest.php @@ -0,0 +1,54 @@ + 'WASP-39 b', + 'type' => 'gas', + 'schema_version' => 1, + ], + ]); + + // Saves a document with no specified schema version + $saturn = Planet::create([ + 'name' => 'Saturn', + 'type' => 'gas', + ]); + + // Retrieves both models from the collection + $planets = Planet::where('type', 'gas') + ->get(); + // end-schema-version + + $this->assertCount(2, $planets); + + $p1 = Planet::where('name', 'Saturn')->first(); + + $this->assertEquals(2, $p1->schema_version); + + $p2 = Planet::where('name', 'WASP-39 b')->first(); + + $this->assertEquals(2, $p2->schema_version); + $this->assertEquals('Milky Way', $p2->galaxy); + } +} From 172c6e3aeccf7062be79fd75ab1deca38b039ae9 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 19 Jul 2024 16:09:21 -0400 Subject: [PATCH 3/6] DOCSP-41628: v4.7 docs version update (#3058) --- docs/includes/framework-compatibility-laravel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/framework-compatibility-laravel.rst b/docs/includes/framework-compatibility-laravel.rst index 281e931ac..608560dd1 100644 --- a/docs/includes/framework-compatibility-laravel.rst +++ b/docs/includes/framework-compatibility-laravel.rst @@ -7,7 +7,7 @@ - Laravel 10.x - Laravel 9.x - * - 4.2 to 4.6 + * - 4.2 to 4.7 - ✓ - ✓ - From b0c3a95f2a7ad14e5b8de2ca9b0bee4f16c112a1 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 23 Jul 2024 10:40:31 -0400 Subject: [PATCH 4/6] Messed up the base branch/merge - fix (#3065) --- docs/eloquent-models/model-class.txt | 46 ++++++++++++++++++- .../eloquent-models/PlanetThirdParty.php | 15 ++++++ docs/user-authentication.txt | 5 ++ 3 files changed, 64 insertions(+), 2 deletions(-) create mode 100644 docs/includes/eloquent-models/PlanetThirdParty.php diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt index ad5565abe..9d38fe1a7 100644 --- a/docs/eloquent-models/model-class.txt +++ b/docs/eloquent-models/model-class.txt @@ -30,7 +30,10 @@ to {+odm-short+} models: - :ref:`laravel-model-define` demonstrates how to create a model class. - :ref:`laravel-authenticatable-model` shows how to set MongoDB as the authentication user provider. -- :ref:`laravel-model-customize` explains several model class customizations. +- :ref:`laravel-model-customize` explains several model class + customizations. +- :ref:`laravel-third-party-model` explains how to make third-party + model classes compatible with MongoDB. - :ref:`laravel-model-pruning` shows how to periodically remove models that you no longer need. - :ref:`laravel-schema-versioning` shows how to implement model schema @@ -180,7 +183,7 @@ in the Laravel docs. .. _laravel-model-cast-data-types: Cast Data Types ---------------- +~~~~~~~~~~~~~~~ Eloquent lets you convert model attribute data types before storing or retrieving data by using a casting helper. This helper is a convenient @@ -281,6 +284,45 @@ To learn how to change the behavior when attempting to fill a field omitted from the ``$fillable`` array, see `Mass Assignment Exceptions `__ in the Laravel docs. +.. _laravel-third-party-model: + +Extend Third-Party Model Classes +-------------------------------- + +You can use {+odm-short+} to extend a third-party model class by +including the ``DocumentModel`` trait when defining your model class. By +including this trait, you can make the third-party class compatible with +MongoDB. + +When you apply the ``DocumentModel`` trait to a model class, you must +declare the following properties in your class: + +- ``$primaryKey = '_id'``, because the ``_id`` field uniquely + identifies MongoDB documents +- ``$keyType = 'string'``, because {+odm-short+} casts MongoDB + ``ObjectId`` values to type ``string`` + +Extended Class Example +~~~~~~~~~~~~~~~~~~~~~~ + +This example creates a ``Planet`` model class that extends the +``CelestialBody`` class from a package called ``ThirdPartyPackage``. The +``Post`` class includes the ``DocumentModel`` trait and defines +properties including ``$primaryKey`` and ``$keyType``: + +.. literalinclude:: /includes/eloquent-models/PlanetThirdParty.php + :language: php + :emphasize-lines: 10,13-14 + :dedent: + +After defining your class, you can perform MongoDB operations as usual. + +.. tip:: + + To view another example that uses the ``DocumentModel`` trait, see + the :ref:`laravel-user-auth-sanctum` section of the User + Authentication guide. + .. _laravel-model-pruning: Specify Pruning Behavior diff --git a/docs/includes/eloquent-models/PlanetThirdParty.php b/docs/includes/eloquent-models/PlanetThirdParty.php new file mode 100644 index 000000000..0f3bae638 --- /dev/null +++ b/docs/includes/eloquent-models/PlanetThirdParty.php @@ -0,0 +1,15 @@ +`__ in the Laravel Sanctum guide. +.. tip:: + + To learn more about the ``DocumentModel`` trait, see + :ref:`laravel-third-party-model` in the Eloquent Model Class guide. + .. _laravel-user-auth-reminders: Password Reminders From 895dcc73d08b2b6ae206860dad1da968b9199a19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 25 Jul 2024 11:20:57 +0200 Subject: [PATCH 5/6] PHPORM-222 Register the `BusServiceProvider` when `BatchRepository` is built (#3071) --- src/MongoDBBusServiceProvider.php | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/MongoDBBusServiceProvider.php b/src/MongoDBBusServiceProvider.php index c77ccd118..d3d6f25fc 100644 --- a/src/MongoDBBusServiceProvider.php +++ b/src/MongoDBBusServiceProvider.php @@ -8,8 +8,11 @@ use Illuminate\Container\Container; use Illuminate\Contracts\Support\DeferrableProvider; use Illuminate\Support\ServiceProvider; +use InvalidArgumentException; use MongoDB\Laravel\Bus\MongoBatchRepository; +use function sprintf; + class MongoDBBusServiceProvider extends ServiceProvider implements DeferrableProvider { /** @@ -18,14 +21,21 @@ class MongoDBBusServiceProvider extends ServiceProvider implements DeferrablePro public function register() { $this->app->singleton(MongoBatchRepository::class, function (Container $app) { + $connection = $app->make('db')->connection($app->config->get('queue.batching.database')); + + if (! $connection instanceof Connection) { + throw new InvalidArgumentException(sprintf('The "mongodb" batch driver requires a MongoDB connection. The "%s" connection uses the "%s" driver.', $connection->getName(), $connection->getDriverName())); + } + return new MongoBatchRepository( $app->make(BatchFactory::class), - $app->make('db')->connection($app->config->get('queue.batching.database')), + $connection, $app->config->get('queue.batching.collection', 'job_batches'), ); }); - /** @see BusServiceProvider::registerBatchServices() */ + /** The {@see BatchRepository} service is registered in {@see BusServiceProvider} */ + $this->app->register(BusServiceProvider::class); $this->app->extend(BatchRepository::class, function (BatchRepository $repository, Container $app) { $driver = $app->config->get('queue.batching.driver'); From fb7bbf6b8d1bcb62dfac80e72261b280365759e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 25 Jul 2024 11:52:51 +0200 Subject: [PATCH 6/6] Update changelog (#3076) --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b4b539e13..8c1c4d9c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Changelog All notable changes to this project will be documented in this file. +## [4.7.1] - 2024-07-25 + +* Fix registration of `BusServiceProvider` for compatibility with Horizon by @GromNaN in [#3071](https://github.com/mongodb/laravel-mongodb/pull/3071) + ## [4.7.0] - 2024-07-19 * Add `Query\Builder::upsert()` method by @GromNaN in [#3052](https://github.com/mongodb/laravel-mongodb/pull/3052)