doc: Add type to properties (#2652)

* Add type to properties
* Add phpdoc for Collection generics

docs/en/reference/aggregation-builder.rst

@@ -133,13 +133,13 @@ they can't be persisted to the database.
         class UserPurchases
         {
             #[ReferenceOne(targetDocument: User::class, name: '_id')]
-            private $user;
+            private User $user;
 
             #[Field(type: 'int')]
-            private $numPurchases;
+            private int $numPurchases;
 
             #[Field(type: 'float')]
-            private $amount;
+            private float $amount;
         }
 
     .. code-block:: xml

docs/en/reference/aggregation-stage-reference.rst

@@ -381,12 +381,13 @@ pipeline stages. Take the following relationship for example:
 
     class Orders
     {
+        /** @var Collection<Item> */
         #[ReferenceMany(
             targetDocument: Item::class,
             cascade: 'all',
             storeAs: 'id',
         )]
-        private $items;
+        private Collection $items;
     }
 
 .. code-block:: php
@@ -417,7 +418,7 @@ to be considered when looking up one-to-one relationships:
             cascade: 'all',
             storeAs: 'id',
         )]
-        private $items;
+        private Item $items;
     }
 
 .. code-block:: php

docs/en/reference/attributes-reference.rst

@@ -18,7 +18,7 @@ does not exist.
     {
         #[Field(type: 'string')]
         #[AlsoLoad('name')]
-        public $fullName;
+        public string $fullName;
     }
 
 The ``$fullName`` property will be loaded from ``fullName`` if it exists, but
@@ -217,6 +217,7 @@ Optional attributes:
 
     class User
     {
+        /** @var Collection<BookTag|SongTag> */
         #[EmbedMany(
             strategy:'set',
             discriminatorField:'type',
@@ -226,7 +227,7 @@ Optional attributes:
             ],
             defaultDiscriminatorValue: 'book',
         )]
-        private $tags = [];
+        private Collection $tags;
     }
 
 Depending on the embedded document's class, a value of ``user`` or ``author``
@@ -281,7 +282,7 @@ Optional attributes:
              ],
              defaultDiscriminatorValue: 'user',
         )]
-        private $creator;
+        private User|Author $creator;
     }
 
 Depending on the embedded document's class, a value of ``user`` or ``author``
@@ -304,7 +305,7 @@ relationship.
     class Money
     {
         #[Field(type: 'float')]
-        private $amount;
+        private float $amount;
 
         public function __construct(float $amount)
         {
@@ -317,7 +318,7 @@ relationship.
     class Wallet
     {
         #[EmbedOne(targetDocument: Money::class)]
-        private $money;
+        private Money $money;
 
         public function setMoney(Money $money): void
         {
@@ -374,13 +375,13 @@ Examples:
     class User
     {
         #[Field(type: 'string')]
-        protected $username;
+        protected string $username;
 
         #[Field(type: 'string', name: 'co')]
-        protected $country;
+        protected string $country;
 
         #[Field(type: 'float')]
-        protected $height;
+        protected float $height;
     }
 
 .. _file:
@@ -501,9 +502,16 @@ customize this via the :ref:`strategy <basic_mapping_identifiers>` attribute.
     class User
     {
         #[Id]
-        protected $id;
+        protected string $id;
     }
 
+.. note::
+
+   The property annotated with `#[Id]`_ cannot be ``readonly`` even if the
+   value is set only once and should never be updated. This is because the
+   property is set outside of the scope of the class, which is not allowed in
+   PHP for ``readonly`` properties.
+
 #[Index]
 --------
 
@@ -551,7 +559,7 @@ If you are creating a single-field index, you can simply specify an `#[Index]`_
     {
         #[Field(type: 'string')]
         #[UniqueIndex]
-        private $username;
+        private string $username;
     }
 
 .. note::
@@ -631,7 +639,7 @@ This is only compatible with the ``int`` type, and cannot be combined with `#[Id
     {
         #[Field(type: 'int')]
         #[Lock]
-        private $lock;
+        private int $lock;
     }
 
 #[MappedSuperclass]
@@ -979,19 +987,20 @@ Optional attributes:
 
     class User
     {
+        /** @var Collection<Item> */
         #[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',
         )]
-        private $cart;
+        private Collection $cart;
     }
 
 .. _attributes_reference_reference_one:
@@ -1061,7 +1070,7 @@ Optional attributes:
             ],
             defaultDiscriminatorValue: 'book'
         )]
-        private $cart;
+        private Item $cart;
     }
 
 #[SearchIndex]
@@ -1148,7 +1157,7 @@ Alias of `#[Index]`_, with the ``unique`` option set by default.
     {
         #[Field(type: 'string')]
         #[UniqueIndex]
-        private $email;
+        private string $email;
     }
 
 .. _attributes_reference_version:
@@ -1258,7 +1267,7 @@ combined with `#[Id]`_. Following ODM types can be used for versioning: ``int``,
     {
         #[Field(type: 'int')]
         #[Version]
-        private $version;
+        private int $version;
     }
 
 By default, Doctrine ODM updates :ref:`embed-many <embed_many>` and

docs/en/reference/basic-mapping.rst

@@ -247,7 +247,7 @@ Here is an example:
         class User
         {
             #[Id]
-            private $id;
+            private string $id;
         }
 
     .. code-block:: xml
@@ -284,7 +284,7 @@ Here is an example how to manually set a string identifier for your documents:
         class MyPersistentClass
         {
             #[Id(strategy: 'NONE', type: 'string')]
-            private $id;
+            private string $id;
 
             public function setId(string $id): void
             {
@@ -362,7 +362,7 @@ Then specify the ``class`` option for the ``CUSTOM`` strategy:
         class MyPersistentClass
         {
             #[Id(strategy: 'CUSTOM', type: 'string', options: ['class' => \Vendor\Specific\Generator::class])]
-            private $id;
+            private string $id;
 
             public function setId(string $id): void
             {
@@ -412,7 +412,7 @@ Example:
             // ...
 
             #[Field(type: 'string')]
-            private $username;
+            private string $username;
         }
 
     .. code-block:: xml
@@ -442,8 +442,11 @@ as follows:
 
         <?php
 
-        #[Field(name: 'db_name')]
-        private $name;
+        class User
+        {
+            #[Field(name: 'db_name')]
+            private string $name;
+        }
 
     .. code-block:: xml
 

docs/en/reference/best-practices.rst

@@ -56,19 +56,23 @@ Example:
     namespace MyProject\Model;
 
     use Doctrine\Common\Collections\ArrayCollection;
+    use Doctrine\Common\Collections\Collection;
 
     class User
     {
-
-        /** @var ArrayCollection  */
-        private $addresses;
-
-        /** @var ArrayCollection  */
-        private $articles;
+        private Collection $addresses;
+        private Collection $articles;
 
         public function __construct()
         {
             $this->addresses = new ArrayCollection();
             $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.

docs/en/reference/bidirectional-references.rst

@@ -15,16 +15,17 @@ and changes are tracked and persisted separately. Here is an example:
         // ...
 
         #[ReferenceOne(targetDocument: User::class)]
-        private $user;
+        private User $user;
     }
 
     #[Document]
     class User
     {
         // ...
 
+        /** @var Collection<BlogPost> */
         #[ReferenceMany(targetDocument: BlogPost::class)]
-        private $posts;
+        private Collection $posts;
     }
 
 When I persist some instances of the above classes the references would exist on both sides! The
@@ -57,16 +58,17 @@ One to Many
         // ...
 
         #[ReferenceOne(targetDocument: User::class, inversedBy: 'posts')]
-        private $user;
+        private User $user;
     }
 
     #[Document]
     class User
     {
         // ...
 
+        /** @var Collection<BlogPost> */
         #[ReferenceMany(targetDocument: BlogPost::class, mappedBy: 'user')]
-        private $posts;
+        private Collection $posts;
     }
 
 So now when we persist a ``User`` and multiple ``BlogPost`` instances for that ``User``:
@@ -136,7 +138,7 @@ Here is an example where we have a one to one relationship between ``Cart`` and
         // ...
 
         #[ReferenceOne(targetDocument: Customer::class, inversedBy: 'cart')]
-        public $customer;
+        public Customer $customer;
     }
 
     #[Document]
@@ -145,7 +147,7 @@ Here is an example where we have a one to one relationship between ``Cart`` and
         // ...
 
         #[ReferenceOne(targetDocument: Cart::class, mappedBy: 'customer')]
-        public $cart;
+        public Cart $cart;
     }
 
 The owning side is on ``Cart.customer`` and the ``Customer.cart`` referenced is loaded with a query
@@ -187,11 +189,13 @@ Self-Referencing Many to Many
     {
         // ...
 
+        /** @var Collection<User> */
         #[ReferenceMany(targetDocument: User::class, mappedBy: 'myFriends')]
-        public $friendsWithMe;
+        public Collection $friendsWithMe;
 
+        /** @var Collection<User> */
         #[ReferenceMany(targetDocument: User::class, inversedBy: 'friendsWithMe')]
-        public $myFriends;
+        public Collection $myFriends;
 
         public function __construct($name)
         {

docs/en/reference/capped-collections.rst

@@ -31,10 +31,10 @@ the ``#[Document]`` attribute:
         class Category
         {
             #[Id]
-            public $id;
+            public string $id;
 
             #[Field(type: 'string')]
-            public $name;
+            public string $name;
         }
 
     .. code-block:: xml

docs/en/reference/change-tracking-policies.rst

@@ -85,11 +85,12 @@ follows:
     {
         // ...
 
-        private $_listeners = [];
+        /** @var PropertyChangedListener[] */
+        private array $listeners = [];
 
         public function addPropertyChangedListener(PropertyChangedListener $listener): void
         {
-            $this->_listeners[] = $listener;
+            $this->listeners[] = $listener;
         }
     }