From 688a9d1b80c14dbace03efa78508474479ea9951 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 24 Jun 2024 10:05:11 +0200 Subject: [PATCH] Add phpdoc for Collection generics --- .../reference/aggregation-stage-reference.rst | 2 ++ docs/en/reference/attributes-reference.rst | 7 ++++--- docs/en/reference/best-practices.rst | 7 +++++++ docs/en/reference/embedded-mapping.rst | 5 ++++- docs/en/reference/indexes.rst | 1 + docs/en/reference/priming-references.rst | 2 ++ docs/en/reference/reference-mapping.rst | 20 ++++++++++++++----- docs/en/reference/trees.rst | 5 +++++ 8 files changed, 40 insertions(+), 9 deletions(-) diff --git a/docs/en/reference/aggregation-stage-reference.rst b/docs/en/reference/aggregation-stage-reference.rst index cb507ea58..adcdbbbc6 100644 --- a/docs/en/reference/aggregation-stage-reference.rst +++ b/docs/en/reference/aggregation-stage-reference.rst @@ -381,6 +381,7 @@ pipeline stages. Take the following relationship for example: class Orders { + /** @var Collection */ #[ReferenceMany( targetDocument: Item::class, cascade: 'all', @@ -412,6 +413,7 @@ to be considered when looking up one-to-one relationships: class Orders { + /** @var Collection */ #[ReferenceOne( targetDocument: Item::class, cascade: 'all', diff --git a/docs/en/reference/attributes-reference.rst b/docs/en/reference/attributes-reference.rst index c630537db..d9ce78fa7 100644 --- a/docs/en/reference/attributes-reference.rst +++ b/docs/en/reference/attributes-reference.rst @@ -217,6 +217,7 @@ Optional attributes: class User { + /** @var Collection */ #[EmbedMany( strategy:'set', discriminatorField:'type', @@ -989,13 +990,13 @@ Optional attributes: /** @var Collection */ #[ReferenceMany( strategy: 'set', - targetDocument: Documents\Item::class, + targetDocument: Item::class, cascade: 'all', sort: ['sort_field' => 'asc'], discriminatorField: 'type', discriminatorMap: [ - 'book' => Documents\BookItem::class, - 'song' => Documents\SongItem::class, + 'book' => BookItem::class, + 'song' => SongItem::class, ], defaultDiscriminatorValue: 'book', )] diff --git a/docs/en/reference/best-practices.rst b/docs/en/reference/best-practices.rst index 9d086bbdb..f4b257bdd 100644 --- a/docs/en/reference/best-practices.rst +++ b/docs/en/reference/best-practices.rst @@ -69,3 +69,10 @@ Example: $this->articles = new ArrayCollection(); } } + +.. note:: + + The properties' type hints must be ``Collection``, and cannot be + ``ArrayCollection``. When the ``User`` object is retrieved from the database, + the properties ``$addresses`` and ``$articles`` are instances of + ``Doctrine\ODM\MongoDB\PersistentCollection`` to track changes. diff --git a/docs/en/reference/embedded-mapping.rst b/docs/en/reference/embedded-mapping.rst index 3cf9ce96d..2aa9e1694 100644 --- a/docs/en/reference/embedded-mapping.rst +++ b/docs/en/reference/embedded-mapping.rst @@ -73,7 +73,7 @@ Embed many documents: { // ... - /** @var Collection + /** @var Collection */ #[EmbedMany(targetDocument: Phonenumber::class)] private Collection $phoneNumbers; @@ -282,6 +282,8 @@ You can achieve this behavior by using the `storeEmptyArray` option for embedded class User { // ... + + /** @var Collection */ #[EmbedMany(targetDocument: PhoneNumber::class, storeEmptyArray: true)] private Collection $phoneNumbers; // ... @@ -299,5 +301,6 @@ You can achieve this behavior by using the `storeEmptyArray` option for embedded + Now, when the `$phoneNumbers` collection is empty, an empty array will be stored in the database for the `User` document's embedded `phoneNumbers` collection, even if there are no actual embedded documents in the collection. diff --git a/docs/en/reference/indexes.rst b/docs/en/reference/indexes.rst index 3b74ebc19..c28bd1898 100644 --- a/docs/en/reference/indexes.rst +++ b/docs/en/reference/indexes.rst @@ -244,6 +244,7 @@ Now if we had a ``BlogPost`` document with the ``Comment`` document embedded man #[Index] private string $slug; + /** @var Collection */ #[EmbedMany(targetDocument: Comment::class)] private Collection $comments; } diff --git a/docs/en/reference/priming-references.rst b/docs/en/reference/priming-references.rst index f37f3f347..dbe4dbfe3 100644 --- a/docs/en/reference/priming-references.rst +++ b/docs/en/reference/priming-references.rst @@ -18,6 +18,7 @@ Consider the following abbreviated model: #[Document] class User { + /** @var Collection */ #[ReferenceMany(targetDocument: Account::class)] private Collection $accounts; } @@ -111,6 +112,7 @@ specifying them in the mapping: #[Document] class User { + /** @var Collection */ #[ReferenceMany(targetDocument: Account::class, prime: ['user'])] private Collection $accounts; } diff --git a/docs/en/reference/reference-mapping.rst b/docs/en/reference/reference-mapping.rst index 5cbc6299b..efdb5a576 100644 --- a/docs/en/reference/reference-mapping.rst +++ b/docs/en/reference/reference-mapping.rst @@ -200,6 +200,7 @@ in each `DBRef`_ object: { // .. + /** @var Collection */ #[ReferenceMany( discriminatorMap: [ 'album' => Album::class, @@ -277,8 +278,11 @@ Example: */ #[ReferenceMany(targetDocument: Account::class, storeEmptyArray: true)] - private Collection $accounts = []; + private Collection $accounts; + // ... } .. code-block:: xml diff --git a/docs/en/reference/trees.rst b/docs/en/reference/trees.rst index 6ad1fea8b..2b5c1b302 100644 --- a/docs/en/reference/trees.rst +++ b/docs/en/reference/trees.rst @@ -23,6 +23,7 @@ Full Tree in Single Document #[Field(type: 'string')] private string $body; + /** @var Collection */ #[EmbedMany(targetDocument: Comment::class)] private Collection $comments; @@ -38,6 +39,7 @@ Full Tree in Single Document #[Field(type: 'string')] private string $text; + /** @var Collection */ #[EmbedMany(targetDocument: Comment::class)] private Collection $replies; @@ -113,6 +115,7 @@ Child Reference #[Field(type: 'string')] private string $name; + /** @var Collection */ #[ReferenceMany(targetDocument: Category::class)] #[Index] private Collection $children; @@ -169,10 +172,12 @@ Array of Ancestors #[Id] private string $id; + /** @var Collection */ #[ReferenceMany(targetDocument: Category::class)] #[Index] private Collection $ancestors; + /** @var Collection */ #[ReferenceOne(targetDocument: Category::class)] #[Index] private ?Category $parent = null;