From 43a70e86b2a472be1cd19bf91d206af2bab2d300 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= <jerome@tamarelle.net>
Date: Mon, 1 Jul 2024 15:44:50 +0200
Subject: [PATCH] doc: Review mapping ORM and ODM cookbook (#2658)

* Review mapping ORM and ODM cookbook
* Add tests on mapping ORM and ODM
* ORM test requires pdo_sqlite
---
 .../mapping-classes-to-orm-and-odm.rst        | 85 +++++++++++--------
 .../MappingOrmAndOdm/BlogPost.php             | 28 ++++++
 .../BlogPostRepositoryInterface.php           | 10 +++
 .../MappingOrmAndOdm/MappingOrmAndOdmTest.php | 75 ++++++++++++++++
 .../OdmBlogPostRepository.php                 | 15 ++++
 .../OrmBlogPostRepository.php                 | 15 ++++
 6 files changed, 192 insertions(+), 36 deletions(-)
 create mode 100644 tests/Documentation/MappingOrmAndOdm/BlogPost.php
 create mode 100644 tests/Documentation/MappingOrmAndOdm/BlogPostRepositoryInterface.php
 create mode 100644 tests/Documentation/MappingOrmAndOdm/MappingOrmAndOdmTest.php
 create mode 100644 tests/Documentation/MappingOrmAndOdm/OdmBlogPostRepository.php
 create mode 100644 tests/Documentation/MappingOrmAndOdm/OrmBlogPostRepository.php

diff --git a/docs/en/cookbook/mapping-classes-to-orm-and-odm.rst b/docs/en/cookbook/mapping-classes-to-orm-and-odm.rst
index fbf540c73..4d6fd9088 100644
--- a/docs/en/cookbook/mapping-classes-to-orm-and-odm.rst
+++ b/docs/en/cookbook/mapping-classes-to-orm-and-odm.rst
@@ -1,9 +1,9 @@
 Mapping Classes to the ORM and ODM
 ==================================
 
-Because of the non-intrusive design of Doctrine, it is possible for you to have plain PHP classes
-that are mapped to both a relational database (with the Doctrine2 Object Relational Mapper) and
-MongoDB (with the Doctrine MongoDB Object Document Mapper), or any other persistence layer that
+Because of the non-intrusive design of Doctrine, it is possible to map PHP
+classes to both a relational database (with the Doctrine ORM) and
+MongoDB (with the Doctrine MongoDB ODM), or any other persistence layer that
 implements the Doctrine Persistence `persistence`_ interfaces.
 
 Test Subject
@@ -21,18 +21,16 @@ for multiple Doctrine persistence layers:
 
     class BlogPost
     {
-        private $id;
-        private $title;
-        private $body;
-
-        // ...
+        public int $id;
+        public string $title;
+        public string $body;
     }
 
 Mapping Information
 -------------------
 
-Now we just need to provide the mapping information for the Doctrine persistence layers so they know
-how to consume the objects and persist them to the database.
+Now we just need to provide the mapping information for the Doctrine persistence
+layers so they know how to consume the objects and persist them to the database.
 
 ORM
 ~~~
@@ -48,21 +46,21 @@ First define the mapping for the ORM:
         namespace Documents\Blog;
 
         use Documents\Blog\Repository\ORM\BlogPostRepository;
+        use Doctrine\ORM\Mapping as ORM;
 
-        #[Entity(repositoryClass: BlogPostRepository::class)]
+        #[ORM\Entity(repositoryClass: BlogPostRepository::class)]
         class BlogPost
         {
-            #[Id]
-            #[Column(type: 'int')]
-            private $id;
-
-            #[Column(type: 'string')]
-            private $title;
+            #[ORM\Id]
+            #[ORM\Column(type: 'integer')]
+            #[ORM\GeneratedValue(strategy: 'AUTO')]
+            public int $id;
 
-            #[Column(type: 'text')]
-            private $body;
+            #[ORM\Column(type: 'string')]
+            public string $title;
 
-            // ...
+            #[ORM\Column(type: 'text')]
+            public string $body;
         }
 
     .. code-block:: xml
@@ -80,14 +78,15 @@ First define the mapping for the ORM:
             </entity>
         </doctrine-mapping>
 
-Now you are able to persist the ``Documents\Blog\BlogPost`` with an instance of ``EntityManager``:
+Now you are able to persist the ``Documents\Blog\BlogPost`` with an instance of
+``EntityManager``:
 
 .. code-block:: php
 
     <?php
 
     $blogPost = new BlogPost();
-    $blogPost->setTitle('test');
+    $blogPost->title = 'Hello World!';
 
     $em->persist($blogPost);
     $em->flush();
@@ -98,7 +97,7 @@ You can find the blog post:
 
     <?php
 
-    $blogPost = $em->getRepository(BlogPost::class)->findOneBy(array('title' => 'test'));
+    $blogPost = $em->getRepository(BlogPost::class)->findOneBy(['title' => 'Hello World!']);
 
 MongoDB ODM
 ~~~~~~~~~~~
@@ -114,20 +113,19 @@ Now map the same class to the Doctrine MongoDB ODM:
         namespace Documents\Blog;
 
         use Documents\Blog\Repository\ODM\BlogPostRepository;
+        use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
 
-        #[Document(repositoryClass: BlogPostRepository::class)]
+        #[ODM\Document(repositoryClass: BlogPostRepository::class)]
         class BlogPost
         {
-            #[Id]
-            private $id;
+            #[ODM\Id(type: 'int', strategy: 'INCREMENT')]
+            public int $id;
 
-            #[Field(type: 'string')]
-            private $title;
+            #[ODM\Field]
+            public string $title;
 
-            #[Field(type: 'string')]
-            private $body;
-
-            // ...
+            #[ODM\Field]
+            public string $body;
         }
 
     .. code-block:: xml
@@ -145,14 +143,21 @@ Now map the same class to the Doctrine MongoDB ODM:
             </document>
         </doctrine-mongo-mapping>
 
-Now the same class is able to be persisted in the same way using an instance of ``DocumentManager``:
+.. note::
+
+    We use the ``INCREMENT`` strategy for the MongoDB ODM for compatibility with
+    the ORM mapping. But you can also use the default ``AUTO`` strategy
+    and store a generated MongoDB ObjectId as a string in the SQL database.
+
+Now the same class is able to be persisted in the same way using an instance of
+``DocumentManager``:
 
 .. code-block:: php
 
     <?php
 
     $blogPost = new BlogPost();
-    $blogPost->setTitle('test');
+    $blogPost->title = 'Hello World!';
 
     $dm->persist($blogPost);
     $dm->flush();
@@ -163,12 +168,13 @@ You can find the blog post:
 
     <?php
 
-    $blogPost = $dm->getRepository(BlogPost::class)->findOneBy(array('title' => 'test'));
+    $blogPost = $dm->getRepository(BlogPost::class)->findOneBy(['title' => 'Hello World!']);
 
 Repository Classes
 ------------------
 
-You can implement the same repository interface for the ORM and MongoDB ODM easily, e.g. by creating ``BlogPostRepositoryInterface``:
+You can implement the same repository interface for the ORM and MongoDB ODM
+easily, e.g. by creating ``BlogPostRepositoryInterface``:
 
 .. code-block:: php
 
@@ -227,4 +233,11 @@ PHP objects. The data is transparently injected to the objects for you automatic
 are not forced to extend some base class or shape your domain in any certain way for it to work
 with the Doctrine persistence layers.
 
+.. note::
+
+    If the same class is mapped to both the ORM and ODM, and you persist the
+    instance in both, you will have two separate instances in memory. This is
+    because the ORM and ODM are separate libraries and do not share the same
+    object manager.
+
 .. _persistence: https://github.com/doctrine/persistence
diff --git a/tests/Documentation/MappingOrmAndOdm/BlogPost.php b/tests/Documentation/MappingOrmAndOdm/BlogPost.php
new file mode 100644
index 000000000..67d00ecff
--- /dev/null
+++ b/tests/Documentation/MappingOrmAndOdm/BlogPost.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Documentation\MappingOrmAndOdm;
+
+use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity(repositoryClass: OrmBlogPostRepository::class)]
+#[ORM\Table(name: 'blog_posts')]
+#[ODM\Document(repositoryClass: OdmBlogPostRepository::class)]
+class BlogPost
+{
+    #[ORM\Id]
+    #[ORM\Column(type: 'integer')]
+    #[ORM\GeneratedValue(strategy: 'AUTO')]
+    #[ODM\Id(type: 'int', strategy: 'INCREMENT')]
+    public int $id;
+
+    #[ORM\Column(type: 'string')]
+    #[ODM\Field]
+    public string $title;
+
+    #[ORM\Column(type: 'text')]
+    #[ODM\Field]
+    public string $body;
+}
diff --git a/tests/Documentation/MappingOrmAndOdm/BlogPostRepositoryInterface.php b/tests/Documentation/MappingOrmAndOdm/BlogPostRepositoryInterface.php
new file mode 100644
index 000000000..ec656a502
--- /dev/null
+++ b/tests/Documentation/MappingOrmAndOdm/BlogPostRepositoryInterface.php
@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Documentation\MappingOrmAndOdm;
+
+interface BlogPostRepositoryInterface
+{
+    public function findPostById(int $id): ?BlogPost;
+}
diff --git a/tests/Documentation/MappingOrmAndOdm/MappingOrmAndOdmTest.php b/tests/Documentation/MappingOrmAndOdm/MappingOrmAndOdmTest.php
new file mode 100644
index 000000000..41f89df39
--- /dev/null
+++ b/tests/Documentation/MappingOrmAndOdm/MappingOrmAndOdmTest.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Documentation\MappingOrmAndOdm;
+
+use Doctrine\DBAL\DriverManager;
+use Doctrine\ODM\MongoDB\Tests\BaseTestCase;
+use Doctrine\ORM\EntityManager;
+use Doctrine\ORM\ORMSetup;
+use PHPUnit\Framework\Attributes\RequiresPhpExtension;
+
+#[RequiresPhpExtension('pdo_sqlite')]
+class MappingOrmAndOdmTest extends BaseTestCase
+{
+    public function testTest(): void
+    {
+        // Init ORM
+        $config     = ORMSetup::createAttributeMetadataConfiguration(
+            paths: [__DIR__],
+            isDevMode: true,
+        );
+        $connection = DriverManager::getConnection([
+            'driver' => 'pdo_sqlite',
+            'path' => ':memory:',
+        ], $config);
+        $connection->executeQuery('CREATE TABLE blog_posts (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT, body TEXT)');
+        $em = new EntityManager($connection, $config);
+
+        // Init ODM
+        $dm = $this->dm;
+
+        // Create and persist a BlogPost in both ORM and ODM
+        $blogPost        = new BlogPost();
+        $blogPost->title = 'Hello World!';
+
+        $em->persist($blogPost);
+        $em->flush();
+        $em->clear();
+
+        $dm->persist($blogPost);
+        $dm->flush();
+        $dm->clear();
+
+        // Load the BlogPost from both ORM and ODM
+        $ormBlogPost = $em->find(BlogPost::class, $blogPost->id);
+        $odmBlogPost = $dm->find(BlogPost::class, $blogPost->id);
+
+        $this->assertSame($blogPost->id, $ormBlogPost->id);
+        $this->assertSame($blogPost->id, $odmBlogPost->id);
+        $this->assertSame($blogPost->title, $ormBlogPost->title);
+        $this->assertSame($blogPost->title, $odmBlogPost->title);
+
+        // Different Object Managers are used, so the instances are different
+        $this->assertNotSame($odmBlogPost, $ormBlogPost);
+
+        $dm->clear();
+        $em->clear();
+
+        // Remove the BlogPost from both ORM and ODM using the repository
+        $ormBlogPostRepository = $em->getRepository(BlogPost::class);
+        $this->assertInstanceOf(OrmBlogPostRepository::class, $ormBlogPostRepository);
+        $ormBlogPost = $ormBlogPostRepository->findPostById($blogPost->id);
+
+        $odmBlogPostRepository = $dm->getRepository(BlogPost::class);
+        $this->assertInstanceOf(OdmBlogPostRepository::class, $odmBlogPostRepository);
+        $odmBlogPost = $odmBlogPostRepository->findPostById($blogPost->id);
+
+        $this->assertSame($blogPost->title, $ormBlogPost->title);
+        $this->assertSame($blogPost->title, $odmBlogPost->title);
+
+        // Different Object Managers are used, so the instances are different
+        $this->assertNotSame($odmBlogPost, $ormBlogPost);
+    }
+}
diff --git a/tests/Documentation/MappingOrmAndOdm/OdmBlogPostRepository.php b/tests/Documentation/MappingOrmAndOdm/OdmBlogPostRepository.php
new file mode 100644
index 000000000..5002d17eb
--- /dev/null
+++ b/tests/Documentation/MappingOrmAndOdm/OdmBlogPostRepository.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Documentation\MappingOrmAndOdm;
+
+use Doctrine\ODM\MongoDB\Repository\DocumentRepository;
+
+final class OdmBlogPostRepository extends DocumentRepository implements BlogPostRepositoryInterface
+{
+    public function findPostById(int $id): ?BlogPost
+    {
+        return $this->findOneBy(['id' => $id]);
+    }
+}
diff --git a/tests/Documentation/MappingOrmAndOdm/OrmBlogPostRepository.php b/tests/Documentation/MappingOrmAndOdm/OrmBlogPostRepository.php
new file mode 100644
index 000000000..58238b682
--- /dev/null
+++ b/tests/Documentation/MappingOrmAndOdm/OrmBlogPostRepository.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Documentation\MappingOrmAndOdm;
+
+use Doctrine\ORM\EntityRepository;
+
+final class OrmBlogPostRepository extends EntityRepository implements BlogPostRepositoryInterface
+{
+    public function findPostById(int $id): ?BlogPost
+    {
+        return $this->findOneBy(['id' => $id]);
+    }
+}