WIP

Author: Chris Cho

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 <laravel-eloquent-relationship-one-to-one>`,
+  created by using the ``hasOne()`` method and its inverse, ``belongsTo()``
+- :ref:`One to many relationship <laravel-eloquent-relationship-one-to-many>`,
+  created by using the ``hasMany()`` and its inverse, ``belongsTo()``
+- :ref:`Many to many relationship <laravel-eloquent-relationship-many-to-many>`,
+  created by using the ``belongsToMany()`` method
+- :ref:`Embedded document pattern <laravel-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
+-------------------------
+
 
 
 

docs/includes/eloquent-models/relationships/OrbitOneToOne.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Models;
+
+use MongoDB\Laravel\Eloquent\Model;
+use MongoDB\Laravel\Relations\BelongsTo;
+
+class Orbit extends Model
+{
+  protected $connection = 'mongodb';
+
+  public function planet(): BelongsTo
+  {
+      return $this->belongsTo(Planet::class);
+  }
+
+}

docs/includes/eloquent-models/relationships/PlanetOneToOne.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Models;
+
+use MongoDB\Laravel\Eloquent\Model;
+use MongoDB\Laravel\Relations\HasOne;
+
+class Planet extends Model
+{
+  protected $connection = 'mongodb';
+
+  public function orbit(): HasOne
+  {
+      return $this->hasOne(Orbit::class);
+  }
+
+}

docs/includes/eloquent-models/relationships/RelationshipController.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\Planet;
+use App\Models\Orbit;
+use Illuminate\Http\Request;
+
+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)
+    {
+
+        // begin one-to-one save
+        $planet = new Planet();
+        $planet->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)
+    {
+        //
+    }
+}