Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Mar 4, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/en/cookbook/time-series-data.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
28 changes: 14 additions & 14 deletions docs/en/reference/attributes-reference.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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]
-------------------
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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``
Expand Down Expand Up @@ -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``
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
69 changes: 52 additions & 17 deletions docs/en/reference/basic-mapping.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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``
Expand Down Expand Up @@ -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:

Expand All @@ -417,7 +414,7 @@ Example:
{
// ...

#[Field(type: 'string')]
#[Field]
public string $username;
}

Expand All @@ -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::

Expand All @@ -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
---------------------------------------

Expand Down
4 changes: 2 additions & 2 deletions docs/en/reference/search-indexes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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/>`__
Expand Down
2 changes: 1 addition & 1 deletion docs/en/reference/storing-files-with-gridfs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading