Add documentation page for data fixtures (#974)

Author: GromNaN

docs/console.rst

@@ -1,7 +1,7 @@
 Console Commands
 ================
 
-The Doctrine2 ODM integration offers various console commands under the
+The Doctrine MongoDB ODM integration offers various console commands under the
 ``doctrine:mongodb`` namespace. To view the command list you can run the console
 without any arguments:
 
@@ -21,7 +21,7 @@ For example, to get details about the ``doctrine:mongodb:query`` task, run:
 .. note::
 
    To be able to load data fixtures into MongoDB, you will need to have the
-   ``DoctrineFixturesBundle`` bundle installed. To learn how to do it, read
-   the "`DoctrineFixturesBundle`_" entry of the documentation.
+   ``doctrine/data-fixtures`` package installed. To learn how to do it, read
+   the `Doctrine Data Fixtures`_.
 
-.. _`DoctrineFixturesBundle`: https://symfony.com/doc/master/bundles/DoctrineFixturesBundle/index.html
+.. _`Doctrine Data Fixtures`: data_fixtures

docs/data_fixtures.rst

@@ -0,0 +1,192 @@
+Data Fixtures
+=============
+
+Data fixtures are a way to load sample data into your MongoDB database.
+This is useful for testing, development, and seeding your database with initial data.
+
+Installation
+------------
+
+First, install the `doctrine/data-fixtures`_ package:
+
+.. code-block:: bash
+
+    composer require --dev doctrine/data-fixtures
+
+Creating Fixtures
+-----------------
+
+To create a fixture, create a class that implements ``ODMFixtureInterface`` or extends the
+``Fixture`` base class. The best practice is to extend ``Doctrine\Bundle\MongoDBBundle\Fixture\Fixture``,
+as it provides convenient access to the object manager and reference functionality:
+
+.. code-block:: php
+
+    // src/DataFixtures/ProductFixtures.php
+    namespace App\DataFixtures;
+
+    use App\Document\Product;
+    use Doctrine\Bundle\MongoDBBundle\Fixture\Fixture;
+    use Doctrine\Persistence\ObjectManager;
+
+    class ProductFixtures extends Fixture
+    {
+        public function load(ObjectManager $manager): void
+        {
+            $product = new Product();
+            $product->setName('Example Product');
+            $product->setPrice(19.99);
+
+            $manager->persist($product);
+            $manager->flush();
+        }
+    }
+
+If you prefer not to extend the base ``Fixture`` class, you can implement the ``ODMFixtureInterface``
+directly:
+
+.. code-block:: php
+
+    // src/DataFixtures/ProductFixtures.php
+    namespace App\DataFixtures;
+
+    use App\Document\Product;
+    use Doctrine\Bundle\MongoDBBundle\Fixture\ODMFixtureInterface;
+    use Doctrine\Persistence\ObjectManager;
+
+    class ProductFixtures implements ODMFixtureInterface
+    {
+        public function load(ObjectManager $manager): void
+        {
+            $product = new Product();
+            $product->setName('Example Product');
+            $product->setPrice(19.99);
+
+            $manager->persist($product);
+            $manager->flush();
+        }
+    }
+
+Registering Fixtures
+--------------------
+
+Fixtures are automatically discovered and registered as services if they are
+in an autoconfigured service namespace (e.g. ``App\DataFixtures``). If your fixtures are located
+elsewhere, or if you have disabled autoconfiguration, you need to manually tag them
+with the ``doctrine.fixture.odm.mongodb`` tag:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\DataFixtures\ProductFixtures:
+                tags:
+                    - { name: 'doctrine.fixture.odm.mongodb' }
+
+
+Loading Fixtures
+----------------
+
+You can load fixtures using the command line:
+
+.. code-block:: bash
+
+    php bin/console doctrine:mongodb:fixtures:load
+
+This command will load all registered fixtures. You can also append data instead of truncating:
+
+.. code-block:: bash
+
+    # Append fixtures without truncating the database
+    php bin/console doctrine:mongodb:fixtures:load --append
+
+Fixture Dependencies
+--------------------
+
+Sometimes you need to load fixtures in a specific order because one fixture depends on data
+created by another fixture. You can implement the ``DependentFixtureInterface`` to specify
+which fixtures must be loaded first:
+
+.. code-block:: php
+
+    // src/DataFixtures/CategoryFixtures.php
+    namespace App\DataFixtures;
+
+    use App\Document\Category;
+    use Doctrine\Bundle\MongoDBBundle\Fixture\Fixture;
+    use Doctrine\Persistence\ObjectManager;
+
+    class CategoryFixtures extends Fixture
+    {
+        public function load(ObjectManager $manager): void
+        {
+            $category = new Category();
+            $category->setName('Electronics');
+
+            $manager->persist($category);
+            $manager->flush();
+
+            // Store a reference for other fixtures to use
+            $this->addReference('category-electronics', $category);
+        }
+    }
+
+.. code-block:: php
+
+    // src/DataFixtures/ProductFixtures.php
+    namespace App\DataFixtures;
+
+    use App\Document\Product;
+    use Doctrine\Bundle\MongoDBBundle\Fixture\Fixture;
+    use Doctrine\Common\DataFixtures\DependentFixtureInterface;
+    use Doctrine\Persistence\ObjectManager;
+
+    class ProductFixtures extends Fixture implements DependentFixtureInterface
+    {
+        public function load(ObjectManager $manager): void
+        {
+            $product = new Product();
+            $product->setName('Laptop');
+            $product->setPrice(999.99);
+            $product->setCategory($this->getReference('category-electronics'));
+
+            $manager->persist($product);
+            $manager->flush();
+        }
+
+        public function getDependencies(): array
+        {
+            return [CategoryFixtures::class];
+        }
+    }
+
+Using References
+----------------
+
+The ``Fixture`` base class provides methods to store and retrieve references to documents,
+which is useful when you need to reference one fixture from another:
+
+.. code-block:: php
+
+    // Store a reference
+    $this->addReference('my-product', $product);
+
+    // Retrieve a reference
+    $product = $this->getReference('my-product');
+
+    // Check if a reference exists
+    if ($this->hasReference('my-product')) {
+        $product = $this->getReference('my-product');
+    }
+
+More Information
+----------------
+
+For more details about data fixtures and advanced usage patterns, see the official
+`Doctrine Data Fixtures documentation`_.
+
+.. _`doctrine/data-fixtures`: https://packagist.org/packages/doctrine/data-fixtures
+.. _`Doctrine Data Fixtures documentation`: https://www.doctrine-project.org/projects/doctrine-data-fixtures/en/current/how-to/loading-fixtures.html
+

docs/index.rst

@@ -1,8 +1,8 @@
 DoctrineMongoDBBundle
 =====================
 
-The `MongoDB`_ Object Document Mapper (ODM) is much like the Doctrine2 ORM
-in its philosophy and how it works. In other words, like the `Doctrine2 ORM`_,
+The `MongoDB`_ Object Document Mapper (ODM) is much like the Doctrine ORM
+in its philosophy and how it works. In other words, like the `Doctrine ORM`_,
 with the Doctrine ODM, you deal only with plain PHP objects, which are then
 persisted transparently to and from MongoDB.
 
@@ -15,7 +15,7 @@ helping you to configure and use it in your application.
 
 .. note::
 
-    This documentation will feel a lot like the `Doctrine2 ORM chapter`_,
+    This documentation will feel a lot like the `Doctrine ORM chapter`_,
     which talks about how the Doctrine ORM can be used to persist data to
     relational databases (e.g. MySQL). This is on purpose - whether you persist
     to a relational database via the ORM or to MongoDB via the ODM, the philosophies
@@ -27,6 +27,7 @@ helping you to configure and use it in your application.
    config
    first_steps
    form_validation
+   data_fixtures
    security_bundle
    messenger
    events
@@ -45,8 +46,8 @@ For more information about them, see `available Doctrine extensions`_
 and use the `StofDoctrineExtensionsBundle`_ to integrate them in your application.
 
 .. _`MongoDB`: https://www.mongodb.com
-.. _`Doctrine2 ORM`: https://symfony.com/doc/current/book/doctrine.html
+.. _`Doctrine ORM`: https://symfony.com/doc/current/book/doctrine.html
 .. _`documentation`: https://www.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/
-.. _`Doctrine2 ORM chapter`: https://symfony.com/doc/current/book/doctrine.html
+.. _`Doctrine ORM chapter`: https://symfony.com/doc/current/book/doctrine.html
 .. _`available Doctrine extensions`: https://github.com/Atlantic18/DoctrineExtensions
 .. _`StofDoctrineExtensionsBundle`: https://symfony.com/doc/current/bundles/StofDoctrineExtensionsBundle/index.html