[Encryption] PHPORM-360 Document limitations of encryption with collection inheritance (#2790)

Author: GromNaN

docs/en/reference/attributes-reference.rst

@@ -356,6 +356,10 @@ Optional arguments:
   users only. The default values for these options are suitable for the majority
   of use cases, and should only be modified if your use case requires it.
 
+.. note::
+
+    Queryable encryption is only supported in MongoDB version 8.0 and later.
+
 Example:
 
 .. code-block:: php
@@ -373,9 +377,50 @@ Example:
         public string $name;
     }
 
+The ``#[Encrypt]`` attribute can be added to a class with `#[EmbeddedDocument]`_.
+This will encrypt the entire embedded document, in the field that contains it.
+Queryable encryption is not supported for embedded documents, so the ``queryType``
+argument is not applicable. Encrypted embedded documents are stored as a binary
+value in the parent document.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\ODM\MongoDB\Mapping\Annotations\Encrypt;
+
+    #[Encrypt]
+    #[EmbeddedDocument]
+    class CreditCard
+    {
+        #[Field]
+        public string $number;
+
+        #[Field]
+        public string $expiryDate;
+    }
+
+    #[Document]
+    class User
+    {
+        #[EmbedOne(targetDocument: CreditCard::class)]
+        public CreditCard $creditCard;
+    }
+
 For more details, refer to the MongoDB documentation on
 `Queryable Encryption <https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/encrypt-and-query/>`_.
 
+
+.. note::
+
+    The encrypted collection must be created with the `Schema Manager`_ before
+    before inserting documents.
+
+.. note::
+
+    Due to the way the encrypted fields map is generated, the queryable encryption
+    is not compatible with ``SINGLE_COLLECTION`` inheritance.
+
 #[Field]
 --------
 
@@ -1439,5 +1484,6 @@ root class specified in the view mapping.
 .. _DBRef: https://docs.mongodb.com/manual/reference/database-references/#dbrefs
 .. _geoNear command: https://docs.mongodb.com/manual/reference/command/geoNear/
 .. _MongoDB\BSON\ObjectId: https://www.php.net/class.mongodb-bson-objectid
+.. _Schema Manager: ../reference/migrating-schemas
 .. |FQCN| raw:: html
   <abbr title="Fully-Qualified Class Name">FQCN</abbr>

docs/en/reference/migrating-schemas.rst

@@ -15,6 +15,44 @@ problem!
     for the Google App Engine datastore. Additional information may be found in
     the `Objectify schema migration`_ documentation.
 
+Creating a collection
+--------------------
+
+Collections are automatically created by the MongoDB server upon first insertion.
+You must explicitly create the collections if you need specific options, such as
+validation rules. In particular, encrypted collections must be created explicitly.
+
+.. code-block:: php
+
+    <?php
+
+    // Assuming $dm is your DocumentManager instance
+    $schemaManager = $dm->getSchemaManager();
+
+To create the collections for all the document classes, you can use the
+`createCollections()` method on the ``DocumentManager``:
+
+.. code-block:: php
+
+    <?php
+
+    $schemaManager->createCollections();
+
+For a specific document class, you can use the `createDocumentCollection()`
+method with the class name as an argument:
+
+    <?php
+
+    $schemaManager->createDocumentCollection(Person::class);
+
+Once the collection is created, you can also set up indexes with ``ensureIndexes``,
+and search indexes with ``createSearchIndexes``:
+
+    <?php
+
+    $schemaManager->ensureIndexes();
+    $schemaManager->createSearchIndexes();
+
 Renaming a Field
 ----------------