<commit_before>Working with Objects
====================

Understanding
-------------

In this chapter we will help you understand the ``DocumentManager``
and the ``UnitOfWork``. A Unit of Work is similar to an
object-level transaction. A new Unit of Work is implicitly started
when a DocumentManager is initially created or after
``DocumentManager#flush()`` has been invoked. A Unit of Work is
committed (and a new one started) by invoking
``DocumentManager#flush()``.

A Unit of Work can be manually closed by calling
``DocumentManager#close()``. Any changes to objects within this
Unit of Work that have not yet been persisted are lost.

The size of a Unit of Work
~~~~~~~~~~~~~~~~~~~~~~~~~~

The size of a Unit of Work mainly refers to the number of managed
documents at a particular point in time.

The cost of flush()
~~~~~~~~~~~~~~~~~~~

How costly a flush operation is in terms of performance mainly
depends on the size. You can get the size of your Unit of Work as
follows:

.. code-block:: php

    <?php

    $uowSize = $dm->getUnitOfWork()->size();

The size represents the number of managed documents in the Unit of
Work. This size affects the performance of flush() operations due
to change tracking and, of course, memory consumption, so you may
want to check it from time to time during development.

.. caution::

    Do not invoke ``flush`` after every change to a
    document or every single invocation of persist/remove/merge/...
    This is an anti-pattern and unnecessarily reduces the performance
    of your application. Instead, form units of work that operate on
    your objects and call ``flush`` when you are done. While serving a
    single HTTP request there should be usually no need for invoking
    ``flush`` more than 0-2 times.

Direct access to a Unit of Work
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can get direct access to the Unit of Work by calling
``DocumentManager#getUnitOfWork()``. This will return the
UnitOfWork instance the DocumentManager is currently using.

.. code-block:: php

    <?php

    $uow = $dm->getUnitOfWork();

.. note::

    Directly manipulating a UnitOfWork is not recommended.
    When working directly with the UnitOfWork API, respect methods
    marked as INTERNAL by not using them and carefully read the API
    documentation.

Persisting documents
--------------------

A document can be made persistent by passing it to the
``DocumentManager#persist($document)`` method. By applying the
persist operation on some document, that document becomes MANAGED,
which means that its persistence is from now on managed by an
DocumentManager. As a result the persistent state of such a
document will subsequently be properly synchronized with the
database when ``DocumentManager#flush()`` is invoked.

.. caution::

    Invoking the ``persist`` method on a document does NOT
    cause an immediate insert to be issued on the database. Doctrine
    applies a strategy called "transactional write-behind", which means
    that it will delay most operations until
    ``DocumentManager#flush()`` is invoked which will then issue all
    necessary queries to synchronize your objects with the database in
    the most efficient way.

Example:

.. code-block:: php

    <?php

    $user = new User();
    $user->setUsername('jwage');
    $user->setPassword('<PASSWORD>');
    $dm->persist($user);
    $dm->flush();

.. caution::

    If not provided upfront the \_id of a document is generated
    during ``persist``. You can not rely on a generated identifier to
    be available during ``prePersist`` event.

The semantics of the persist operation, applied on a document X,
are as follows:<commit_msg>Reword paragraph as per @jmikola's review<commit_after>Working with Objects
====================

Understanding
-------------

In this chapter we will help you understand the ``DocumentManager``
and the ``UnitOfWork``. A Unit of Work is similar to an
object-level transaction. A new Unit of Work is implicitly started
when a DocumentManager is initially created or after
``DocumentManager#flush()`` has been invoked. A Unit of Work is
committed (and a new one started) by invoking
``DocumentManager#flush()``.

A Unit of Work can be manually closed by calling
``DocumentManager#close()``. Any changes to objects within this
Unit of Work that have not yet been persisted are lost.

The size of a Unit of Work
~~~~~~~~~~~~~~~~~~~~~~~~~~

The size of a Unit of Work mainly refers to the number of managed
documents at a particular point in time.

The cost of flush()
~~~~~~~~~~~~~~~~~~~

How costly a flush operation is in terms of performance mainly
depends on the size. You can get the size of your Unit of Work as
follows:

.. code-block:: php

    <?php

    $uowSize = $dm->getUnitOfWork()->size();

The size represents the number of managed documents in the Unit of
Work. This size affects the performance of flush() operations due
to change tracking and, of course, memory consumption, so you may
want to check it from time to time during development.

.. caution::

    Do not invoke ``flush`` after every change to a
    document or every single invocation of persist/remove/merge/...
    This is an anti-pattern and unnecessarily reduces the performance
    of your application. Instead, form units of work that operate on
    your objects and call ``flush`` when you are done. While serving a
    single HTTP request there should be usually no need for invoking
    ``flush`` more than 0-2 times.

Direct access to a Unit of Work
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can get direct access to the Unit of Work by calling
``DocumentManager#getUnitOfWork()``. This will return the
UnitOfWork instance the DocumentManager is currently using.

.. code-block:: php

    <?php

    $uow = $dm->getUnitOfWork();

.. note::

    Directly manipulating a UnitOfWork is not recommended.
    When working directly with the UnitOfWork API, respect methods
    marked as INTERNAL by not using them and carefully read the API
    documentation.

Persisting documents
--------------------

A document can be made persistent by passing it to the
``DocumentManager#persist($document)`` method. By applying the
persist operation on some document, that document becomes MANAGED,
which means that its persistence is from now on managed by an
DocumentManager. As a result the persistent state of such a
document will subsequently be properly synchronized with the
database when ``DocumentManager#flush()`` is invoked.

.. caution::

    Invoking the ``persist`` method on a document does NOT
    cause an immediate insert to be issued on the database. Doctrine
    applies a strategy called "transactional write-behind", which means
    that it will delay most operations until
    ``DocumentManager#flush()`` is invoked which will then issue all
    necessary queries to synchronize your objects with the database in
    the most efficient way.

Example:

.. code-block:: php

    <?php

    $user = new User();
    $user->setUsername('jwage');
    $user->setPassword('<PASSWORD>');
    $dm->persist($user);
    $dm->flush();

.. caution::

    The document identifier is generated during ``persist`` if not previously
    specified. Users cannot rely on a document identifier being available during
    the ``prePersist`` event.

The semantics of the persist operation, applied on a document X,
are as follows:
{'fraction_non_alphanumeric': 0.09881745276607312, 'fraction_numerical': 0.0005436998776675275, 'mean_word_length': 3.82175622542595, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4657918', 'n_tokens_mistral': 1856, 'n_tokens_neox': 1775, 'n_words': 1002}