Replace "attribute" with "argument" to avoid confusion with PHP attributes (doctrine#2741)

Author: GromNaN

docs/en/cookbook/time-series-data.rst

@@ -75,7 +75,7 @@ change values in the document, in this example we'll assume that the data will
 not change.
 
 Now we can mark the document as a time series document. To do so, we use the
-``TimeSeries`` attribute, configuring appropriate values for the time and
+``#[TimeSeries]`` attribute, configuring appropriate values for the time and
 metadata field, which in our case stores the ID of the sensor reporting the
 measurement:
 

docs/en/reference/attributes-reference.rst

@@ -108,7 +108,7 @@ during hydration to select the instantiation class.
 .. note::
 
     For backwards compatibility, the discriminator field may also be specified
-    via either the ``name`` or ``fieldName`` attribute.
+    via either the ``name`` or ``fieldName`` argument.
 
 #[DiscriminatorMap]
 -------------------
@@ -141,7 +141,7 @@ and it does not contain the class name of the persisted document, a
 Required attribute to mark a PHP class as a document, whose persistence will be
 managed by ODM.
 
-Optional attributes:
+Optional arguments:
 
 -
    ``db`` - By default, the document manager will use the MongoDB database
@@ -185,7 +185,7 @@ Optional attributes:
 This attribute is similar to `#[EmbedOne]`_, but instead of embedding one
 document, it embeds a collection of documents.
 
-Optional attributes:
+Optional arguments:
 
 -
     ``targetDocument`` - A |FQCN| of the target document.
@@ -251,7 +251,7 @@ following excerpt from the MongoDB documentation:
     are eliminated. So in general, the question to ask is, "why would I not want
     to embed this object?"
 
-Optional attributes:
+Optional arguments:
 
 -
     ``targetDocument`` - A |FQCN| of the target document. When typed properties
@@ -343,7 +343,7 @@ Marks an annotated instance variable for persistence. Values for this field will
 be saved to and loaded from the document store as part of the document class'
 lifecycle.
 
-Optional attributes:
+Optional arguments:
 
 -
    ``type`` - Name of the ODM type, which will determine the value's
@@ -392,7 +392,7 @@ Examples:
 This marks the document as a GridFS file. GridFS allow storing larger amounts of
 data than regular documents.
 
-Optional attributes:
+Optional arguments:
 
 -
    ``db`` - By default, the document manager will use the MongoDB database
@@ -445,7 +445,7 @@ This maps the ``metadata`` property of a GridFS file to a property. Metadata can
 be used to store additional properties in a file. The metadata document must be
 an embedded document mapped using `#[EmbeddedDocument]`_.
 
-Optional attributes:
+Optional arguments:
 
 -
     ``targetDocument`` - A |FQCN| of the target document.
@@ -520,7 +520,7 @@ collection (or embedding document's collection in the case of
 `#[EmbeddedDocument]`_). It may also be used at the property-level to define
 single-field indexes.
 
-Optional attributes:
+Optional arguments:
 
 -
     ``keys`` - Mapping of indexed fields to their ordering or index type. ODM
@@ -925,7 +925,7 @@ that will be applied when querying for the annotated document.
 Defines that the annotated instance variable holds a collection of referenced
 documents.
 
-Optional attributes:
+Optional arguments:
 
 -
     ``targetDocument`` - A |FQCN| of the target document. A ``targetDocument``
@@ -1010,7 +1010,7 @@ Optional attributes:
 
 Defines an instance variable holds a related document instance.
 
-Optional attributes:
+Optional arguments:
 
 -
     ``targetDocument`` - A |FQCN| of the target document. A ``targetDocument``
@@ -1079,12 +1079,12 @@ Optional attributes:
 This attribute is used to specify :ref:`search indexes <search_indexes>` for
 `MongoDB Atlas Search <https://www.mongodb.com/docs/atlas/atlas-search/>`__.
 
-The attributes correspond to arguments for
+The arguments correspond to arguments for
 `MongoDB\Collection::createSearchIndex() <https://www.mongodb.com/docs/php-library/current/reference/method/MongoDBCollection-createSearchIndex/>`__.
-Excluding ``name``, attributes are used to create the
+Excluding ``name``, arguments are used to create the
 `search index definition <https://www.mongodb.com/docs/manual/reference/command/createSearchIndexes/#search-index-definition-syntax>`__.
 
-Optional attributes:
+Optional arguments:
 
 -
     ``name`` - Name of the search index to create, which must be unique to the
@@ -1353,7 +1353,7 @@ Required attributes:
    ``repositoryClass`` - a repository class is required. This repository must
    implement the ``MongoDB\ODM\MongoDB\Repository\ViewRepository`` interface.
 
-Optional attributes:
+Optional arguments:
 
 -
    ``db`` - By default, the document manager will use the MongoDB database

docs/en/reference/basic-mapping.rst

@@ -34,8 +34,8 @@ annotations by offering a standardized approach to metadata, eliminating
 the need for the separate parsing library required by annotations.
 
 In this documentation we follow the `PER Coding Style <https://www.php-fig.org/per/coding-style/#12-attributes>`_
-for attributes. We use named arguments for attributes as they argument names
-or attribute classes constructors are covered by Doctrine Backward-Compatibility promise.
+for attributes. We use named arguments for attributes as the names of their
+constructor arguments are covered by Doctrine Backward-Compatibility promise.
 
 .. note::
 
@@ -109,8 +109,8 @@ option as follows:
 Now instances of ``Documents\User`` will be persisted into a
 collection named ``users`` in the database ``my_db``.
 
-If you want to omit the db attribute you can configure the default db
-to use with the ``setDefaultDB`` method:
+If you want to omit the ``db`` argument you can configure the default database
+to use with the ``setDefaultDB()`` method:
 
 .. code-block:: php
 
@@ -195,7 +195,7 @@ _________________
     Doctrine will skip type autoconfiguration if settings are provided explicitly.
 
 Since version 2.4 Doctrine can determine usable defaults from property types
-on document classes. Doctrine will map PHP types to ``type`` attribute as
+on document classes. Doctrine will map PHP types to ``type`` arguments as
 follows:
 
 - ``DateTime``: ``date``
@@ -392,12 +392,9 @@ Then specify the ``class`` option for the ``CUSTOM`` strategy:
 Fields
 ~~~~~~
 
-To mark a property for document persistence the ``#[Field]`` docblock
-attribute can be used. This attribute usually requires at least 1
-attribute to be set, the ``type``. The ``type`` attribute specifies
-the Doctrine Mapping Type to use for the field. If the type is not
-specified, 'string' is used as the default mapping type since it is
-the most flexible.
+To mark a property to be persisted in the document, add the ``#[Field]``
+attribute. The name and the type of the field are inferred from the property
+name and type.
 
 Example:
 
@@ -417,7 +414,7 @@ Example:
         {
             // ...
 
-            #[Field(type: 'string')]
+            #[Field]
             public string $username;
         }
 
@@ -436,11 +433,9 @@ Example:
 
 In that example we mapped the property ``id`` to the field ``id``
 using the mapping type ``id`` and the property ``name`` is mapped
-to the field ``name`` with the default mapping type ``string``. As
-you can see, by default the mongo field names are assumed to be the
-same as the property names. To specify a different name for the
-field, you can use the ``name`` attribute of the Field attribute
-as follows:
+to the field ``name`` with the default mapping type ``string``.
+To specify a different name for the field, you can use the ``name`` argument
+of the Field attribute as follows:
 
 .. configuration-block::
 
@@ -458,6 +453,46 @@ as follows:
 
         <field field-name="name" name="db_name" />
 
+Date Fields
+~~~~~~~~~~~
+
+MongoDB has a specific database type to store date and time values. You should never
+use a string to store a date. To define a date field, use the property types
+``DateTime`` or ``DateTimeImmutable`` so that Doctrine maps it to a BSON date.
+The ``date`` and ``date_immutable`` mapping types can be used explicitly;
+they are required only if the property type is ``DateTimeInterface`` or not set.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+
+        class User
+        {
+            #[Field]
+            public \DateTimeImmutable $immutableDateTime;
+
+            #[Field]
+            public \DateTime $mutableDateTime;
+
+            #[Field(type: 'date_immutable')]
+            public \DateTimeInterface $datetime;
+        }
+
+    .. code-block:: xml
+
+        <field field-name="immutableDateTime" type="date_immutable" />
+        <field field-name="mutableDateTime" name="date" />
+        <field field-name="datetime" name="date_immutable" />
+
+
+.. note::
+
+    Prefer using ``DateTimeImmutable`` over ``DateTime`` to avoid issues with
+    mutable objects. If you need to modify a date, create a new instance
+    and assign it to the property.
+
 Multiple Document Types in a Collection
 ---------------------------------------
 

docs/en/reference/search-indexes.rst

@@ -30,7 +30,7 @@ ODM supports the following search index options:
     ``dynamic`` - Enables or disables dynamic field mapping for this index.
     If ``true``, the index will include all fields with
     `supported data types <https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/#std-label-bson-data-chart>`__.
-    If ``false``, the ``fields`` attribute must be specified. Defaults to ``false``.
+    If ``false``, the ``fields`` argument must be specified. Defaults to ``false``.
 -
     ``fields`` - Associative array of `field mappings <https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/>`__
     that specify the fields to index (keys). Required only if dynamic mapping is disabled.
@@ -41,7 +41,7 @@ ODM supports the following search index options:
 -
     ``searchAnalyzer`` - Specifies the `analyzer <https://www.mongodb.com/docs/atlas/atlas-search/analyzers/>`__
     to apply to query text before the text is searched. Defaults to the
-    ``analyzer`` attribute, or the `standard analyzer <https://www.mongodb.com/docs/atlas/atlas-search/analyzers/standard/>`__.
+    ``analyzer`` argument, or the `standard analyzer <https://www.mongodb.com/docs/atlas/atlas-search/analyzers/standard/>`__.
     if both are unspecified.
 -
     ``analyzers`` - Array of `custom analyzers <https://www.mongodb.com/docs/atlas/atlas-search/analyzers/custom/>`__

docs/en/reference/storing-files-with-gridfs.rst

@@ -120,7 +120,7 @@ look like this:
     </doctrine-mongo-mapping>
 
 With XML mappings, the fields are automatically mapped to camel-cased properties.
-To change property names, simply override the ``fieldName`` attribute for each
+To change property names, simply override the ``fieldName`` argument for each
 field. You cannot override any other options for GridFS fields.
 
 The ``ImageMetadata`` class must be an embedded document: