From ef774e23b481fed1e161356ba57e4c9a7fb8e2f9 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 23 Feb 2024 10:35:27 -0500 Subject: [PATCH 01/27] DOCSP-37056: Eloquent relationships --- docs/eloquent-models/relationships.txt | 38 ++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/eloquent-models/relationships.txt diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt new file mode 100644 index 000000000..e07a70ba7 --- /dev/null +++ b/docs/eloquent-models/relationships.txt @@ -0,0 +1,38 @@ +.. _laravel-eloquent-model-relationships: + +============================ +Eloquent Model Relationships +============================ + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, odm, code example + +Relationships +------------- + +This section describes each of the Laravel Eloquent and MongoDB-specific +relationships that you can use and provides examples for hasOne, hasMany, +belongsTo, belongsToMany, embedsOne, and embedsMany. + + +{+odm-short+} supports the following Eloquent relationships: + +- hasOne +- hasMany +- belongsTo +- belongsToMany + + +It also supports the following + + + +Each example will show, when applicable, how to define the relationships, +access the related models, save/create, destroy/delete, and associate/disassociate. + + + From 28737cd3b2348c90546c8aee7abb9e975ee27fff Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 28 Feb 2024 11:19:28 -0500 Subject: [PATCH 02/27] WIP --- docs/eloquent-models/relationships.txt | 100 +++++++++++++++--- .../relationships/OrbitOneToOne.php | 17 +++ .../relationships/PlanetOneToOne.php | 17 +++ .../relationships/RelationshipController.php | 97 +++++++++++++++++ 4 files changed, 218 insertions(+), 13 deletions(-) create mode 100644 docs/includes/eloquent-models/relationships/OrbitOneToOne.php create mode 100644 docs/includes/eloquent-models/relationships/PlanetOneToOne.php create mode 100644 docs/includes/eloquent-models/relationships/RelationshipController.php diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index e07a70ba7..63754e5f6 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -11,28 +11,102 @@ Eloquent Model Relationships .. meta:: :keywords: php framework, odm, code example -Relationships -------------- +Overview +-------- + +This section describes the following Laravel Eloquent and MongoDB-specific +relationships available in {+odm-short+} and shows examples on how to define +and use them: + +- :ref:`One to one relationship `, + created by using the ``hasOne()`` method and its inverse, ``belongsTo()`` +- :ref:`One to many relationship `, + created by using the ``hasMany()`` and its inverse, ``belongsTo()`` +- :ref:`Many to many relationship `, + created by using the ``belongsToMany()`` method +- :ref:`Embedded document pattern `, + specific to MongoDB, which can represent a one + to one or one to many relationship by using the ``embedsOne()`` or + ``embedsMany()`` method + + +TODO: +Each example will show, when applicable, how to define the relationships, +access the related models, save/create, destroy/delete, and associate/disassociate. -This section describes each of the Laravel Eloquent and MongoDB-specific -relationships that you can use and provides examples for hasOne, hasMany, -belongsTo, belongsToMany, embedsOne, and embedsMany. +.. _laravel-eloquent-relationship-one-to-one: +One to One Relationship +----------------------- -{+odm-short+} supports the following Eloquent relationships: +In data modeling, a one to one relationship between models means that one model +record is related to exactly one other type of model record. In {+odm-short+}, +this is represented by storing the value of the ID of the related model. -- hasOne -- hasMany -- belongsTo -- belongsToMany +TODO +To establish a one to one relationship, define a method that returns a +``hasOne`` function and calls the ``hasOne()`` method. Pass it the class of +the related model. -It also supports the following +To define the inverse of the relationship on the related model and call the +``belongsTo()`` method on it. +https://laravel.com/docs/10.x/eloquent-relationships#one-to-one -Each example will show, when applicable, how to define the relationships, -access the related models, save/create, destroy/delete, and associate/disassociate. +One to One Example +~~~~~~~~~~~~~~~~~~ + +The following classes shows a one to one relationship between a ``Planet`` +and ``Orbit`` model. + +.. literalinclude:: /includes/eloquent-models/relationships/PlanetOneToOne.php + :language: php + :dedent: + +.. literalinclude:: /includes/eloquent-models/relationships/OrbitOneToOne.php + :language: php + :dedent: + +The following sample code shows how you can create a model and ould in +To create a Planet and corresponding Orbit, + + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController + :language: php + :dedent: + :starts-after: begin one-to-one save + :ends-before: end one-to-one save + + +MongoDB documents: + + + + + + + + + + +.. _laravel-eloquent-relationship-one-to-many: + +One to Many Relationship +------------------------ + +.. _laravel-eloquent-relationship-many-to-many: + +Many to Many Relationship +------------------------- + + +.. _laravel-embedded-document-pattern: + +Embedded Document Pattern +------------------------- + diff --git a/docs/includes/eloquent-models/relationships/OrbitOneToOne.php b/docs/includes/eloquent-models/relationships/OrbitOneToOne.php new file mode 100644 index 000000000..05a65bee7 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/OrbitOneToOne.php @@ -0,0 +1,17 @@ +belongsTo(Planet::class); + } + +} diff --git a/docs/includes/eloquent-models/relationships/PlanetOneToOne.php b/docs/includes/eloquent-models/relationships/PlanetOneToOne.php new file mode 100644 index 000000000..b292a4670 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/PlanetOneToOne.php @@ -0,0 +1,17 @@ +hasOne(Orbit::class); + } + +} diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php new file mode 100644 index 000000000..b99c0ab79 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/RelationshipController.php @@ -0,0 +1,97 @@ +name = 'Earth'; + $planet->diameter_km = 12742; + $planet->save(); + + $orbit = new Orbit(); + $orbit->period = 365.26; + $orbit->direction = 'counterclockwise'; + + $planet->orbit()->save($orbit); + // end one-to-one save + + + + return; + } + + /** + * Display the specified resource. + */ + + public function show() + { + + // begin planet-to-orbit + $planet = Planet::first(); + $related_orbit = $planet->orbit; + // end planet-to-orbit + + // begin orbit-to-planet + $orbit = Orbit::first(); + $related_planet = $orbit->planet; + // end orbit-to-planet + + return view('browse_planets', [ + 'planets' => Planet::take(10) + ->get() + ]); + } + + /** + * Show the form for editing the specified resource. + */ + public function edit(Planet $planet) + { + // + } + + /** + * Update the specified resource in storage. + */ + public function update(Request $request, Planet $planet) + { + // + } + + /** + * Remove the specified resource from storage. + */ + public function destroy(Planet $planet) + { + // + } +} From 49bcdef5810c1df97d560641b7889c80536acfcc Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 28 Feb 2024 16:16:23 -0500 Subject: [PATCH 03/27] one to one --- docs/eloquent-models/relationships.txt | 91 ++++++++++++------- .../relationships/RelationshipController.php | 6 +- 2 files changed, 62 insertions(+), 35 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 63754e5f6..ef3c072fd 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -9,7 +9,7 @@ Eloquent Model Relationships :values: tutorial .. meta:: - :keywords: php framework, odm, code example + :keywords: php framework, odm, code example, entity relationship, eloquent Overview -------- @@ -29,67 +29,96 @@ and use them: to one or one to many relationship by using the ``embedsOne()`` or ``embedsMany()`` method - -TODO: -Each example will show, when applicable, how to define the relationships, -access the related models, save/create, destroy/delete, and associate/disassociate. +To establish a relationship, add an Eloquent **dynamic property** to access the +related model. The dynamic property lets you access the relational method by +using the same syntax as you use to access a property on the model. .. _laravel-eloquent-relationship-one-to-one: One to One Relationship ----------------------- -In data modeling, a one to one relationship between models means that one model -record is related to exactly one other type of model record. In {+odm-short+}, -this is represented by storing the value of the ID of the related model. +A one to one relationship between models consists of a model record that +is related to exactly one other type of model record. In MongoDB, a record +is represented as a document and different model types exist in separate +collections. -TODO +In {+odm-short+}, you can define a one to one relationship by using the +``hasOne()`` method or ``belongsTo()`` method. -To establish a one to one relationship, define a method that returns a -``hasOne`` function and calls the ``hasOne()`` method. Pass it the class of -the related model. +When you establish a one to one relationship by using the ``hasOne()`` method, +Eloquent lets you access the model by using a dynamic property and stores the +model's ID on the related model. -To define the inverse of the relationship on the related model and call the -``belongsTo()`` method on it. +When you establish the inverse of the relationship by using the ``belongsTo()`` +method, Eloquent lets you access the model by using a dynamic property, but +does not add any fields. -https://laravel.com/docs/10.x/eloquent-relationships#one-to-one +The following section shows an example of how to create one to one +relationships. +To learn more about one to one relationships, see +`One to One `__ +in the Laravel docs. One to One Example ~~~~~~~~~~~~~~~~~~ -The following classes shows a one to one relationship between a ``Planet`` -and ``Orbit`` model. +The following example class shows how to define a ``HasOne`` one to one +relationship between a ``Planet`` and ``Orbit`` model. .. literalinclude:: /includes/eloquent-models/relationships/PlanetOneToOne.php :language: php :dedent: +To define the inverse of the relationship on ``Orbit``, add the dynamic +property and call the ``belongsTo()`` method on it as shown in the following +example class: + .. literalinclude:: /includes/eloquent-models/relationships/OrbitOneToOne.php :language: php :dedent: -The following sample code shows how you can create a model and ould in -To create a Planet and corresponding Orbit, +The following sample code shows how you can create a model for each class +and add the relationship between them: - -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php :language: php :dedent: :starts-after: begin one-to-one save :ends-before: end one-to-one save +The following sample code shows how you can access the related models by using +the dynamic properties as defined in the example classes: -MongoDB documents: - - - - - - - - - +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :starts-after: begin dynamic property example + :ends-before: end dynamic property example + +The models created in the prior examples resemble the following documents +in MongoDB: + +.. code-block:: javascript + :copyable: false + + // Document in the "planets" collection + { + _id: ObjectId('65de67fb2e59d63e6d07f8b8'), + name: 'Earth', + diameter_km: 12742, + // ... + } + + // Document in the "orbits" collection + { + _id: ObjectId('65de67fb2e59d63e6d07f8b9'), + period: 365.26, + direction: 'counterclockwise', + planet_id: '65de67fb2e59d63e6d07f8b8', + // ... + } .. _laravel-eloquent-relationship-one-to-many: diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php index b99c0ab79..a95630bfa 100644 --- a/docs/includes/eloquent-models/relationships/RelationshipController.php +++ b/docs/includes/eloquent-models/relationships/RelationshipController.php @@ -55,15 +55,13 @@ public function store(Request $request) public function show() { - // begin planet-to-orbit + // begin dynamic property example $planet = Planet::first(); $related_orbit = $planet->orbit; - // end planet-to-orbit - // begin orbit-to-planet $orbit = Orbit::first(); $related_planet = $orbit->planet; - // end orbit-to-planet + // end dynamic property example return view('browse_planets', [ 'planets' => Planet::take(10) From d6d874ec1e5e595b256fcdce520cac8dd3bd60d6 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 28 Feb 2024 16:29:35 -0500 Subject: [PATCH 04/27] rst fixes --- docs/eloquent-models/relationships.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index ef3c072fd..9f1a03c3e 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -58,7 +58,7 @@ The following section shows an example of how to create one to one relationships. To learn more about one to one relationships, see -`One to One `__ +`One to One `__ in the Laravel docs. One to One Example @@ -85,8 +85,8 @@ and add the relationship between them: .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php :language: php :dedent: - :starts-after: begin one-to-one save - :ends-before: end one-to-one save + :start-after: begin one-to-one save + :end-before: end one-to-one save The following sample code shows how you can access the related models by using the dynamic properties as defined in the example classes: @@ -94,8 +94,8 @@ the dynamic properties as defined in the example classes: .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php :language: php :dedent: - :starts-after: begin dynamic property example - :ends-before: end dynamic property example + :start-after: begin dynamic property example + :end-before: end dynamic property example The models created in the prior examples resemble the following documents in MongoDB: From 8228f5184ae322d882ca1855d09ce2a4357f73de Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 28 Feb 2024 18:00:55 -0500 Subject: [PATCH 05/27] one to many --- docs/eloquent-models.txt | 517 +----------------- docs/eloquent-models/relationships.txt | 107 +++- .../relationships/RelationshipController.php | 90 +-- 3 files changed, 166 insertions(+), 548 deletions(-) diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index 3ce32c124..37d6fc080 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -6,517 +6,24 @@ Eloquent Models .. facet:: :name: genre - :values: tutorial + :values: reference .. meta:: - :keywords: php framework, odm, code example + :keywords: php framework, odm -This package includes a MongoDB enabled Eloquent class that you can use to -define models for corresponding collections. +Eloquent models are part of the Laravel Eloquent object-relational +mapping (ORM) framework that enable you to work with a database by using +model classes. The {+odm-short+} extends this framework to use similar +syntax to work with MongoDB as a database. -Extending the base model -~~~~~~~~~~~~~~~~~~~~~~~~ +This section contains guidance on how to use Eloquent models in +{+odm-short+} to work with MongoDB in the following ways: -To get started, create a new model class in your ``app\Models\`` directory. +- :ref:`laravel-eloquent-model-relationships`` shows how to add relationships + between models -.. code-block:: php +.. toctree:: - namespace App\Models; + /eloquent-models/relationships - use MongoDB\Laravel\Eloquent\Model; - class Book extends Model - { - // - } - -Just like a regular model, the MongoDB model class will know which collection -to use based on the model name. For ``Book``, the collection ``books`` will -be used. - -To change the collection, pass the ``$collection`` property: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - protected $collection = 'my_books_collection'; - } - -.. note:: - - MongoDB documents are automatically stored with a unique ID that is stored - in the ``_id`` property. If you wish to use your own ID, substitute the - ``$primaryKey`` property and set it to your own primary key attribute name. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - protected $primaryKey = 'id'; - } - - // MongoDB will also create _id, but the 'id' property will be used for primary key actions like find(). - Book::create(['id' => 1, 'title' => 'The Fault in Our Stars']); - -Likewise, you may define a ``connection`` property to override the name of the -database connection to reference the model. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - protected $connection = 'mongodb'; - } - -Soft Deletes -~~~~~~~~~~~~ - -When soft deleting a model, it is not actually removed from your database. -Instead, a ``deleted_at`` timestamp is set on the record. - -To enable soft delete for a model, apply the ``MongoDB\Laravel\Eloquent\SoftDeletes`` -Trait to the model: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\SoftDeletes; - - class User extends Model - { - use SoftDeletes; - } - -For more information check `Laravel Docs about Soft Deleting `__. - -Prunable -~~~~~~~~ - -``Prunable`` and ``MassPrunable`` traits are Laravel features to automatically -remove models from your database. You can use ``Illuminate\Database\Eloquent\Prunable`` -trait to remove models one by one. If you want to remove models in bulk, you -must use the ``MongoDB\Laravel\Eloquent\MassPrunable`` trait instead: it -will be more performant but can break links with other documents as it does -not load the models. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - use MongoDB\Laravel\Eloquent\MassPrunable; - - class Book extends Model - { - use MassPrunable; - } - -For more information check `Laravel Docs about Pruning Models `__. - -Dates -~~~~~ - -Eloquent allows you to work with Carbon or DateTime objects instead of MongoDate objects. Internally, these dates will be converted to MongoDate objects when saved to the database. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - protected $casts = ['birthday' => 'datetime']; - } - -This allows you to execute queries like this: - -.. code-block:: php - - $users = User::where( - 'birthday', '>', - new DateTime('-18 years') - )->get(); - -Extending the Authenticatable base model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This package includes a MongoDB Authenticatable Eloquent class ``MongoDB\Laravel\Auth\User`` -that you can use to replace the default Authenticatable class ``Illuminate\Foundation\Auth\User`` -for your ``User`` model. - -.. code-block:: php - - use MongoDB\Laravel\Auth\User as Authenticatable; - - class User extends Authenticatable - { - - } - -Guarding attributes -~~~~~~~~~~~~~~~~~~~ - -When choosing between guarding attributes or marking some as fillable, Taylor -Otwell prefers the fillable route. This is in light of -`recent security issues described here `__. - -Keep in mind guarding still works, but you may experience unexpected behavior. - -Schema ------- - -The database driver also has (limited) schema builder support. You can -conveniently manipulate collections and set indexes. - -Basic Usage -~~~~~~~~~~~ - -.. code-block:: php - - Schema::create('users', function ($collection) { - $collection->index('name'); - $collection->unique('email'); - }); - -You can also pass all the parameters specified :manual:`in the MongoDB docs ` -to the ``$options`` parameter: - -.. code-block:: php - - Schema::create('users', function ($collection) { - $collection->index( - 'username', - null, - null, - [ - 'sparse' => true, - 'unique' => true, - 'background' => true, - ] - ); - }); - -Inherited operations: - - -* create and drop -* collection -* hasCollection -* index and dropIndex (compound indexes supported as well) -* unique - -MongoDB specific operations: - - -* background -* sparse -* expire -* geospatial - -All other (unsupported) operations are implemented as dummy pass-through -methods because MongoDB does not use a predefined schema. - -Read more about the schema builder on `Laravel Docs `__ - -Geospatial indexes -~~~~~~~~~~~~~~~~~~ - -Geospatial indexes can improve query performance of location-based documents. - -They come in two forms: ``2d`` and ``2dsphere``. Use the schema builder to add -these to a collection. - -.. code-block:: php - - Schema::create('bars', function ($collection) { - $collection->geospatial('location', '2d'); - }); - -To add a ``2dsphere`` index: - -.. code-block:: php - - Schema::create('bars', function ($collection) { - $collection->geospatial('location', '2dsphere'); - }); - -Relationships -------------- - -Basic Usage -~~~~~~~~~~~ - -The only available relationships are: - - -* hasOne -* hasMany -* belongsTo -* belongsToMany - -The MongoDB-specific relationships are: - - -* embedsOne -* embedsMany - -Here is a small example: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function items() - { - return $this->hasMany(Item::class); - } - } - -The inverse relation of ``hasMany`` is ``belongsTo``: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Item extends Model - { - public function user() - { - return $this->belongsTo(User::class); - } - } - -belongsToMany and pivots -~~~~~~~~~~~~~~~~~~~~~~~~ - -The belongsToMany relation will not use a pivot "table" but will push id's to -a **related_ids** attribute instead. This makes the second parameter for the -belongsToMany method useless. - -If you want to define custom keys for your relation, set it to ``null``: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function groups() - { - return $this->belongsToMany( - Group::class, null, 'user_ids', 'group_ids' - ); - } - } - -EmbedsMany Relationship -~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to embed models, rather than referencing them, you can use the -``embedsMany`` relation. This relation is similar to the ``hasMany`` relation -but embeds the models inside the parent object. - -**REMEMBER**\ : These relations return Eloquent collections, they don't return -query builder objects! - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function books() - { - return $this->embedsMany(Book::class); - } - } - -You can access the embedded models through the dynamic property: - -.. code-block:: php - - $user = User::first(); - - foreach ($user->books as $book) { - // - } - -The inverse relation is auto *magically* available. You can omit the reverse -relation definition. - -.. code-block:: php - - $book = User::first()->books()->first(); - - $user = $book->user; - -Inserting and updating embedded models works similar to the ``hasMany`` relation: - -.. code-block:: php - - $book = $user->books()->save( - new Book(['title' => 'A Game of Thrones']) - ); - - // or - $book = - $user->books() - ->create(['title' => 'A Game of Thrones']); - -You can update embedded models using their ``save`` method (available since -release 2.0.0): - -.. code-block:: php - - $book = $user->books()->first(); - - $book->title = 'A Game of Thrones'; - $book->save(); - -You can remove an embedded model by using the ``destroy`` method on the -relation, or the ``delete`` method on the model (available since release 2.0.0): - -.. code-block:: php - - $book->delete(); - - // Similar operation - $user->books()->destroy($book); - -If you want to add or remove an embedded model, without touching the database, -you can use the ``associate`` and ``dissociate`` methods. - -To eventually write the changes to the database, save the parent object: - -.. code-block:: php - - $user->books()->associate($book); - $user->save(); - -Like other relations, embedsMany assumes the local key of the relationship -based on the model name. You can override the default local key by passing a -second argument to the embedsMany method: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class User extends Model - { - public function books() - { - return $this->embedsMany(Book::class, 'local_key'); - } - } - -Embedded relations will return a Collection of embedded items instead of a -query builder. Check out the available operations here: -`https://laravel.com/docs/master/collections `__ - -EmbedsOne Relationship -~~~~~~~~~~~~~~~~~~~~~~ - -The embedsOne relation is similar to the embedsMany relation, but only embeds a single model. - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Book extends Model - { - public function author() - { - return $this->embedsOne(Author::class); - } - } - -You can access the embedded models through the dynamic property: - -.. code-block:: php - - $book = Book::first(); - $author = $book->author; - -Inserting and updating embedded models works similar to the ``hasOne`` relation: - -.. code-block:: php - - $author = $book->author()->save( - new Author(['name' => 'John Doe']) - ); - - // Similar - $author = - $book->author() - ->create(['name' => 'John Doe']); - -You can update the embedded model using the ``save`` method (available since -release 2.0.0): - -.. code-block:: php - - $author = $book->author; - - $author->name = 'Jane Doe'; - $author->save(); - -You can replace the embedded model with a new model like this: - -.. code-block:: php - - $newAuthor = new Author(['name' => 'Jane Doe']); - - $book->author()->save($newAuthor); - -Cross-Database Relationships ----------------------------- - -If you're using a hybrid MongoDB and SQL setup, you can define relationships -across them. - -The model will automatically return a MongoDB-related or SQL-related relation -based on the type of the related model. - -If you want this functionality to work both ways, your SQL-models will need -to use the ``MongoDB\Laravel\Eloquent\HybridRelations`` trait. - -**This functionality only works for ``hasOne``, ``hasMany`` and ``belongsTo``.** - -The SQL model must use the ``HybridRelations`` trait: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\HybridRelations; - - class User extends Model - { - use HybridRelations; - - protected $connection = 'mysql'; - - public function messages() - { - return $this->hasMany(Message::class); - } - } - -Within your MongoDB model, you must define the following relationship: - -.. code-block:: php - - use MongoDB\Laravel\Eloquent\Model; - - class Message extends Model - { - protected $connection = 'mongodb'; - - public function user() - { - return $this->belongsTo(User::class); - } - } diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 9f1a03c3e..958882709 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -24,10 +24,9 @@ and use them: created by using the ``hasMany()`` and its inverse, ``belongsTo()`` - :ref:`Many to many relationship `, created by using the ``belongsToMany()`` method -- :ref:`Embedded document pattern `, - specific to MongoDB, which can represent a one - to one or one to many relationship by using the ``embedsOne()`` or - ``embedsMany()`` method +- :ref:`Embedded document pattern `, a + MongoDB-specific relationship that can represent a one to one or one to many + relationship, created by using the ``embedsOne()`` or ``embedsMany()`` method To establish a relationship, add an Eloquent **dynamic property** to access the related model. The dynamic property lets you access the relational method by @@ -46,11 +45,11 @@ collections. In {+odm-short+}, you can define a one to one relationship by using the ``hasOne()`` method or ``belongsTo()`` method. -When you establish a one to one relationship by using the ``hasOne()`` method, +When you add a one to one relationship by using the ``hasOne()`` method, Eloquent lets you access the model by using a dynamic property and stores the -model's ID on the related model. +model's document ID on the related model. -When you establish the inverse of the relationship by using the ``belongsTo()`` +When you add the inverse of the relationship by using the ``belongsTo()`` method, Eloquent lets you access the model by using a dynamic property, but does not add any fields. @@ -94,8 +93,8 @@ the dynamic properties as defined in the example classes: .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php :language: php :dedent: - :start-after: begin dynamic property example - :end-before: end dynamic property example + :start-after: begin planet orbit dynamic property example + :end-before: end planet orbit dynamic property example The models created in the prior examples resemble the following documents in MongoDB: @@ -125,6 +124,96 @@ in MongoDB: One to Many Relationship ------------------------ +A one to many relationship between models consists of a model that is +the parent and one or more related model records which are the children. + +In {+odm-short+}, you can define a one to many relationship by using the +``hasMany()`` method or ``belongsTo()`` method. + +When you add a one to many relationship by using the ``hasOne()`` method, +Eloquent lets you access the model by using a dynamic property and stores the +parent model's document ID on each of the child model documents. + +When you add the inverse of the relationship by using the ``belongsTo()`` +method, Eloquent lets you access the parent model by using a dynamic property, +but does not add any fields. + +The following section shows an example of how to create one to many +relationships. + +To learn more about one to many relationships, see +`One to Many `__ +in the Laravel docs. + +One to Many Example +~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define a ``HasMany`` one to many +relationship between a ``Planet`` parent model and ``Moon`` child model. + +.. literalinclude:: /includes/eloquent-models/relationships/PlanetOneToMany.php + :language: php + :dedent: + +To define the inverse of the relationship on ``Moon``, add the dynamic +property and call the ``belongsTo()`` method on it as shown in the following +example class: + +.. literalinclude:: /includes/eloquent-models/relationships/MoonOneToMany.php + :language: php + :dedent: + +The following sample code shows how you can create a model for each class +and add the relationship between them: + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin one-to-many save + :end-before: end one-to-many save + +The following sample code shows how you can access the related models by using +the dynamic properties as defined in the example classes: + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin planet moons dynamic property example + :end-before: end planet moons dynamic property example + +The models created in the prior examples resemble the following documents +in MongoDB: + +.. code-block:: javascript + :copyable: false + + // Parent document in the "planets" collection + { + _id: ObjectId('65dfb0050e323bbef800f7b2'), + name: 'Jupiter', + diameter_km: 142984, + // ... + } + + // Child documents in the "moons" collection + [ + { + _id: ObjectId('65dfb0050e323bbef800f7b3'), + name: 'Ganymede', + orbital_period: 7.15, + planet_id: '65dfb0050e323bbef800f7b2', + // ... + }, + { + _id: ObjectId('65dfb0050e323bbef800f7b4'), + name: 'Europa', + orbital_period: 3.55, + planet_id: '65dfb0050e323bbef800f7b2', + // ... + } + ] + + .. _laravel-eloquent-relationship-many-to-many: Many to Many Relationship diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php index a95630bfa..73aa84144 100644 --- a/docs/includes/eloquent-models/relationships/RelationshipController.php +++ b/docs/includes/eloquent-models/relationships/RelationshipController.php @@ -8,28 +8,9 @@ class PlanetController extends Controller { - /** - * Display a listing of the resource. - */ - public function index() - { - // - } - - /** - * Show the form for creating a new resource. - */ - public function create() - { - // - } - /** - * Store a newly created resource in storage. - */ - public function store(Request $request) + private function oneToOne() { - // begin one-to-one save $planet = new Planet(); $planet->name = 'Earth'; @@ -42,31 +23,72 @@ public function store(Request $request) $planet->orbit()->save($orbit); // end one-to-one save + } + private function oneToMany() + { + // begin one-to-many save + $planet = new Planet(); + $planet->name = 'Jupiter'; + $planet->diameter_km = 142984; + $planet->save(); + $moon_1 = new Moon(); + $moon_1->name = 'Ganymede'; + $moon_1->orbital_period = 7.15; - return; + $moon_2 = new Moon(); + $moon_2->name = 'Europa'; + $moon_2->orbital_period = 3.55; + + $planet->moons()->save($moon_1); + $planet->moons()->save($moon_2); + // end one-to-many save + } + + private function planetOrbitDynamic() + { + // begin planet orbit dynamic property example + $planet = Planet::first(); + $related_orbit = $planet->orbit; + + $orbit = Orbit::first(); + $related_planet = $orbit->planet; + // end planet orbit dynamic property example + } + + private function planetMoonsDynamic() + { + // begin planet moons dynamic property example + $planet = Planet::first(); + $related_moons = $planet->moons; + + $moon = Moon::first(); + $related_planet = $moon->planet; + // end planet moons dynamic property example } /** - * Display the specified resource. + * Store a newly created resource in storage. */ - - public function show() + public function store(Request $request) { + oneToMany(); + + return; + } - // begin dynamic property example - $planet = Planet::first(); - $related_orbit = $planet->orbit; - $orbit = Orbit::first(); - $related_planet = $orbit->planet; - // end dynamic property example - return view('browse_planets', [ - 'planets' => Planet::take(10) - ->get() - ]); + /** + * Display the specified resource. + */ + public function show() + { + return view('browse_planets', [ + 'planets' => Planet::take(10) + ->get() + ]); } /** From 6875660629797b3c496c7b0c6964035a5613b2e4 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 28 Feb 2024 18:27:26 -0500 Subject: [PATCH 06/27] add missing files --- docs/eloquent-models.txt | 2 +- docs/eloquent-models/relationships.txt | 89 +++++++++++++++++++ .../relationships/MoonOneToMany.php | 17 ++++ .../relationships/PlanetOneToMany.php | 17 ++++ 4 files changed, 124 insertions(+), 1 deletion(-) create mode 100644 docs/includes/eloquent-models/relationships/MoonOneToMany.php create mode 100644 docs/includes/eloquent-models/relationships/PlanetOneToMany.php diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index 37d6fc080..2e4bb40b2 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -19,7 +19,7 @@ syntax to work with MongoDB as a database. This section contains guidance on how to use Eloquent models in {+odm-short+} to work with MongoDB in the following ways: -- :ref:`laravel-eloquent-model-relationships`` shows how to add relationships +- :ref:`laravel-eloquent-model-relationships` shows how to add relationships between models .. toctree:: diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 958882709..377dd9ac7 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -219,6 +219,95 @@ in MongoDB: Many to Many Relationship ------------------------- +A many to many relationship consists of a relationship between two different +model types in which each model record can be related to multiple records +of the other type. + +In {+odm-short+}, you can define a many to many relationship by using the +``belongsToMany()`` method. + +When you add a many to many relationship by using the ``belongsTo()`` method, +Eloquent lets you access the model by using a dynamic property and stores the +parent model's document ID on each of the child model documents. + +When you add the inverse of the relationship by using the ``belongsTo()`` +method, Eloquent lets you access the parent model by using a dynamic property, +but does not add any fields. + +The following section shows an example of how to create one to many +relationships. + +To learn more about one to many relationships, see +`One to Many `__ +in the Laravel docs. + +One to Many Example +~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define a ``HasMany`` one to many +relationship between a ``Planet`` parent model and ``Moon`` child model. + +.. literalinclude:: /includes/eloquent-models/relationships/PlanetOneToMany.php + :language: php + :dedent: + +To define the inverse of the relationship on ``Moon``, add the dynamic +property and call the ``belongsTo()`` method on it as shown in the following +example class: + +.. literalinclude:: /includes/eloquent-models/relationships/MoonOneToMany.php + :language: php + :dedent: + +The following sample code shows how you can create a model for each class +and add the relationship between them: + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin one-to-many save + :end-before: end one-to-many save + +The following sample code shows how you can access the related models by using +the dynamic properties as defined in the example classes: + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin planet moons dynamic property example + :end-before: end planet moons dynamic property example + +The models created in the prior examples resemble the following documents +in MongoDB: + +.. code-block:: javascript + :copyable: false + + // Parent document in the "planets" collection + { + _id: ObjectId('65dfb0050e323bbef800f7b2'), + name: 'Jupiter', + diameter_km: 142984, + // ... + } + + // Child documents in the "moons" collection + [ + { + _id: ObjectId('65dfb0050e323bbef800f7b3'), + name: 'Ganymede', + orbital_period: 7.15, + planet_id: '65dfb0050e323bbef800f7b2', + // ... + }, + { + _id: ObjectId('65dfb0050e323bbef800f7b4'), + name: 'Europa', + orbital_period: 3.55, + planet_id: '65dfb0050e323bbef800f7b2', + // ... + } + ] .. _laravel-embedded-document-pattern: diff --git a/docs/includes/eloquent-models/relationships/MoonOneToMany.php b/docs/includes/eloquent-models/relationships/MoonOneToMany.php new file mode 100644 index 000000000..4b5b46248 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/MoonOneToMany.php @@ -0,0 +1,17 @@ +belongsTo(Planet::class); + } + +} diff --git a/docs/includes/eloquent-models/relationships/PlanetOneToMany.php b/docs/includes/eloquent-models/relationships/PlanetOneToMany.php new file mode 100644 index 000000000..77ed3f4c1 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/PlanetOneToMany.php @@ -0,0 +1,17 @@ +hasMany(Moon::class); + } + +} From cca3c5672fa244e940607f44b04245754583db3a Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Mon, 4 Mar 2024 23:15:25 -0500 Subject: [PATCH 07/27] WIP --- docs/eloquent-models/relationships.txt | 519 ++++++++++++------ .../relationships/CargoEmbedsMany.php | 10 + .../relationships/PlanetManyToMany.php | 17 + .../relationships/RelationshipController.php | 78 +++ .../relationships/SpaceExplorerManyToMany.php | 17 + .../relationships/SpaceShipEmbedsMany.php | 17 + 6 files changed, 498 insertions(+), 160 deletions(-) create mode 100644 docs/includes/eloquent-models/relationships/CargoEmbedsMany.php create mode 100644 docs/includes/eloquent-models/relationships/PlanetManyToMany.php create mode 100644 docs/includes/eloquent-models/relationships/SpaceExplorerManyToMany.php create mode 100644 docs/includes/eloquent-models/relationships/SpaceShipEmbedsMany.php diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 377dd9ac7..66f261272 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -14,7 +14,7 @@ Eloquent Model Relationships Overview -------- -This section describes the following Laravel Eloquent and MongoDB-specific +This page describes the following Laravel Eloquent and MongoDB-specific relationships available in {+odm-short+} and shows examples on how to define and use them: @@ -27,10 +27,15 @@ and use them: - :ref:`Embedded document pattern `, a MongoDB-specific relationship that can represent a one to one or one to many relationship, created by using the ``embedsOne()`` or ``embedsMany()`` method +- :ref:`Cross-database Relationships `, + required when you want to define + relationships between MongoDB and SQL models. -To establish a relationship, add an Eloquent **dynamic property** to access the -related model. The dynamic property lets you access the relational method by -using the same syntax as you use to access a property on the model. +To establish a relationship, add a function to the model class that calls +the appropriate relationship method. This function allows you to access the +related model as a **dynamic property**. A dynamic property lets you access +the related model by using the same syntax as you use to access a property +on the model. .. _laravel-eloquent-relationship-one-to-one: @@ -42,19 +47,19 @@ is related to exactly one other type of model record. In MongoDB, a record is represented as a document and different model types exist in separate collections. +When you add a one to one relationship by using the method, Eloquent lets you +access the model by using a dynamic property and stores the model's document +ID on the related model. + In {+odm-short+}, you can define a one to one relationship by using the ``hasOne()`` method or ``belongsTo()`` method. -When you add a one to one relationship by using the ``hasOne()`` method, -Eloquent lets you access the model by using a dynamic property and stores the -model's document ID on the related model. - When you add the inverse of the relationship by using the ``belongsTo()`` method, Eloquent lets you access the model by using a dynamic property, but does not add any fields. -The following section shows an example of how to create one to one -relationships. +The following section shows an example of how to create a one to one +relationship. To learn more about one to one relationships, see `One to One `__ @@ -70,15 +75,15 @@ relationship between a ``Planet`` and ``Orbit`` model. :language: php :dedent: -To define the inverse of the relationship on ``Orbit``, add the dynamic -property and call the ``belongsTo()`` method on it as shown in the following -example class: +The following example class uses a dynamic property and calls the +``belongsTo()`` method to define the inverse of the relationship on ``Orbit`` +as shown in the following example class: .. literalinclude:: /includes/eloquent-models/relationships/OrbitOneToOne.php :language: php :dedent: -The following sample code shows how you can create a model for each class +The following sample code shows how you can instantiate a model for each class and add the relationship between them: .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php @@ -90,34 +95,34 @@ and add the relationship between them: The following sample code shows how you can access the related models by using the dynamic properties as defined in the example classes: -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php - :language: php - :dedent: - :start-after: begin planet orbit dynamic property example - :end-before: end planet orbit dynamic property example - -The models created in the prior examples resemble the following documents -in MongoDB: - -.. code-block:: javascript - :copyable: false - - // Document in the "planets" collection - { - _id: ObjectId('65de67fb2e59d63e6d07f8b8'), - name: 'Earth', - diameter_km: 12742, - // ... - } - - // Document in the "orbits" collection - { - _id: ObjectId('65de67fb2e59d63e6d07f8b9'), - period: 365.26, - direction: 'counterclockwise', - planet_id: '65de67fb2e59d63e6d07f8b8', - // ... - } + +.. io-code-block:: + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin planet orbit dynamic property example + :end-before: end planet orbit dynamic property example + + .. output:: + :language: json + :visible: false + + // Document in the "planets" collection + { + _id: ObjectId('65de67fb2e59d63e6d07f8b8'), + name: 'Earth', + diameter_km: 12742, + // ... + } + + // Document in the "orbits" collection + { + _id: ObjectId('65de67fb2e59d63e6d07f8b9'), + period: 365.26, + direction: 'counterclockwise', + planet_id: '65de67fb2e59d63e6d07f8b8', + // ... + } .. _laravel-eloquent-relationship-one-to-many: @@ -127,19 +132,20 @@ One to Many Relationship A one to many relationship between models consists of a model that is the parent and one or more related model records which are the children. -In {+odm-short+}, you can define a one to many relationship by using the -``hasMany()`` method or ``belongsTo()`` method. +When you add a one to many relationship method, Eloquent lets you access the +model by using a dynamic property and stores the parent model's document ID +on each of the child model documents. -When you add a one to many relationship by using the ``hasOne()`` method, -Eloquent lets you access the model by using a dynamic property and stores the -parent model's document ID on each of the child model documents. +In {+odm-short+}, you can define a one to many relationship by using the +``hasMany()`` method on the parent class and optionally the ``belongsTo()`` +method on the child class. When you add the inverse of the relationship by using the ``belongsTo()`` -method, Eloquent lets you access the parent model by using a dynamic property, -but does not add any fields. +method, Eloquent lets you access the parent model by using a dynamic property +without adding any fields. -The following section shows an example of how to create one to many -relationships. +The following section shows an example of how to create a one to many +relationship. To learn more about one to many relationships, see `One to Many `__ @@ -149,9 +155,9 @@ One to Many Example ~~~~~~~~~~~~~~~~~~~ The following example class shows how to define a ``HasMany`` one to many -relationship between a ``Planet`` parent model and ``Moon`` child model. +relationship between a ``Planet`` parent model and ``Moon`` child model. -.. literalinclude:: /includes/eloquent-models/relationships/PlanetOneToMany.php +.. literalinclude:: includes/eloquent-models/relationships/PlanetOneToMany.php :language: php :dedent: @@ -159,11 +165,11 @@ To define the inverse of the relationship on ``Moon``, add the dynamic property and call the ``belongsTo()`` method on it as shown in the following example class: -.. literalinclude:: /includes/eloquent-models/relationships/MoonOneToMany.php +.. literalinclude:: includes/eloquent-models/relationships/MoonOneToMany.php :language: php :dedent: -The following sample code shows how you can create a model for each class +The following sample code shows how you can instantiate a model for each class and add the relationship between them: .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php @@ -173,46 +179,47 @@ and add the relationship between them: :end-before: end one-to-many save The following sample code shows how you can access the related models by using -the dynamic properties as defined in the example classes: - -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php - :language: php - :dedent: - :start-after: begin planet moons dynamic property example - :end-before: end planet moons dynamic property example - -The models created in the prior examples resemble the following documents -in MongoDB: - -.. code-block:: javascript - :copyable: false - - // Parent document in the "planets" collection - { - _id: ObjectId('65dfb0050e323bbef800f7b2'), - name: 'Jupiter', - diameter_km: 142984, - // ... - } - - // Child documents in the "moons" collection - [ - { - _id: ObjectId('65dfb0050e323bbef800f7b3'), - name: 'Ganymede', - orbital_period: 7.15, - planet_id: '65dfb0050e323bbef800f7b2', - // ... - }, - { - _id: ObjectId('65dfb0050e323bbef800f7b4'), - name: 'Europa', - orbital_period: 3.55, - planet_id: '65dfb0050e323bbef800f7b2', - // ... - } - ] - +the dynamic properties as defined in the example classes. Click the +:guilabel:`Output` button to see sample MongoDB documents created by running +the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin planet moons dynamic property example + :end-before: end planet moons dynamic property example + + .. output:: + :language: json + :visible: false + + // Parent document in the "planets" collection + { + _id: ObjectId('65dfb0050e323bbef800f7b2'), + name: 'Jupiter', + diameter_km: 142984, + // ... + } + + // Child documents in the "moons" collection + [ + { + _id: ObjectId('65dfb0050e323bbef800f7b3'), + name: 'Ganymede', + orbital_period: 7.15, + planet_id: '65dfb0050e323bbef800f7b2', + // ... + }, + { + _id: ObjectId('65dfb0050e323bbef800f7b4'), + name: 'Europa', + orbital_period: 3.55, + planet_id: '65dfb0050e323bbef800f7b2', + // ... + } + ] .. _laravel-eloquent-relationship-many-to-many: @@ -220,100 +227,292 @@ Many to Many Relationship ------------------------- A many to many relationship consists of a relationship between two different -model types in which each model record can be related to multiple records -of the other type. +model types in which one type of model record can be related to multiple +records of the other type. -In {+odm-short+}, you can define a many to many relationship by using the -``belongsToMany()`` method. +In {+odm-short+}, you can define a many to many relationship by adding the +``belongsToMany()`` method to both related classes. -When you add a many to many relationship by using the ``belongsTo()`` method, -Eloquent lets you access the model by using a dynamic property and stores the -parent model's document ID on each of the child model documents. +When you define a many to many relationship in a relational database, Laravel +creates a pivot table to track the relationships. When you use {+odm-short+}, +it omits the pivot table creation and instead adds the related document IDs +to a document field, derived from the related model class name. -When you add the inverse of the relationship by using the ``belongsTo()`` -method, Eloquent lets you access the parent model by using a dynamic property, -but does not add any fields. +.. tip:: -The following section shows an example of how to create one to many -relationships. + Since {+odm-short+} uses a document field instead of a pivot table, omit + the pivot table parameter from the ``belongsToMany()`` constructor or set + it to ``null``. -To learn more about one to many relationships, see -`One to Many `__ +The following section shows an example of how to create a many to many +relationship between model classes. + +To learn more about many to many relationships in Laravel, see +`Many to Many `__ in the Laravel docs. -One to Many Example -~~~~~~~~~~~~~~~~~~~ +Many to Many Example +~~~~~~~~~~~~~~~~~~~~ -The following example class shows how to define a ``HasMany`` one to many -relationship between a ``Planet`` parent model and ``Moon`` child model. +The following ``Planet`` class shows how to define a ``BelongsToMany`` many to +many relationship with and a ``SpaceExplorer`` model. -.. literalinclude:: /includes/eloquent-models/relationships/PlanetOneToMany.php +.. literalinclude:: /includes/eloquent-models/relationships/PlanetManyToMany.php :language: php :dedent: -To define the inverse of the relationship on ``Moon``, add the dynamic -property and call the ``belongsTo()`` method on it as shown in the following -example class: +The ``SpaceExplorer`` model defines a ``BelongsToMany`` many to many +relationship with ``Planet`` as shown in the following example class: -.. literalinclude:: /includes/eloquent-models/relationships/MoonOneToMany.php +.. literalinclude:: /includes/eloquent-models/relationships/SpaceShipManyToMany.php :language: php :dedent: -The following sample code shows how you can create a model for each class +The following sample code shows how you can instantiate a model for each class and add the relationship between them: .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php :language: php :dedent: - :start-after: begin one-to-many save - :end-before: end one-to-many save + :start-after: begin many-to-many save + :end-before: end many-to-many save The following sample code shows how you can access the related models by using -the dynamic properties as defined in the example classes: - -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php - :language: php - :dedent: - :start-after: begin planet moons dynamic property example - :end-before: end planet moons dynamic property example - -The models created in the prior examples resemble the following documents -in MongoDB: - -.. code-block:: javascript - :copyable: false - - // Parent document in the "planets" collection - { - _id: ObjectId('65dfb0050e323bbef800f7b2'), - name: 'Jupiter', - diameter_km: 142984, - // ... - } - - // Child documents in the "moons" collection - [ - { - _id: ObjectId('65dfb0050e323bbef800f7b3'), - name: 'Ganymede', - orbital_period: 7.15, - planet_id: '65dfb0050e323bbef800f7b2', - // ... - }, - { - _id: ObjectId('65dfb0050e323bbef800f7b4'), - name: 'Europa', - orbital_period: 3.55, - planet_id: '65dfb0050e323bbef800f7b2', - // ... - } - ] +the dynamic properties as defined in the example classes. Click the +:guilabel:`Output` button to see sample MongoDB documents created by running +the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin many to many dynamic property example + :end-before: end many to many dynamic property example + + .. output:: + :language: json + :visible: false + + // Documents in the "planets" collection + [ + { + _id: ObjectId('65e1043a5265269a03078ad0'), + name: 'Earth', + // ... + space_explorer_ids: [ + '65e1043b5265269a03078ad3', + '65e1043b5265269a03078ad4', + '65e1043b5265269a03078ad5' + ], + }, + { + _id: ObjectId('65e1043a5265269a03078ad1'), + name: 'Mars', + // ... + space_explorer_ids: [ '65e1043b5265269a03078ad4', '65e1043b5265269a03078ad5' ] + }, + { + _id: ObjectId('65e1043b5265269a03078ad2'), + name: 'Jupiter', + // ... + space_explorer_ids: [ '65e1043b5265269a03078ad3', '65e1043b5265269a03078ad5' ] + } + ] + + // Documents in the "space_explorers" collection + + [ + { + _id: ObjectId('65e1043b5265269a03078ad3'), + name: 'Tanya Kirbuk', + // ... + planet_ids: [ '65e1043a5265269a03078ad0', '65e1043b5265269a03078ad2' ] + }, + { + _id: ObjectId('65e1043b5265269a03078ad4'), + name: 'Mark Watney', + // ... + planet_ids: [ '65e1043a5265269a03078ad0', '65e1043a5265269a03078ad1' ] + }, + { + _id: ObjectId('65e1043b5265269a03078ad5'), + name: 'Jean-Luc Picard', + // ... + planet_ids: [ + '65e1043a5265269a03078ad0', + '65e1043a5265269a03078ad1', + '65e1043b5265269a03078ad2' + ] + } + ] .. _laravel-embedded-document-pattern: Embedded Document Pattern ------------------------- +In MongoDB, the embedded document pattern adds the related model's data into +the parent model instead of keeping foreign key references. This pattern +when you must optimize for one or more of the following requirements: + +- Keep related data together in a single collection +- Perform atomic updates on multiple fields of the document and the related data +- Reduce the number of reads required to fetch the data + +In {+odm-short+}, you can define embedded documents by using one of the +following dynamic property methods: + +- ``embedsOne()`` to embed a single document +- ``embedsMany()`` to embed multiple documents + +.. note:: + + These methods return Eloquent collections, which differ from query builder + objects. + +The following section shows an example of how to use the embedded document +pattern. + +To learn more about the MongoDB embedded document pattern, see the following +MongoDB server tutorials: + +- :manual:`Model One-to-One Relationships with Embedded Documents ` +- :manual:`Model One-to-Many Relationships with Embedded Documents ` + +Embedded Document Example +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example class shows how to define an ``embedsMany`` one to many +relationship between a ``SpaceShip`` and ``Cargo`` model: + +.. literalinclude:: /includes/eloquent-models/relationships/SpaceShipEmbedsMany.php + :language: php + :dedent: + +The embedded model class omits the relationship definition as shown in the +following example class: + +.. literalinclude:: /includes/eloquent-models/relationships/CargoEmbedsMany.php + :language: php + :dedent: + +The following sample code shows how you can create a ``SpaceShip`` model and +embed multiple ``Cargo`` models and the MongoDB document created by running the +code. Click the :guilabel:`Output` button to see sample MongoDB documents +created by running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin embedsMany save + :end-before: end embedsMany save + + .. output:: + :language: json + :visible: false + + // Document in the "space_ships" collection + { + _id: ObjectId('65e207b9aa167d29a3048853'), + name: 'The Millenium Falcon', + // ... + cargo: [ + { + name: 'spice', + weight: 50, + // ... + _id: ObjectId('65e207b9aa167d29a3048854') + }, + { + name: 'hyperdrive', + weight: 25, + // ... + _id: ObjectId('65e207b9aa167d29a3048855') + } + ] + } + + +.. _laravel-relationship-cross-database + +Cross-Database Relationships +---------------------------- + +A cross-database relationship in {+odm-short+} is a relationship between models +stored in a SQL relational database and models stored in a MongoDB database. + +When you add a cross-database relationship, Eloquent lets you access a +related model by using a dynamic property. + +{+odm-short+} supports the following cross-database relationship methods: + +- ``hasOne()`` +- ``hasMany()`` +- ``belongsTo()`` + +To define a cross-database relationship, you must import the +``MongoDB\Laravel\Eloquent\HybridRelations`` package in the class stored in +the relational database. + +The following section shows an example of how to define a cross-database +relationship. + +Cross-Database Relationship Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example class creates a ``hasMany`` relationship between a +``SpaceShip`` model stored in a MySQL database and a ``Passenger`` model +stored in a MongoDB database: + +.. literalinclude:: /includes/eloquent-models/relationships/SpaceShipCrossHasMany.php + :language: php + :dedent: + +The ``Passenger`` model defines a ``BelongsToMany`` relationship with +``SpaceShip`` as shown in the following example class: + +.. literalinclude:: /includes/eloquent-models/relationships/SpaceShipManyToMany.php + :language: php + :dedent: + +The following sample code shows how you can instantiate a model for each class +and add the relationship between them: + +.. literalinclude:: /includes/eloquent-models/relationships/PassengerCrossBelongsTo.php + :language: php + :dedent: + +The embedded model class omits the relationship definition as shown in the +following example class: + +.. literalinclude:: /includes/eloquent-models/relationships/CargoEmbedsMany.php + :language: php + :dedent: + +The following sample code shows how you can create a ``SpaceShip`` model in +a MySQL database and related ``Passenger`` models in a MongoDB database and +the data created by running the code. Click the :guilabel:`Output` button to +see sample MongoDB documents created by running the code: + +.. io-code-block:: + + .. input:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin cross-database save + :end-before: end cross-database save + + .. output:: + :language: none + :visible: false + +------+----------+ + | id | name | + +------+----------+ + | 1234 | Nostromo | + +------+----------+ diff --git a/docs/includes/eloquent-models/relationships/CargoEmbedsMany.php b/docs/includes/eloquent-models/relationships/CargoEmbedsMany.php new file mode 100644 index 000000000..2030f855b --- /dev/null +++ b/docs/includes/eloquent-models/relationships/CargoEmbedsMany.php @@ -0,0 +1,10 @@ +belongsToMany(SpaceExplorer::class); + } + +} diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php index 73aa84144..532f053a7 100644 --- a/docs/includes/eloquent-models/relationships/RelationshipController.php +++ b/docs/includes/eloquent-models/relationships/RelationshipController.php @@ -68,6 +68,84 @@ private function planetMoonsDynamic() // end planet moons dynamic property example } + private function manyToMany() + { + // begin many-to-many save + $planet_earth = new Planet(); + $planet_earth->name = 'Earth'; + $planet_earth->save(); + + $planet_mars = new Planet(); + $planet_mars->name = 'Mars'; + $planet_mars->save(); + + $planet_jupiter= new Planet(); + $planet_jupiter->name = 'Jupiter'; + $planet_jupiter->save(); + + $explorer_tanya = new SpaceExplorer(); + $explorer_tanya->name = 'Tanya Kirbuk'; + $explorer_tanya->save(); + + $explorer_mark = new SpaceExplorer(); + $explorer_mark->name = 'Mark Watney'; + $explorer_mark->save(); + + $explorer_jeanluc = new SpaceExplorer(); + $explorer_jeanluc->name = 'Jean-Luc Picard'; + $explorer_jeanluc->save(); + + $explorer_tanya->planetsVisited()->attach($planet_earth); + $explorer_tanya->planetsVisited()->attach($planet_jupiter); + $explorer_mark->planetsVisited()->attach($planet_earth); + $explorer_mark->planetsVisited()->attach($planet_mars); + $explorer_jeanluc->planetsVisited()->attach($planet_earth); + $explorer_jeanluc->planetsVisited()->attach($planet_mars); + $explorer_jeanluc->planetsVisited()->attach($planet_jupiter); + // end many-to-many save + + } + private function embedsMany() + { + // begin embedsMany save + $spaceship = new SpaceShip(); + $spaceship->name = 'The Millenium Falcon'; + $spaceship->save(); + + $cargo_spice = new Cargo(); + $cargo_spice->name = "spice"; + $cargo_spice->weight = 50; + + $cargo_hyperdrive = new Cargo(); + $cargo_hyperdrive->name = "hyperdrive"; + $cargo_hyperdrive->weight = 25; + + $spaceship->cargo()->attach($cargo_spice); + $spaceship->cargo()->attach($cargo_hyperdrive); + // end embedsMany save + } + + + private function crossDatabase() + { + // begin cross-database save + $spaceship = new SpaceShip(); + $spaceship->id = 1234; + $spaceship->name = 'Nostromo'; + $spaceship->save(); + + $passenger_ellen = new Passenger(); + $passenger_ellen->name = 'Ellen Ripley'; + + $passenger_dwayne = new Passenger(); + $passenger_dwayne->name = 'Dwayne Hicks'; + + $spaceship->passengers()->save($passenger_ellen); + $spaceship->passengers()->save($passenger_dwayne); + // end cross-database save + } + + /** * Store a newly created resource in storage. */ diff --git a/docs/includes/eloquent-models/relationships/SpaceExplorerManyToMany.php b/docs/includes/eloquent-models/relationships/SpaceExplorerManyToMany.php new file mode 100644 index 000000000..ee7221b7e --- /dev/null +++ b/docs/includes/eloquent-models/relationships/SpaceExplorerManyToMany.php @@ -0,0 +1,17 @@ +belongsToMany(Planet::class); + } + +} diff --git a/docs/includes/eloquent-models/relationships/SpaceShipEmbedsMany.php b/docs/includes/eloquent-models/relationships/SpaceShipEmbedsMany.php new file mode 100644 index 000000000..93880e309 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/SpaceShipEmbedsMany.php @@ -0,0 +1,17 @@ +embedsMany(Cargo::class); + } + +} From f7ec7726cc3eb1158524eb2dbe640e9ff7d82dff Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 5 Mar 2024 01:03:59 -0500 Subject: [PATCH 08/27] rst fixes --- docs/eloquent-models/relationships.txt | 16 ++++++++-------- .../relationships/PassengerCrossBelongsTo.php | 17 +++++++++++++++++ .../relationships/SpaceShipCrossHasMany.php | 19 +++++++++++++++++++ 3 files changed, 44 insertions(+), 8 deletions(-) create mode 100644 docs/includes/eloquent-models/relationships/PassengerCrossBelongsTo.php create mode 100644 docs/includes/eloquent-models/relationships/SpaceShipCrossHasMany.php diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 66f261272..0d6df767d 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -264,7 +264,7 @@ many relationship with and a ``SpaceExplorer`` model. The ``SpaceExplorer`` model defines a ``BelongsToMany`` many to many relationship with ``Planet`` as shown in the following example class: -.. literalinclude:: /includes/eloquent-models/relationships/SpaceShipManyToMany.php +.. literalinclude:: /includes/eloquent-models/relationships/SpaceExplorerManyToMany.php :language: php :dedent: @@ -433,7 +433,7 @@ created by running the code: _id: ObjectId('65e207b9aa167d29a3048855') } ] - } + } .. _laravel-relationship-cross-database @@ -509,10 +509,10 @@ see sample MongoDB documents created by running the code: :language: none :visible: false - +------+----------+ - | id | name | - +------+----------+ - | 1234 | Nostromo | - +------+----------+ - + +------+----------+ + | id | name | + +------+----------+ + | 1234 | Nostromo | + +------+----------+ + diff --git a/docs/includes/eloquent-models/relationships/PassengerCrossBelongsTo.php b/docs/includes/eloquent-models/relationships/PassengerCrossBelongsTo.php new file mode 100644 index 000000000..8ae6b059a --- /dev/null +++ b/docs/includes/eloquent-models/relationships/PassengerCrossBelongsTo.php @@ -0,0 +1,17 @@ +BelongsTo(SpaceShip::class); + } + +} diff --git a/docs/includes/eloquent-models/relationships/SpaceShipCrossHasMany.php b/docs/includes/eloquent-models/relationships/SpaceShipCrossHasMany.php new file mode 100644 index 000000000..1ba13d213 --- /dev/null +++ b/docs/includes/eloquent-models/relationships/SpaceShipCrossHasMany.php @@ -0,0 +1,19 @@ +hasMany(Passenger::class); + } + +} From d2bbc981a1b10475dd536bab120d67b6ed99e53c Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 5 Mar 2024 01:11:41 -0500 Subject: [PATCH 09/27] fix RST --- docs/eloquent-models/relationships.txt | 56 +++++++++----------------- 1 file changed, 20 insertions(+), 36 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 0d6df767d..2915b90b4 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -287,8 +287,8 @@ the code: .. input:: /includes/eloquent-models/relationships/RelationshipController.php :language: php :dedent: - :start-after: begin many to many dynamic property example - :end-before: end many to many dynamic property example + :start-after: begin many to many save + :end-before: end many to many save .. output:: :language: json @@ -416,27 +416,26 @@ created by running the code: // Document in the "space_ships" collection { - _id: ObjectId('65e207b9aa167d29a3048853'), - name: 'The Millenium Falcon', - // ... - cargo: [ - { - name: 'spice', - weight: 50, - // ... - _id: ObjectId('65e207b9aa167d29a3048854') - }, - { - name: 'hyperdrive', - weight: 25, - // ... - _id: ObjectId('65e207b9aa167d29a3048855') - } - ] + _id: ObjectId('65e207b9aa167d29a3048853'), + name: 'The Millenium Falcon', + // ... + cargo: [ + { + name: 'spice', + weight: 50, + // ... + _id: ObjectId('65e207b9aa167d29a3048854') + }, + { + name: 'hyperdrive', + weight: 25, + // ... + _id: ObjectId('65e207b9aa167d29a3048855') + } + ] } - -.. _laravel-relationship-cross-database +.. _laravel-relationship-cross-database: Cross-Database Relationships ---------------------------- @@ -474,24 +473,10 @@ stored in a MongoDB database: The ``Passenger`` model defines a ``BelongsToMany`` relationship with ``SpaceShip`` as shown in the following example class: -.. literalinclude:: /includes/eloquent-models/relationships/SpaceShipManyToMany.php - :language: php - :dedent: - -The following sample code shows how you can instantiate a model for each class -and add the relationship between them: - .. literalinclude:: /includes/eloquent-models/relationships/PassengerCrossBelongsTo.php :language: php :dedent: -The embedded model class omits the relationship definition as shown in the -following example class: - -.. literalinclude:: /includes/eloquent-models/relationships/CargoEmbedsMany.php - :language: php - :dedent: - The following sample code shows how you can create a ``SpaceShip`` model in a MySQL database and related ``Passenger`` models in a MongoDB database and the data created by running the code. Click the :guilabel:`Output` button to @@ -514,5 +499,4 @@ see sample MongoDB documents created by running the code: +------+----------+ | 1234 | Nostromo | +------+----------+ - From 6d0ba9b9ac1b5172d8629069e7b63fe1bb769766 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 5 Mar 2024 02:08:34 -0500 Subject: [PATCH 10/27] fix --- docs/eloquent-models/relationships.txt | 78 +++++++++---------- .../relationships/RelationshipController.php | 11 +++ 2 files changed, 50 insertions(+), 39 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 2915b90b4..9230b41c9 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -84,17 +84,8 @@ as shown in the following example class: :dedent: The following sample code shows how you can instantiate a model for each class -and add the relationship between them: - -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php - :language: php - :dedent: - :start-after: begin one-to-one save - :end-before: end one-to-one save - -The following sample code shows how you can access the related models by using -the dynamic properties as defined in the example classes: - +and add the relationship between them. Click the :guilabel:`Output` button to +see sample MongoDB documents created by running the code:: .. io-code-block:: .. input:: /includes/eloquent-models/relationships/RelationshipController.php @@ -124,6 +115,15 @@ the dynamic properties as defined in the example classes: // ... } +The following sample code shows how you can access the related models by using +the dynamic properties as defined in the example classes: + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin planet orbit dynamic property example + :end-before: end planet orbit dynamic property example + .. _laravel-eloquent-relationship-one-to-many: One to Many Relationship @@ -170,26 +170,16 @@ example class: :dedent: The following sample code shows how you can instantiate a model for each class -and add the relationship between them: - -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php - :language: php - :dedent: - :start-after: begin one-to-many save - :end-before: end one-to-many save - -The following sample code shows how you can access the related models by using -the dynamic properties as defined in the example classes. Click the -:guilabel:`Output` button to see sample MongoDB documents created by running -the code: +and add the relationship between them. Click the :guilabel:`Output` button to +see sample MongoDB documents created by running the code: .. io-code-block:: .. input:: /includes/eloquent-models/relationships/RelationshipController.php :language: php :dedent: - :start-after: begin planet moons dynamic property example - :end-before: end planet moons dynamic property example + :start-after: begin one-to-many save + :end-before: end one-to-many save .. output:: :language: json @@ -221,6 +211,16 @@ the code: } ] +The following sample code shows how you can access the related models by using +the dynamic properties as defined in the example classes. + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin planet moons dynamic property example + :end-before: end planet moons dynamic property example + + .. _laravel-eloquent-relationship-many-to-many: Many to Many Relationship @@ -269,26 +269,16 @@ relationship with ``Planet`` as shown in the following example class: :dedent: The following sample code shows how you can instantiate a model for each class -and add the relationship between them: - -.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php - :language: php - :dedent: - :start-after: begin many-to-many save - :end-before: end many-to-many save - -The following sample code shows how you can access the related models by using -the dynamic properties as defined in the example classes. Click the -:guilabel:`Output` button to see sample MongoDB documents created by running -the code: +and add the relationship between them. Click the :guilabel:`Output` button to +see sample MongoDB documents created by running the code: .. io-code-block:: .. input:: /includes/eloquent-models/relationships/RelationshipController.php :language: php :dedent: - :start-after: begin many to many save - :end-before: end many to many save + :start-after: begin many-to-many save + :end-before: end many-to-many save .. output:: :language: json @@ -347,6 +337,16 @@ the code: } ] +The following sample code shows how you can access the related models by using +the dynamic properties as defined in the example classes. + +.. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php + :language: php + :dedent: + :start-after: begin many-to-many dynamic property example + :end-before: end many-to-many dynamic property example + + .. _laravel-embedded-document-pattern: Embedded Document Pattern diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php index 532f053a7..1941fe881 100644 --- a/docs/includes/eloquent-models/relationships/RelationshipController.php +++ b/docs/includes/eloquent-models/relationships/RelationshipController.php @@ -103,8 +103,19 @@ private function manyToMany() $explorer_jeanluc->planetsVisited()->attach($planet_mars); $explorer_jeanluc->planetsVisited()->attach($planet_jupiter); // end many-to-many save + } + private function manyToManyDynamic() + { + // begin many-to-many dynamic property example + $planet = Planet::first(); + $explorers = $planet->visitors; + + $space_explorer = SpaceExplorer:first(); + $planets_visited = $space_explorer->planetsVisited; + // end many-to-many dynamic property example } + private function embedsMany() { // begin embedsMany save From 389c76ad10f78e64cf785bf10e26e7899eb28cb9 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 5 Mar 2024 02:11:04 -0500 Subject: [PATCH 11/27] fixes --- docs/eloquent-models/relationships.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 9230b41c9..144f4a748 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -85,9 +85,10 @@ as shown in the following example class: The following sample code shows how you can instantiate a model for each class and add the relationship between them. Click the :guilabel:`Output` button to -see sample MongoDB documents created by running the code:: +see sample MongoDB documents created by running the code: .. io-code-block:: + .. input:: /includes/eloquent-models/relationships/RelationshipController.php :language: php :dedent: @@ -157,7 +158,7 @@ One to Many Example The following example class shows how to define a ``HasMany`` one to many relationship between a ``Planet`` parent model and ``Moon`` child model. -.. literalinclude:: includes/eloquent-models/relationships/PlanetOneToMany.php +.. literalinclude:: /includes/eloquent-models/relationships/PlanetOneToMany.php :language: php :dedent: @@ -165,7 +166,7 @@ To define the inverse of the relationship on ``Moon``, add the dynamic property and call the ``belongsTo()`` method on it as shown in the following example class: -.. literalinclude:: includes/eloquent-models/relationships/MoonOneToMany.php +.. literalinclude:: /includes/eloquent-models/relationships/MoonOneToMany.php :language: php :dedent: From b82c2ee2358d6af38122419c85fabb010f496645 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 5 Mar 2024 02:27:45 -0500 Subject: [PATCH 12/27] fixes --- docs/eloquent-models/relationships.txt | 101 ++++++++++++++----------- 1 file changed, 56 insertions(+), 45 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 144f4a748..ba704bafd 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -15,7 +15,7 @@ Overview -------- This page describes the following Laravel Eloquent and MongoDB-specific -relationships available in {+odm-short+} and shows examples on how to define +relationships available in {+odm-short+} and shows examples of how to define and use them: - :ref:`One to one relationship `, @@ -27,25 +27,23 @@ and use them: - :ref:`Embedded document pattern `, a MongoDB-specific relationship that can represent a one to one or one to many relationship, created by using the ``embedsOne()`` or ``embedsMany()`` method -- :ref:`Cross-database Relationships `, - required when you want to define - relationships between MongoDB and SQL models. +- :ref:`Cross-database relationships `, + required when you want to create relationships between MongoDB and SQL models -To establish a relationship, add a function to the model class that calls -the appropriate relationship method. This function allows you to access the -related model as a **dynamic property**. A dynamic property lets you access -the related model by using the same syntax as you use to access a property -on the model. +Add a function to the model class that calls the appropriate relationship method +to establish a relationship. This function allows you to access the related +model as a **dynamic property**. A dynamic property lets you access the +related model by using the same syntax as you use to access a property on the +model. .. _laravel-eloquent-relationship-one-to-one: One to One Relationship ----------------------- -A one to one relationship between models consists of a model record that -is related to exactly one other type of model record. In MongoDB, a record -is represented as a document and different model types exist in separate -collections. +A one to one relationship between models consists of a model record related to +exactly one other type of model record. In MongoDB, a record is represented as +a document, and different model types exist in separate collections. When you add a one to one relationship by using the method, Eloquent lets you access the model by using a dynamic property and stores the model's document @@ -58,9 +56,6 @@ When you add the inverse of the relationship by using the ``belongsTo()`` method, Eloquent lets you access the model by using a dynamic property, but does not add any fields. -The following section shows an example of how to create a one to one -relationship. - To learn more about one to one relationships, see `One to One `__ in the Laravel docs. @@ -83,8 +78,8 @@ as shown in the following example class: :language: php :dedent: -The following sample code shows how you can instantiate a model for each class -and add the relationship between them. Click the :guilabel:`Output` button to +The following sample code shows how to instantiate a model for each class +and add the relationship between them. Click the :guilabel:`View Output` button to see sample MongoDB documents created by running the code: .. io-code-block:: @@ -116,7 +111,7 @@ see sample MongoDB documents created by running the code: // ... } -The following sample code shows how you can access the related models by using +The following sample code shows how to access the related models by using the dynamic properties as defined in the example classes: .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php @@ -131,23 +126,20 @@ One to Many Relationship ------------------------ A one to many relationship between models consists of a model that is -the parent and one or more related model records which are the children. +the parent and one or more related child model records. When you add a one to many relationship method, Eloquent lets you access the model by using a dynamic property and stores the parent model's document ID on each of the child model documents. In {+odm-short+}, you can define a one to many relationship by using the -``hasMany()`` method on the parent class and optionally the ``belongsTo()`` +``hasMany()`` method on the parent class and, optionally, the ``belongsTo()`` method on the child class. When you add the inverse of the relationship by using the ``belongsTo()`` method, Eloquent lets you access the parent model by using a dynamic property without adding any fields. -The following section shows an example of how to create a one to many -relationship. - To learn more about one to many relationships, see `One to Many `__ in the Laravel docs. @@ -163,15 +155,15 @@ relationship between a ``Planet`` parent model and ``Moon`` child model. :dedent: To define the inverse of the relationship on ``Moon``, add the dynamic -property and call the ``belongsTo()`` method on it as shown in the following +property and call the ``belongsTo()`` method on it, as shown in the following example class: .. literalinclude:: /includes/eloquent-models/relationships/MoonOneToMany.php :language: php :dedent: -The following sample code shows how you can instantiate a model for each class -and add the relationship between them. Click the :guilabel:`Output` button to +The following sample code shows how ton instantiate a model for each class +and add the relationship between them. Click the :guilabel:`View Output` button to see sample MongoDB documents created by running the code: .. io-code-block:: @@ -212,7 +204,7 @@ see sample MongoDB documents created by running the code: } ] -The following sample code shows how you can access the related models by using +The following sample code shows how to access the related models by using the dynamic properties as defined in the example classes. .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php @@ -236,8 +228,8 @@ In {+odm-short+}, you can define a many to many relationship by adding the When you define a many to many relationship in a relational database, Laravel creates a pivot table to track the relationships. When you use {+odm-short+}, -it omits the pivot table creation and instead adds the related document IDs -to a document field, derived from the related model class name. +it omits the pivot table creation and adds the related document IDs to a +document field, derived from the related model class name. .. tip:: @@ -245,13 +237,13 @@ to a document field, derived from the related model class name. the pivot table parameter from the ``belongsToMany()`` constructor or set it to ``null``. -The following section shows an example of how to create a many to many -relationship between model classes. - To learn more about many to many relationships in Laravel, see `Many to Many `__ in the Laravel docs. +The following section shows an example of how to create a many to many +relationship between model classes. + Many to Many Example ~~~~~~~~~~~~~~~~~~~~ @@ -269,8 +261,8 @@ relationship with ``Planet`` as shown in the following example class: :language: php :dedent: -The following sample code shows how you can instantiate a model for each class -and add the relationship between them. Click the :guilabel:`Output` button to +The following sample code shows how to instantiate a model for each class +and add the relationship between them. Click the :guilabel:`View Output` button to see sample MongoDB documents created by running the code: .. io-code-block:: @@ -338,7 +330,7 @@ see sample MongoDB documents created by running the code: } ] -The following sample code shows how you can access the related models by using +The following sample code shows how to access the related models by using the dynamic properties as defined in the example classes. .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php @@ -357,8 +349,9 @@ In MongoDB, the embedded document pattern adds the related model's data into the parent model instead of keeping foreign key references. This pattern when you must optimize for one or more of the following requirements: -- Keep related data together in a single collection -- Perform atomic updates on multiple fields of the document and the related data +- Keep associated data together in a single collection +- Perform atomic updates on multiple fields of the document and the associated + data - Reduce the number of reads required to fetch the data In {+odm-short+}, you can define embedded documents by using one of the @@ -372,15 +365,15 @@ following dynamic property methods: These methods return Eloquent collections, which differ from query builder objects. -The following section shows an example of how to use the embedded document -pattern. - To learn more about the MongoDB embedded document pattern, see the following MongoDB server tutorials: - :manual:`Model One-to-One Relationships with Embedded Documents ` - :manual:`Model One-to-Many Relationships with Embedded Documents ` +The following section shows an example of how to use the embedded document +pattern. + Embedded Document Example ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -398,9 +391,9 @@ following example class: :language: php :dedent: -The following sample code shows how you can create a ``SpaceShip`` model and +The following sample code shows how to create a ``SpaceShip`` model and embed multiple ``Cargo`` models and the MongoDB document created by running the -code. Click the :guilabel:`Output` button to see sample MongoDB documents +code. Click the :guilabel:`View Output` button to see sample MongoDB documents created by running the code: .. io-code-block:: @@ -478,9 +471,9 @@ The ``Passenger`` model defines a ``BelongsToMany`` relationship with :language: php :dedent: -The following sample code shows how you can create a ``SpaceShip`` model in +The following sample code shows how to create a ``SpaceShip`` model in a MySQL database and related ``Passenger`` models in a MongoDB database and -the data created by running the code. Click the :guilabel:`Output` button to +the data created by running the code. Click the :guilabel:`View Output` button to see sample MongoDB documents created by running the code: .. io-code-block:: @@ -495,9 +488,27 @@ see sample MongoDB documents created by running the code: :language: none :visible: false + -- Row in the "space_ships" table +------+----------+ | id | name | +------+----------+ | 1234 | Nostromo | +------+----------+ + + // Document in the "passengers" collection + [ + { + _id: ObjectId('65e625e74903fd63af0a5524'), + name: 'Ellen Ripley', + space_ship_id: 1234, + // ... + }, + { + _id: ObjectId('65e625e74903fd63af0a5525'), + name: 'Dwayne Hicks', + space_ship_id: 1234, + // ... + } + ] + From 9dc003e951959ed53870d0df85c5777a3318205d Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 5 Mar 2024 10:48:57 -0500 Subject: [PATCH 13/27] update toc title and sample code wording --- docs/eloquent-models.txt | 2 +- docs/eloquent-models/relationships.txt | 20 ++++++++++---------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index 2e4bb40b2..35e939f4b 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -24,6 +24,6 @@ This section contains guidance on how to use Eloquent models in .. toctree:: - /eloquent-models/relationships + :doc:`Relationships ` diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index ba704bafd..fe18635ca 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -79,8 +79,8 @@ as shown in the following example class: :dedent: The following sample code shows how to instantiate a model for each class -and add the relationship between them. Click the :guilabel:`View Output` button to -see sample MongoDB documents created by running the code: +and add the relationship between them. Click the :guilabel:`View Output` +button to see the data created by running the code: .. io-code-block:: @@ -163,8 +163,8 @@ example class: :dedent: The following sample code shows how ton instantiate a model for each class -and add the relationship between them. Click the :guilabel:`View Output` button to -see sample MongoDB documents created by running the code: +and add the relationship between them. Click the :guilabel:`View Output` +button to see the data created by running the code: .. io-code-block:: @@ -262,8 +262,8 @@ relationship with ``Planet`` as shown in the following example class: :dedent: The following sample code shows how to instantiate a model for each class -and add the relationship between them. Click the :guilabel:`View Output` button to -see sample MongoDB documents created by running the code: +and add the relationship between them. Click the :guilabel:`View Output` +button to see the data created by running the code: .. io-code-block:: @@ -393,8 +393,8 @@ following example class: The following sample code shows how to create a ``SpaceShip`` model and embed multiple ``Cargo`` models and the MongoDB document created by running the -code. Click the :guilabel:`View Output` button to see sample MongoDB documents -created by running the code: +code. Click the :guilabel:`View Output` button to see the data created by +running the code: .. io-code-block:: @@ -473,8 +473,8 @@ The ``Passenger`` model defines a ``BelongsToMany`` relationship with The following sample code shows how to create a ``SpaceShip`` model in a MySQL database and related ``Passenger`` models in a MongoDB database and -the data created by running the code. Click the :guilabel:`View Output` button to -see sample MongoDB documents created by running the code: +the data created by running the code. Click the :guilabel:`View Output` button +to see the data created by running the code: .. io-code-block:: From 5dbd3875867d9b5266a2bffc35121320e9126377 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 5 Mar 2024 13:27:38 -0500 Subject: [PATCH 14/27] toctree fix --- docs/eloquent-models.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index 35e939f4b..e9ca923a2 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -24,6 +24,6 @@ This section contains guidance on how to use Eloquent models in .. toctree:: - :doc:`Relationships ` + Relationships From f5dbc6a583249bc5ae96fa867d2eb9ca5f487358 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 5 Mar 2024 13:37:28 -0500 Subject: [PATCH 15/27] remove install ToC entry --- docs/index.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.txt b/docs/index.txt index f22848b57..8ee11dbda 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -13,7 +13,6 @@ Laravel MongoDB :titlesonly: :maxdepth: 1 - /install /quick-start /retrieve /eloquent-models From 70310ef58cd2527106c9f3c4c4a3440715781857 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 5 Mar 2024 21:40:39 -0500 Subject: [PATCH 16/27] show correct code snippet --- docs/eloquent-models/relationships.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index fe18635ca..77f9bad5d 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -87,8 +87,8 @@ button to see the data created by running the code: .. input:: /includes/eloquent-models/relationships/RelationshipController.php :language: php :dedent: - :start-after: begin planet orbit dynamic property example - :end-before: end planet orbit dynamic property example + :start-after: begin one-to-one save + :end-before: end one-to-one save .. output:: :language: json From 8430d1c31b80013aac2c8129573336c6b4881a76 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Mar 2024 15:32:15 -0500 Subject: [PATCH 17/27] PRR fixes --- docs/eloquent-models.txt | 9 ++-- docs/eloquent-models/relationships.txt | 59 ++++++++++++++------------ 2 files changed, 36 insertions(+), 32 deletions(-) diff --git a/docs/eloquent-models.txt b/docs/eloquent-models.txt index e9ca923a2..21b8e8a70 100644 --- a/docs/eloquent-models.txt +++ b/docs/eloquent-models.txt @@ -12,14 +12,15 @@ Eloquent Models :keywords: php framework, odm Eloquent models are part of the Laravel Eloquent object-relational -mapping (ORM) framework that enable you to work with a database by using -model classes. The {+odm-short+} extends this framework to use similar -syntax to work with MongoDB as a database. +mapping (ORM) framework, which lets you to work with data in a relational +database by using model classes and Eloquent syntax. {+odm-short+} extends +this framework so that you can use Eloquent syntax to work with data in a +MongoDB database. This section contains guidance on how to use Eloquent models in {+odm-short+} to work with MongoDB in the following ways: -- :ref:`laravel-eloquent-model-relationships` shows how to add relationships +- :ref:`laravel-eloquent-model-relationships` shows how to define relationships between models .. toctree:: diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 77f9bad5d..dd95736ae 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -14,6 +14,17 @@ Eloquent Model Relationships Overview -------- +When you use a relational database, the Eloquent ORM stores models as rows +in tables that correspond to the model classes. When you use MongoDB, the +{+odm-short+} stores models as documents in collections that correspond to the +model classes. + +To define a relationship, add a function to the model class that calls the +appropriate relationship method. This function allows you to access the related +model as a **dynamic property**. A dynamic property lets you access the +related model by using the same syntax as you use to access a property on the +model. + This page describes the following Laravel Eloquent and MongoDB-specific relationships available in {+odm-short+} and shows examples of how to define and use them: @@ -30,24 +41,19 @@ and use them: - :ref:`Cross-database relationships `, required when you want to create relationships between MongoDB and SQL models -Add a function to the model class that calls the appropriate relationship method -to establish a relationship. This function allows you to access the related -model as a **dynamic property**. A dynamic property lets you access the -related model by using the same syntax as you use to access a property on the -model. - .. _laravel-eloquent-relationship-one-to-one: One to One Relationship ----------------------- A one to one relationship between models consists of a model record related to -exactly one other type of model record. In MongoDB, a record is represented as +exactly one other type of model record. + a document, and different model types exist in separate collections. -When you add a one to one relationship by using the method, Eloquent lets you -access the model by using a dynamic property and stores the model's document -ID on the related model. +When you add a one to one relationship, Eloquent lets you access the model by +using a dynamic property and stores the model's document ID on the related +model. In {+odm-short+}, you can define a one to one relationship by using the ``hasOne()`` method or ``belongsTo()`` method. @@ -58,7 +64,7 @@ does not add any fields. To learn more about one to one relationships, see `One to One `__ -in the Laravel docs. +in the Laravel documentation. One to One Example ~~~~~~~~~~~~~~~~~~ @@ -70,16 +76,15 @@ relationship between a ``Planet`` and ``Orbit`` model. :language: php :dedent: -The following example class uses a dynamic property and calls the -``belongsTo()`` method to define the inverse of the relationship on ``Orbit`` -as shown in the following example class: +The following example class shows how to define the inverse relationship with +``Orbit`` by using the ``belongsTo()`` method: .. literalinclude:: /includes/eloquent-models/relationships/OrbitOneToOne.php :language: php :dedent: The following sample code shows how to instantiate a model for each class -and add the relationship between them. Click the :guilabel:`View Output` +and add the relationship between them. Click the :guilabel:`View Output` button to see the data created by running the code: .. io-code-block:: @@ -142,7 +147,7 @@ without adding any fields. To learn more about one to many relationships, see `One to Many `__ -in the Laravel docs. +in the Laravel documentation. One to Many Example ~~~~~~~~~~~~~~~~~~~ @@ -163,7 +168,7 @@ example class: :dedent: The following sample code shows how ton instantiate a model for each class -and add the relationship between them. Click the :guilabel:`View Output` +and add the relationship between them. Click the :guilabel:`View Output` button to see the data created by running the code: .. io-code-block:: @@ -213,7 +218,6 @@ the dynamic properties as defined in the example classes. :start-after: begin planet moons dynamic property example :end-before: end planet moons dynamic property example - .. _laravel-eloquent-relationship-many-to-many: Many to Many Relationship @@ -239,7 +243,7 @@ document field, derived from the related model class name. To learn more about many to many relationships in Laravel, see `Many to Many `__ -in the Laravel docs. +in the Laravel documentation. The following section shows an example of how to create a many to many relationship between model classes. @@ -262,7 +266,7 @@ relationship with ``Planet`` as shown in the following example class: :dedent: The following sample code shows how to instantiate a model for each class -and add the relationship between them. Click the :guilabel:`View Output` +and add the relationship between them. Click the :guilabel:`View Output` button to see the data created by running the code: .. io-code-block:: @@ -339,20 +343,19 @@ the dynamic properties as defined in the example classes. :start-after: begin many-to-many dynamic property example :end-before: end many-to-many dynamic property example - .. _laravel-embedded-document-pattern: Embedded Document Pattern ------------------------- In MongoDB, the embedded document pattern adds the related model's data into -the parent model instead of keeping foreign key references. This pattern -when you must optimize for one or more of the following requirements: +the parent model instead of keeping foreign key references. Use this pattern +to meet one or more of the following requirements: -- Keep associated data together in a single collection -- Perform atomic updates on multiple fields of the document and the associated +- Keeping associated data together in a single collection +- Performing atomic updates on multiple fields of the document and the associated data -- Reduce the number of reads required to fetch the data +- Reducing the number of reads required to fetch the data In {+odm-short+}, you can define embedded documents by using one of the following dynamic property methods: @@ -393,7 +396,7 @@ following example class: The following sample code shows how to create a ``SpaceShip`` model and embed multiple ``Cargo`` models and the MongoDB document created by running the -code. Click the :guilabel:`View Output` button to see the data created by +code. Click the :guilabel:`View Output` button to see the data created by running the code: .. io-code-block:: @@ -473,7 +476,7 @@ The ``Passenger`` model defines a ``BelongsToMany`` relationship with The following sample code shows how to create a ``SpaceShip`` model in a MySQL database and related ``Passenger`` models in a MongoDB database and -the data created by running the code. Click the :guilabel:`View Output` button +the data created by running the code. Click the :guilabel:`View Output` button to see the data created by running the code: .. io-code-block:: From 6f2ea84112b099b97d30e2dd7b09596b1880dc6c Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Mar 2024 15:33:04 -0500 Subject: [PATCH 18/27] remove stray text --- docs/eloquent-models/relationships.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index dd95736ae..d60b952f8 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -49,8 +49,6 @@ One to One Relationship A one to one relationship between models consists of a model record related to exactly one other type of model record. -a document, and different model types exist in separate collections. - When you add a one to one relationship, Eloquent lets you access the model by using a dynamic property and stores the model's document ID on the related model. From 65e96487ddafbbdebf96872daec5a877d7fdbf1d Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Mar 2024 15:51:26 -0500 Subject: [PATCH 19/27] add tip on schema --- docs/eloquent-models/relationships.txt | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index d60b952f8..2a8cd01e4 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -458,7 +458,7 @@ Cross-Database Relationship Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example class creates a ``hasMany`` relationship between a -``SpaceShip`` model stored in a MySQL database and a ``Passenger`` model +``SpaceShip`` model stored in a relational database and a ``Passenger`` model stored in a MongoDB database: .. literalinclude:: /includes/eloquent-models/relationships/SpaceShipCrossHasMany.php @@ -472,6 +472,16 @@ The ``Passenger`` model defines a ``BelongsToMany`` relationship with :language: php :dedent: +.. tip:: + + Make sure that your primary key defined in your relational database table + schema matches the one that your model uses. To learn more about Laravel + primary keys and schema definitions, see the following pages in the Laravel + documentation: + + - `Primary Keys `__ + - `Database: Migrations `__ + The following sample code shows how to create a ``SpaceShip`` model in a MySQL database and related ``Passenger`` models in a MongoDB database and the data created by running the code. Click the :guilabel:`View Output` button From d8609e90e95631cbf8096cd1f769cb37ba11146b Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Mar 2024 16:01:29 -0500 Subject: [PATCH 20/27] add right nav and update wording in overview --- docs/eloquent-models/relationships.txt | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 2a8cd01e4..1406ab07b 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -11,6 +11,12 @@ Eloquent Model Relationships .. meta:: :keywords: php framework, odm, code example, entity relationship, eloquent +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + Overview -------- @@ -25,7 +31,7 @@ model as a **dynamic property**. A dynamic property lets you access the related model by using the same syntax as you use to access a property on the model. -This page describes the following Laravel Eloquent and MongoDB-specific +The following sections describe the Laravel Eloquent and MongoDB-specific relationships available in {+odm-short+} and shows examples of how to define and use them: From b8b54dde41f25c7135334d0f0b28d82f98368943 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Mar 2024 16:06:16 -0500 Subject: [PATCH 21/27] code snippet fixes --- .../relationships/CargoEmbedsMany.php | 4 +++- .../relationships/MoonOneToMany.php | 13 +++++----- .../relationships/OrbitOneToOne.php | 13 +++++----- .../relationships/PassengerCrossBelongsTo.php | 15 ++++++------ .../relationships/PlanetManyToMany.php | 13 +++++----- .../relationships/PlanetOneToMany.php | 13 +++++----- .../relationships/PlanetOneToOne.php | 13 +++++----- .../relationships/RelationshipController.php | 24 ++++++++----------- .../relationships/SpaceExplorerManyToMany.php | 13 +++++----- .../relationships/SpaceShipCrossHasMany.php | 14 ++++++----- .../relationships/SpaceShipEmbedsMany.php | 13 +++++----- 11 files changed, 78 insertions(+), 70 deletions(-) diff --git a/docs/includes/eloquent-models/relationships/CargoEmbedsMany.php b/docs/includes/eloquent-models/relationships/CargoEmbedsMany.php index 2030f855b..3ce144815 100644 --- a/docs/includes/eloquent-models/relationships/CargoEmbedsMany.php +++ b/docs/includes/eloquent-models/relationships/CargoEmbedsMany.php @@ -1,10 +1,12 @@ belongsTo(Planet::class); - } + protected $connection = 'mongodb'; + public function planet(): BelongsTo + { + return $this->belongsTo(Planet::class); + } } diff --git a/docs/includes/eloquent-models/relationships/OrbitOneToOne.php b/docs/includes/eloquent-models/relationships/OrbitOneToOne.php index 05a65bee7..4cb526309 100644 --- a/docs/includes/eloquent-models/relationships/OrbitOneToOne.php +++ b/docs/includes/eloquent-models/relationships/OrbitOneToOne.php @@ -1,5 +1,7 @@ belongsTo(Planet::class); - } + protected $connection = 'mongodb'; + public function planet(): BelongsTo + { + return $this->belongsTo(Planet::class); + } } diff --git a/docs/includes/eloquent-models/relationships/PassengerCrossBelongsTo.php b/docs/includes/eloquent-models/relationships/PassengerCrossBelongsTo.php index 8ae6b059a..4ceb7c45b 100644 --- a/docs/includes/eloquent-models/relationships/PassengerCrossBelongsTo.php +++ b/docs/includes/eloquent-models/relationships/PassengerCrossBelongsTo.php @@ -1,17 +1,18 @@ BelongsTo(SpaceShip::class); - } + protected $connection = 'mongodb'; + public function spaceship(): BelongsTo + { + return $this->belongsTo(SpaceShip::class); + } } diff --git a/docs/includes/eloquent-models/relationships/PlanetManyToMany.php b/docs/includes/eloquent-models/relationships/PlanetManyToMany.php index 8424d22af..4059d634d 100644 --- a/docs/includes/eloquent-models/relationships/PlanetManyToMany.php +++ b/docs/includes/eloquent-models/relationships/PlanetManyToMany.php @@ -1,5 +1,7 @@ belongsToMany(SpaceExplorer::class); - } + protected $connection = 'mongodb'; + public function visitors(): BelongsToMany + { + return $this->belongsToMany(SpaceExplorer::class); + } } diff --git a/docs/includes/eloquent-models/relationships/PlanetOneToMany.php b/docs/includes/eloquent-models/relationships/PlanetOneToMany.php index 77ed3f4c1..679877ae5 100644 --- a/docs/includes/eloquent-models/relationships/PlanetOneToMany.php +++ b/docs/includes/eloquent-models/relationships/PlanetOneToMany.php @@ -1,5 +1,7 @@ hasMany(Moon::class); - } + protected $connection = 'mongodb'; + public function moons(): HasMany + { + return $this->hasMany(Moon::class); + } } diff --git a/docs/includes/eloquent-models/relationships/PlanetOneToOne.php b/docs/includes/eloquent-models/relationships/PlanetOneToOne.php index b292a4670..e3137ab3a 100644 --- a/docs/includes/eloquent-models/relationships/PlanetOneToOne.php +++ b/docs/includes/eloquent-models/relationships/PlanetOneToOne.php @@ -1,5 +1,7 @@ hasOne(Orbit::class); - } + protected $connection = 'mongodb'; + public function orbit(): HasOne + { + return $this->hasOne(Orbit::class); + } } diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php index 1941fe881..5451f1e71 100644 --- a/docs/includes/eloquent-models/relationships/RelationshipController.php +++ b/docs/includes/eloquent-models/relationships/RelationshipController.php @@ -1,14 +1,17 @@ name = 'Mars'; $planet_mars->save(); - $planet_jupiter= new Planet(); + $planet_jupiter = new Planet(); $planet_jupiter->name = 'Jupiter'; $planet_jupiter->save(); @@ -124,11 +127,11 @@ private function embedsMany() $spaceship->save(); $cargo_spice = new Cargo(); - $cargo_spice->name = "spice"; + $cargo_spice->name = 'spice'; $cargo_spice->weight = 50; $cargo_hyperdrive = new Cargo(); - $cargo_hyperdrive->name = "hyperdrive"; + $cargo_hyperdrive->name = 'hyperdrive'; $cargo_hyperdrive->weight = 25; $spaceship->cargo()->attach($cargo_spice); @@ -136,7 +139,6 @@ private function embedsMany() // end embedsMany save } - private function crossDatabase() { // begin cross-database save @@ -156,7 +158,6 @@ private function crossDatabase() // end cross-database save } - /** * Store a newly created resource in storage. */ @@ -167,16 +168,14 @@ public function store(Request $request) return; } - - /** * Display the specified resource. */ public function show() { return view('browse_planets', [ - 'planets' => Planet::take(10) - ->get() + 'planets' => Planet::take(10) + ->get(), ]); } @@ -185,7 +184,6 @@ public function show() */ public function edit(Planet $planet) { - // } /** @@ -193,7 +191,6 @@ public function edit(Planet $planet) */ public function update(Request $request, Planet $planet) { - // } /** @@ -201,6 +198,5 @@ public function update(Request $request, Planet $planet) */ public function destroy(Planet $planet) { - // } } diff --git a/docs/includes/eloquent-models/relationships/SpaceExplorerManyToMany.php b/docs/includes/eloquent-models/relationships/SpaceExplorerManyToMany.php index ee7221b7e..aa9b2829d 100644 --- a/docs/includes/eloquent-models/relationships/SpaceExplorerManyToMany.php +++ b/docs/includes/eloquent-models/relationships/SpaceExplorerManyToMany.php @@ -1,5 +1,7 @@ belongsToMany(Planet::class); - } + protected $connection = 'mongodb'; + public function planetsVisited(): BelongsToMany + { + return $this->belongsToMany(Planet::class); + } } diff --git a/docs/includes/eloquent-models/relationships/SpaceShipCrossHasMany.php b/docs/includes/eloquent-models/relationships/SpaceShipCrossHasMany.php index 1ba13d213..1f3c5d120 100644 --- a/docs/includes/eloquent-models/relationships/SpaceShipCrossHasMany.php +++ b/docs/includes/eloquent-models/relationships/SpaceShipCrossHasMany.php @@ -1,5 +1,7 @@ hasMany(Passenger::class); - } + protected $connection = 'sqlite'; + public function passengers(): HasMany + { + return $this->hasMany(Passenger::class); + } } diff --git a/docs/includes/eloquent-models/relationships/SpaceShipEmbedsMany.php b/docs/includes/eloquent-models/relationships/SpaceShipEmbedsMany.php index 93880e309..d28971783 100644 --- a/docs/includes/eloquent-models/relationships/SpaceShipEmbedsMany.php +++ b/docs/includes/eloquent-models/relationships/SpaceShipEmbedsMany.php @@ -1,5 +1,7 @@ embedsMany(Cargo::class); - } + protected $connection = 'mongodb'; + public function cargo(): EmbedsMany + { + return $this->embedsMany(Cargo::class); + } } From 2c0526f04ea2906d1cc929da0d10e6504ef86adf Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Mar 2024 17:03:52 -0500 Subject: [PATCH 22/27] code linter fixes --- docs/eloquent-models/relationships.txt | 24 ++-- .../relationships/RelationshipController.php | 130 ++++++++---------- .../Passenger.php} | 0 .../SpaceShip.php} | 0 .../{CargoEmbedsMany.php => embeds/Cargo.php} | 0 .../SpaceShip.php} | 0 .../Planet.php} | 0 .../SpaceExplorer.php} | 0 .../Moon.php} | 0 .../Planet.php} | 0 .../Orbit.php} | 0 .../Planet.php} | 0 12 files changed, 73 insertions(+), 81 deletions(-) rename docs/includes/eloquent-models/relationships/{PassengerCrossBelongsTo.php => cross-db/Passenger.php} (100%) rename docs/includes/eloquent-models/relationships/{SpaceShipCrossHasMany.php => cross-db/SpaceShip.php} (100%) rename docs/includes/eloquent-models/relationships/{CargoEmbedsMany.php => embeds/Cargo.php} (100%) rename docs/includes/eloquent-models/relationships/{SpaceShipEmbedsMany.php => embeds/SpaceShip.php} (100%) rename docs/includes/eloquent-models/relationships/{PlanetManyToMany.php => many-to-many/Planet.php} (100%) rename docs/includes/eloquent-models/relationships/{SpaceExplorerManyToMany.php => many-to-many/SpaceExplorer.php} (100%) rename docs/includes/eloquent-models/relationships/{MoonOneToMany.php => one-to-many/Moon.php} (100%) rename docs/includes/eloquent-models/relationships/{PlanetOneToMany.php => one-to-many/Planet.php} (100%) rename docs/includes/eloquent-models/relationships/{OrbitOneToOne.php => one-to-one/Orbit.php} (100%) rename docs/includes/eloquent-models/relationships/{PlanetOneToOne.php => one-to-one/Planet.php} (100%) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 1406ab07b..1713a5f32 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -76,14 +76,14 @@ One to One Example The following example class shows how to define a ``HasOne`` one to one relationship between a ``Planet`` and ``Orbit`` model. -.. literalinclude:: /includes/eloquent-models/relationships/PlanetOneToOne.php +.. literalinclude:: /includes/eloquent-models/relationships/one-to-one/Planet.php :language: php :dedent: The following example class shows how to define the inverse relationship with ``Orbit`` by using the ``belongsTo()`` method: -.. literalinclude:: /includes/eloquent-models/relationships/OrbitOneToOne.php +.. literalinclude:: /includes/eloquent-models/relationships/one-to-one/Orbit.php :language: php :dedent: @@ -159,7 +159,7 @@ One to Many Example The following example class shows how to define a ``HasMany`` one to many relationship between a ``Planet`` parent model and ``Moon`` child model. -.. literalinclude:: /includes/eloquent-models/relationships/PlanetOneToMany.php +.. literalinclude:: /includes/eloquent-models/relationships/one-to-many/Planet.php :language: php :dedent: @@ -167,7 +167,7 @@ To define the inverse of the relationship on ``Moon``, add the dynamic property and call the ``belongsTo()`` method on it, as shown in the following example class: -.. literalinclude:: /includes/eloquent-models/relationships/MoonOneToMany.php +.. literalinclude:: /includes/eloquent-models/relationships/one-to-many/Moon.php :language: php :dedent: @@ -258,14 +258,14 @@ Many to Many Example The following ``Planet`` class shows how to define a ``BelongsToMany`` many to many relationship with and a ``SpaceExplorer`` model. -.. literalinclude:: /includes/eloquent-models/relationships/PlanetManyToMany.php +.. literalinclude:: /includes/eloquent-models/relationships/many-to-many/Planet.php :language: php :dedent: The ``SpaceExplorer`` model defines a ``BelongsToMany`` many to many relationship with ``Planet`` as shown in the following example class: -.. literalinclude:: /includes/eloquent-models/relationships/SpaceExplorerManyToMany.php +.. literalinclude:: /includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php :language: php :dedent: @@ -387,14 +387,14 @@ Embedded Document Example The following example class shows how to define an ``embedsMany`` one to many relationship between a ``SpaceShip`` and ``Cargo`` model: -.. literalinclude:: /includes/eloquent-models/relationships/SpaceShipEmbedsMany.php +.. literalinclude:: /includes/eloquent-models/relationships/embeds/SpaceShip.php :language: php :dedent: The embedded model class omits the relationship definition as shown in the following example class: -.. literalinclude:: /includes/eloquent-models/relationships/CargoEmbedsMany.php +.. literalinclude:: /includes/eloquent-models/relationships/embeds/Cargo.php :language: php :dedent: @@ -444,8 +444,8 @@ Cross-Database Relationships A cross-database relationship in {+odm-short+} is a relationship between models stored in a SQL relational database and models stored in a MongoDB database. -When you add a cross-database relationship, Eloquent lets you access a -related model by using a dynamic property. +When you add a cross-database relationship, Eloquent lets you access the +related models by using a dynamic property. {+odm-short+} supports the following cross-database relationship methods: @@ -467,14 +467,14 @@ The following example class creates a ``hasMany`` relationship between a ``SpaceShip`` model stored in a relational database and a ``Passenger`` model stored in a MongoDB database: -.. literalinclude:: /includes/eloquent-models/relationships/SpaceShipCrossHasMany.php +.. literalinclude:: /includes/eloquent-models/relationships/cross-db/SpaceShip.php :language: php :dedent: The ``Passenger`` model defines a ``BelongsToMany`` relationship with ``SpaceShip`` as shown in the following example class: -.. literalinclude:: /includes/eloquent-models/relationships/PassengerCrossBelongsTo.php +.. literalinclude:: /includes/eloquent-models/relationships/cross-db/Passenger.php :language: php :dedent: diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php index 5451f1e71..0c015e329 100644 --- a/docs/includes/eloquent-models/relationships/RelationshipController.php +++ b/docs/includes/eloquent-models/relationships/RelationshipController.php @@ -8,9 +8,7 @@ use App\Models\Planet; use Illuminate\Http\Request; -use function view; - -class PlanetController extends Controller +class RelationshipController extends Controller { private function oneToOne() { @@ -36,16 +34,16 @@ private function oneToMany() $planet->diameter_km = 142984; $planet->save(); - $moon_1 = new Moon(); - $moon_1->name = 'Ganymede'; - $moon_1->orbital_period = 7.15; + $moon1 = new Moon(); + $moon1->name = 'Ganymede'; + $moon1->orbital_period = 7.15; - $moon_2 = new Moon(); - $moon_2->name = 'Europa'; - $moon_2->orbital_period = 3.55; + $moon2 = new Moon(); + $moon2->name = 'Europa'; + $moon2->orbital_period = 3.55; - $planet->moons()->save($moon_1); - $planet->moons()->save($moon_2); + $planet->moons()->save($moon1); + $planet->moons()->save($moon2); // end one-to-many save } @@ -53,10 +51,10 @@ private function planetOrbitDynamic() { // begin planet orbit dynamic property example $planet = Planet::first(); - $related_orbit = $planet->orbit; + $relatedOrbit = $planet->orbit; $orbit = Orbit::first(); - $related_planet = $orbit->planet; + $relatedPlanet = $orbit->planet; // end planet orbit dynamic property example } @@ -64,47 +62,47 @@ private function planetMoonsDynamic() { // begin planet moons dynamic property example $planet = Planet::first(); - $related_moons = $planet->moons; + $relatedMoons = $planet->moons; $moon = Moon::first(); - $related_planet = $moon->planet; + $relatedPlanet = $moon->planet; // end planet moons dynamic property example } private function manyToMany() { // begin many-to-many save - $planet_earth = new Planet(); - $planet_earth->name = 'Earth'; - $planet_earth->save(); - - $planet_mars = new Planet(); - $planet_mars->name = 'Mars'; - $planet_mars->save(); - - $planet_jupiter = new Planet(); - $planet_jupiter->name = 'Jupiter'; - $planet_jupiter->save(); - - $explorer_tanya = new SpaceExplorer(); - $explorer_tanya->name = 'Tanya Kirbuk'; - $explorer_tanya->save(); - - $explorer_mark = new SpaceExplorer(); - $explorer_mark->name = 'Mark Watney'; - $explorer_mark->save(); - - $explorer_jeanluc = new SpaceExplorer(); - $explorer_jeanluc->name = 'Jean-Luc Picard'; - $explorer_jeanluc->save(); - - $explorer_tanya->planetsVisited()->attach($planet_earth); - $explorer_tanya->planetsVisited()->attach($planet_jupiter); - $explorer_mark->planetsVisited()->attach($planet_earth); - $explorer_mark->planetsVisited()->attach($planet_mars); - $explorer_jeanluc->planetsVisited()->attach($planet_earth); - $explorer_jeanluc->planetsVisited()->attach($planet_mars); - $explorer_jeanluc->planetsVisited()->attach($planet_jupiter); + $planetEarth = new Planet(); + $planetEarth->name = 'Earth'; + $planetEarth->save(); + + $planetMars = new Planet(); + $planetMars->name = 'Mars'; + $planetMars->save(); + + $planetJupiter = new Planet(); + $planetJupiter->name = 'Jupiter'; + $planetJupiter->save(); + + $explorerTanya = new SpaceExplorer(); + $explorerTanya->name = 'Tanya Kirbuk'; + $explorerTanya->save(); + + $explorerMark = new SpaceExplorer(); + $explorerMark->name = 'Mark Watney'; + $explorerMark->save(); + + $explorerJeanluc = new SpaceExplorer(); + $explorerJeanluc->name = 'Jean-Luc Picard'; + $explorerJeanluc->save(); + + $explorerTanya->planetsVisited()->attach($planetEarth); + $explorerTanya->planetsVisited()->attach($planetJupiter); + $explorerMark->planetsVisited()->attach($planetEarth); + $explorerMark->planetsVisited()->attach($planetMars); + $explorerJeanluc->planetsVisited()->attach($planetEarth); + $explorerJeanluc->planetsVisited()->attach($planetMars); + $explorerJeanluc->planetsVisited()->attach($planetJupiter); // end many-to-many save } @@ -114,8 +112,8 @@ private function manyToManyDynamic() $planet = Planet::first(); $explorers = $planet->visitors; - $space_explorer = SpaceExplorer:first(); - $planets_visited = $space_explorer->planetsVisited; + $spaceExplorer = SpaceExplorer:first(); + $explored = $spaceExplorer->planetsVisited; // end many-to-many dynamic property example } @@ -126,16 +124,16 @@ private function embedsMany() $spaceship->name = 'The Millenium Falcon'; $spaceship->save(); - $cargo_spice = new Cargo(); - $cargo_spice->name = 'spice'; - $cargo_spice->weight = 50; + $cargoSpice = new Cargo(); + $cargoSpice->name = 'spice'; + $cargoSpice->weight = 50; - $cargo_hyperdrive = new Cargo(); - $cargo_hyperdrive->name = 'hyperdrive'; - $cargo_hyperdrive->weight = 25; + $cargoHyperdrive = new Cargo(); + $cargoHyperdrive->name = 'hyperdrive'; + $cargoHyperdrive->weight = 25; - $spaceship->cargo()->attach($cargo_spice); - $spaceship->cargo()->attach($cargo_hyperdrive); + $spaceship->cargo()->attach($cargoSpice); + $spaceship->cargo()->attach($cargoHyperdrive); // end embedsMany save } @@ -147,14 +145,14 @@ private function crossDatabase() $spaceship->name = 'Nostromo'; $spaceship->save(); - $passenger_ellen = new Passenger(); - $passenger_ellen->name = 'Ellen Ripley'; + $passengerEllen = new Passenger(); + $passengerEllen->name = 'Ellen Ripley'; - $passenger_dwayne = new Passenger(); - $passenger_dwayne->name = 'Dwayne Hicks'; + $passengerDwayne = new Passenger(); + $passengerDwayne->name = 'Dwayne Hicks'; - $spaceship->passengers()->save($passenger_ellen); - $spaceship->passengers()->save($passenger_dwayne); + $spaceship->passengers()->save($passengerEllen); + $spaceship->passengers()->save($passengerDwayne); // end cross-database save } @@ -163,9 +161,6 @@ private function crossDatabase() */ public function store(Request $request) { - oneToMany(); - - return; } /** @@ -173,10 +168,7 @@ public function store(Request $request) */ public function show() { - return view('browse_planets', [ - 'planets' => Planet::take(10) - ->get(), - ]); + return 'ok'; } /** diff --git a/docs/includes/eloquent-models/relationships/PassengerCrossBelongsTo.php b/docs/includes/eloquent-models/relationships/cross-db/Passenger.php similarity index 100% rename from docs/includes/eloquent-models/relationships/PassengerCrossBelongsTo.php rename to docs/includes/eloquent-models/relationships/cross-db/Passenger.php diff --git a/docs/includes/eloquent-models/relationships/SpaceShipCrossHasMany.php b/docs/includes/eloquent-models/relationships/cross-db/SpaceShip.php similarity index 100% rename from docs/includes/eloquent-models/relationships/SpaceShipCrossHasMany.php rename to docs/includes/eloquent-models/relationships/cross-db/SpaceShip.php diff --git a/docs/includes/eloquent-models/relationships/CargoEmbedsMany.php b/docs/includes/eloquent-models/relationships/embeds/Cargo.php similarity index 100% rename from docs/includes/eloquent-models/relationships/CargoEmbedsMany.php rename to docs/includes/eloquent-models/relationships/embeds/Cargo.php diff --git a/docs/includes/eloquent-models/relationships/SpaceShipEmbedsMany.php b/docs/includes/eloquent-models/relationships/embeds/SpaceShip.php similarity index 100% rename from docs/includes/eloquent-models/relationships/SpaceShipEmbedsMany.php rename to docs/includes/eloquent-models/relationships/embeds/SpaceShip.php diff --git a/docs/includes/eloquent-models/relationships/PlanetManyToMany.php b/docs/includes/eloquent-models/relationships/many-to-many/Planet.php similarity index 100% rename from docs/includes/eloquent-models/relationships/PlanetManyToMany.php rename to docs/includes/eloquent-models/relationships/many-to-many/Planet.php diff --git a/docs/includes/eloquent-models/relationships/SpaceExplorerManyToMany.php b/docs/includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php similarity index 100% rename from docs/includes/eloquent-models/relationships/SpaceExplorerManyToMany.php rename to docs/includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php diff --git a/docs/includes/eloquent-models/relationships/MoonOneToMany.php b/docs/includes/eloquent-models/relationships/one-to-many/Moon.php similarity index 100% rename from docs/includes/eloquent-models/relationships/MoonOneToMany.php rename to docs/includes/eloquent-models/relationships/one-to-many/Moon.php diff --git a/docs/includes/eloquent-models/relationships/PlanetOneToMany.php b/docs/includes/eloquent-models/relationships/one-to-many/Planet.php similarity index 100% rename from docs/includes/eloquent-models/relationships/PlanetOneToMany.php rename to docs/includes/eloquent-models/relationships/one-to-many/Planet.php diff --git a/docs/includes/eloquent-models/relationships/OrbitOneToOne.php b/docs/includes/eloquent-models/relationships/one-to-one/Orbit.php similarity index 100% rename from docs/includes/eloquent-models/relationships/OrbitOneToOne.php rename to docs/includes/eloquent-models/relationships/one-to-one/Orbit.php diff --git a/docs/includes/eloquent-models/relationships/PlanetOneToOne.php b/docs/includes/eloquent-models/relationships/one-to-one/Planet.php similarity index 100% rename from docs/includes/eloquent-models/relationships/PlanetOneToOne.php rename to docs/includes/eloquent-models/relationships/one-to-one/Planet.php From d66b4e5f2b85d181150060438402f4e94a42a088 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Mar 2024 17:15:26 -0500 Subject: [PATCH 23/27] remove unnecessary linebreaks --- docs/eloquent-models/relationships.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 1713a5f32..48bfe453f 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -312,7 +312,6 @@ button to see the data created by running the code: ] // Documents in the "space_explorers" collection - [ { _id: ObjectId('65e1043b5265269a03078ad3'), @@ -512,7 +511,6 @@ to see the data created by running the code: | 1234 | Nostromo | +------+----------+ - // Document in the "passengers" collection [ { From 1da6c331ea1f3666a34c8e28d327da1a282fa1af Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 7 Mar 2024 16:40:13 -0500 Subject: [PATCH 24/27] PRR fixes --- docs/eloquent-models/relationships.txt | 58 ++++++++++++++------------ 1 file changed, 32 insertions(+), 26 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 48bfe453f..779656cbf 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -21,7 +21,7 @@ Overview -------- When you use a relational database, the Eloquent ORM stores models as rows -in tables that correspond to the model classes. When you use MongoDB, the +in tables that correspond to the model classes. When you use MongoDB, the {+odm-short+} stores models as documents in collections that correspond to the model classes. @@ -74,21 +74,23 @@ One to One Example ~~~~~~~~~~~~~~~~~~ The following example class shows how to define a ``HasOne`` one to one -relationship between a ``Planet`` and ``Orbit`` model. +relationship between a ``Planet`` and ``Orbit`` model by using the +``hasOne()`` method: .. literalinclude:: /includes/eloquent-models/relationships/one-to-one/Planet.php :language: php :dedent: -The following example class shows how to define the inverse relationship with -``Orbit`` by using the ``belongsTo()`` method: +The following example class shows how to define the inverse ``BelongsTo`` +relationship between ``Orbit`` and ``Planet`` by using the ``belongsTo()`` +method: .. literalinclude:: /includes/eloquent-models/relationships/one-to-one/Orbit.php :language: php :dedent: The following sample code shows how to instantiate a model for each class -and add the relationship between them. Click the :guilabel:`View Output` +and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` button to see the data created by running the code: .. io-code-block:: @@ -157,22 +159,23 @@ One to Many Example ~~~~~~~~~~~~~~~~~~~ The following example class shows how to define a ``HasMany`` one to many -relationship between a ``Planet`` parent model and ``Moon`` child model. +relationship between a ``Planet`` parent model and ``Moon`` child model by +using the ``hasMany()`` method: .. literalinclude:: /includes/eloquent-models/relationships/one-to-many/Planet.php :language: php :dedent: -To define the inverse of the relationship on ``Moon``, add the dynamic -property and call the ``belongsTo()`` method on it, as shown in the following -example class: +The following example class shows how to define the inverse ``BelongsTo`` +relationship between a ``Moon`` child model and the and the ``Planet`` parent +model by using the ``belongsTo()`` method: .. literalinclude:: /includes/eloquent-models/relationships/one-to-many/Moon.php :language: php :dedent: -The following sample code shows how ton instantiate a model for each class -and add the relationship between them. Click the :guilabel:`View Output` +The following sample code shows how to instantiate a model for each class +and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` button to see the data created by running the code: .. io-code-block:: @@ -228,8 +231,8 @@ Many to Many Relationship ------------------------- A many to many relationship consists of a relationship between two different -model types in which one type of model record can be related to multiple -records of the other type. +model types in which, for each type of model, an instance of the model can +be related to multiple instances of the other type. In {+odm-short+}, you can define a many to many relationship by adding the ``belongsToMany()`` method to both related classes. @@ -255,22 +258,24 @@ relationship between model classes. Many to Many Example ~~~~~~~~~~~~~~~~~~~~ -The following ``Planet`` class shows how to define a ``BelongsToMany`` many to -many relationship with and a ``SpaceExplorer`` model. +The following example class shows how to define a ``BelongsToMany`` many to +many relationship between a ``Planet`` and ``SpaceExporer`` model by using +the ``belongsToMany()`` method: .. literalinclude:: /includes/eloquent-models/relationships/many-to-many/Planet.php :language: php :dedent: -The ``SpaceExplorer`` model defines a ``BelongsToMany`` many to many -relationship with ``Planet`` as shown in the following example class: +The following example class shows how to define the inverse ``BelongsToMany`` +many to many relationship between a ``SpaceExplorer`` and ``Planet`` model by +using the ``belongsToMany()`` method: .. literalinclude:: /includes/eloquent-models/relationships/many-to-many/SpaceExplorer.php :language: php :dedent: The following sample code shows how to instantiate a model for each class -and add the relationship between them. Click the :guilabel:`View Output` +and add the relationship between them. Click the :guilabel:`VIEW OUTPUT` button to see the data created by running the code: .. io-code-block:: @@ -391,7 +396,7 @@ relationship between a ``SpaceShip`` and ``Cargo`` model: :dedent: The embedded model class omits the relationship definition as shown in the -following example class: +following ``Cargo`` model class: .. literalinclude:: /includes/eloquent-models/relationships/embeds/Cargo.php :language: php @@ -399,7 +404,7 @@ following example class: The following sample code shows how to create a ``SpaceShip`` model and embed multiple ``Cargo`` models and the MongoDB document created by running the -code. Click the :guilabel:`View Output` button to see the data created by +code. Click the :guilabel:`VIEW OUTPUT` button to see the data created by running the code: .. io-code-block:: @@ -462,16 +467,17 @@ relationship. Cross-Database Relationship Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following example class creates a ``hasMany`` relationship between a -``SpaceShip`` model stored in a relational database and a ``Passenger`` model -stored in a MongoDB database: +The following example class shows how to define a ``HasMany`` relationship +between a ``SpaceShip`` model stored in a relational database and a +``Passenger`` model stored in a MongoDB database: .. literalinclude:: /includes/eloquent-models/relationships/cross-db/SpaceShip.php :language: php :dedent: -The ``Passenger`` model defines a ``BelongsToMany`` relationship with -``SpaceShip`` as shown in the following example class: +The following example class shows how to define the inverse ``BelongsTo`` +relationship between a ``Passenger`` model and the and the ``Spaceship`` +model by using the ``belongsTo()`` method: .. literalinclude:: /includes/eloquent-models/relationships/cross-db/Passenger.php :language: php @@ -489,7 +495,7 @@ The ``Passenger`` model defines a ``BelongsToMany`` relationship with The following sample code shows how to create a ``SpaceShip`` model in a MySQL database and related ``Passenger`` models in a MongoDB database and -the data created by running the code. Click the :guilabel:`View Output` button +the data created by running the code. Click the :guilabel:`VIEW OUTPUT` button to see the data created by running the code: .. io-code-block:: From 945882b9efacd87bd4d16a2da3f32a69bd2b2a51 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 7 Mar 2024 17:05:17 -0500 Subject: [PATCH 25/27] PRR and grammar fixes --- docs/eloquent-models/relationships.txt | 27 +++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/eloquent-models/relationships.txt b/docs/eloquent-models/relationships.txt index 779656cbf..92625f076 100644 --- a/docs/eloquent-models/relationships.txt +++ b/docs/eloquent-models/relationships.txt @@ -32,7 +32,7 @@ related model by using the same syntax as you use to access a property on the model. The following sections describe the Laravel Eloquent and MongoDB-specific -relationships available in {+odm-short+} and shows examples of how to define +relationships available in {+odm-short+} and show examples of how to define and use them: - :ref:`One to one relationship `, @@ -141,9 +141,9 @@ the parent and one or more related child model records. When you add a one to many relationship method, Eloquent lets you access the model by using a dynamic property and stores the parent model's document ID -on each of the child model documents. +on each child model document. -In {+odm-short+}, you can define a one to many relationship by using the +In {+odm-short+}, you can define a one to many relationship by adding the ``hasMany()`` method on the parent class and, optionally, the ``belongsTo()`` method on the child class. @@ -240,7 +240,7 @@ In {+odm-short+}, you can define a many to many relationship by adding the When you define a many to many relationship in a relational database, Laravel creates a pivot table to track the relationships. When you use {+odm-short+}, it omits the pivot table creation and adds the related document IDs to a -document field, derived from the related model class name. +document field derived from the related model class name. .. tip:: @@ -259,7 +259,7 @@ Many to Many Example ~~~~~~~~~~~~~~~~~~~~ The following example class shows how to define a ``BelongsToMany`` many to -many relationship between a ``Planet`` and ``SpaceExporer`` model by using +many relationship between a ``Planet`` and ``SpaceExplorer`` model by using the ``belongsToMany()`` method: .. literalinclude:: /includes/eloquent-models/relationships/many-to-many/Planet.php @@ -365,8 +365,8 @@ to meet one or more of the following requirements: data - Reducing the number of reads required to fetch the data -In {+odm-short+}, you can define embedded documents by using one of the -following dynamic property methods: +In {+odm-short+}, you can define embedded documents by adding one of the +following methods: - ``embedsOne()`` to embed a single document - ``embedsMany()`` to embed multiple documents @@ -388,8 +388,9 @@ pattern. Embedded Document Example ~~~~~~~~~~~~~~~~~~~~~~~~~ -The following example class shows how to define an ``embedsMany`` one to many -relationship between a ``SpaceShip`` and ``Cargo`` model: +The following example class shows how to define an ``EmbedsMany`` one to many +relationship between a ``SpaceShip`` and ``Cargo`` model by using the +``embedsMany()`` method: .. literalinclude:: /includes/eloquent-models/relationships/embeds/SpaceShip.php :language: php @@ -446,7 +447,7 @@ Cross-Database Relationships ---------------------------- A cross-database relationship in {+odm-short+} is a relationship between models -stored in a SQL relational database and models stored in a MongoDB database. +stored in a relational database and models stored in a MongoDB database. When you add a cross-database relationship, Eloquent lets you access the related models by using a dynamic property. @@ -485,7 +486,7 @@ model by using the ``belongsTo()`` method: .. tip:: - Make sure that your primary key defined in your relational database table + Make sure that the primary key defined in your relational database table schema matches the one that your model uses. To learn more about Laravel primary keys and schema definitions, see the following pages in the Laravel documentation: @@ -494,8 +495,8 @@ model by using the ``belongsTo()`` method: - `Database: Migrations `__ The following sample code shows how to create a ``SpaceShip`` model in -a MySQL database and related ``Passenger`` models in a MongoDB database and -the data created by running the code. Click the :guilabel:`VIEW OUTPUT` button +a MySQL database and related ``Passenger`` models in a MongoDB database as well +as the data created by running the code. Click the :guilabel:`VIEW OUTPUT` button to see the data created by running the code: .. io-code-block:: From 22419acb3afbcfaa1e2175a675c3b45599e12061 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 15 Mar 2024 11:31:16 -0400 Subject: [PATCH 26/27] PRR fixes --- .../eloquent-models/relationships/RelationshipController.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/includes/eloquent-models/relationships/RelationshipController.php b/docs/includes/eloquent-models/relationships/RelationshipController.php index 0c015e329..fc10184d3 100644 --- a/docs/includes/eloquent-models/relationships/RelationshipController.php +++ b/docs/includes/eloquent-models/relationships/RelationshipController.php @@ -8,7 +8,7 @@ use App\Models\Planet; use Illuminate\Http\Request; -class RelationshipController extends Controller +class RelationshipController { private function oneToOne() { @@ -112,7 +112,7 @@ private function manyToManyDynamic() $planet = Planet::first(); $explorers = $planet->visitors; - $spaceExplorer = SpaceExplorer:first(); + $spaceExplorer = SpaceExplorer::first(); $explored = $spaceExplorer->planetsVisited; // end many-to-many dynamic property example } From ea5e8c1348ff3a031d1691be4c658ee0ba06d5d7 Mon Sep 17 00:00:00 2001 From: ccho-mongodb Date: Fri, 15 Mar 2024 15:31:49 +0000 Subject: [PATCH 27/27] apply phpcbf formatting --- src/Query/Builder.php | 5 ----- tests/Models/User.php | 2 +- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/src/Query/Builder.php b/src/Query/Builder.php index 98e6640df..27e788db8 100644 --- a/src/Query/Builder.php +++ b/src/Query/Builder.php @@ -1158,11 +1158,6 @@ protected function compileWheres(): array return $compiled; } - /** - * @param array $where - * - * @return array - */ protected function compileWhereBasic(array $where): array { $column = $where['column']; diff --git a/tests/Models/User.php b/tests/Models/User.php index f2d2cf7cc..98f76d931 100644 --- a/tests/Models/User.php +++ b/tests/Models/User.php @@ -130,7 +130,7 @@ protected function username(): Attribute { return Attribute::make( get: fn ($value) => $value, - set: fn ($value) => Str::slug($value) + set: fn ($value) => Str::slug($value), ); }