upgrade

vendor/doctrine/orm/docs/en/reference/advanced-configuration.rst

@@ -0,0 +1,470 @@
+Advanced Configuration
+======================
+
+The configuration of the EntityManager requires a
+``Doctrine\ORM\Configuration`` instance as well as some database
+connection parameters. This example shows all the potential
+steps of configuration.
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\EntityManager,
+        Doctrine\ORM\Configuration;
+    
+    // ...
+    
+    if ($applicationMode == "development") {
+        $cache = new \Doctrine\Common\Cache\ArrayCache;
+    } else {
+        $cache = new \Doctrine\Common\Cache\ApcCache;
+    }
+    
+    $config = new Configuration;
+    $config->setMetadataCacheImpl($cache);
+    $driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
+    $config->setMetadataDriverImpl($driverImpl);
+    $config->setQueryCacheImpl($cache);
+    $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
+    $config->setProxyNamespace('MyProject\Proxies');
+    
+    if ($applicationMode == "development") {
+        $config->setAutoGenerateProxyClasses(true);
+    } else {
+        $config->setAutoGenerateProxyClasses(false);
+    }
+    
+    $connectionOptions = array(
+        'driver' => 'pdo_sqlite',
+        'path' => 'database.sqlite'
+    );
+    
+    $em = EntityManager::create($connectionOptions, $config);
+
+.. note::
+
+    Do not use Doctrine without a metadata and query cache!
+    Doctrine is optimized for working with caches. The main
+    parts in Doctrine that are optimized for caching are the metadata
+    mapping information with the metadata cache and the DQL to SQL
+    conversions with the query cache. These 2 caches require only an
+    absolute minimum of memory yet they heavily improve the runtime
+    performance of Doctrine. The recommended cache driver to use with
+    Doctrine is `APC <http://www.php.net/apc>`_. APC provides you with
+    an opcode-cache (which is highly recommended anyway) and a very
+    fast in-memory cache storage that you can use for the metadata and
+    query caches as seen in the previous code snippet.
+
+Configuration Options
+---------------------
+
+The following sections describe all the configuration options
+available on a ``Doctrine\ORM\Configuration`` instance.
+
+Proxy Directory (***REQUIRED***)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+    <?php
+    $config->setProxyDir($dir);
+    $config->getProxyDir();
+
+Gets or sets the directory where Doctrine generates any proxy
+classes. For a detailed explanation on proxy classes and how they
+are used in Doctrine, refer to the "Proxy Objects" section further
+down.
+
+Proxy Namespace (***REQUIRED***)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+    <?php
+    $config->setProxyNamespace($namespace);
+    $config->getProxyNamespace();
+
+Gets or sets the namespace to use for generated proxy classes. For
+a detailed explanation on proxy classes and how they are used in
+Doctrine, refer to the "Proxy Objects" section further down.
+
+Metadata Driver (***REQUIRED***)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+    <?php
+    $config->setMetadataDriverImpl($driver);
+    $config->getMetadataDriverImpl();
+
+Gets or sets the metadata driver implementation that is used by
+Doctrine to acquire the object-relational metadata for your
+classes.
+
+There are currently 4 available implementations:
+
+
+-  ``Doctrine\ORM\Mapping\Driver\AnnotationDriver``
+-  ``Doctrine\ORM\Mapping\Driver\XmlDriver``
+-  ``Doctrine\ORM\Mapping\Driver\YamlDriver``
+-  ``Doctrine\ORM\Mapping\Driver\DriverChain``
+
+Throughout the most part of this manual the AnnotationDriver is
+used in the examples. For information on the usage of the XmlDriver
+or YamlDriver please refer to the dedicated chapters
+``XML Mapping`` and ``YAML Mapping``.
+
+The annotation driver can be configured with a factory method on
+the ``Doctrine\ORM\Configuration``:
+
+.. code-block:: php
+
+    <?php
+    $driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
+    $config->setMetadataDriverImpl($driverImpl);
+
+The path information to the entities is required for the annotation
+driver, because otherwise mass-operations on all entities through
+the console could not work correctly. All of metadata drivers
+accept either a single directory as a string or an array of
+directories. With this feature a single driver can support multiple
+directories of Entities.
+
+Metadata Cache (***RECOMMENDED***)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+    <?php
+    $config->setMetadataCacheImpl($cache);
+    $config->getMetadataCacheImpl();
+
+Gets or sets the cache implementation to use for caching metadata
+information, that is, all the information you supply via
+annotations, xml or yaml, so that they do not need to be parsed and
+loaded from scratch on every single request which is a waste of
+resources. The cache implementation must implement the
+``Doctrine\Common\Cache\Cache`` interface.
+
+Usage of a metadata cache is highly recommended.
+
+The recommended implementations for production are:
+
+
+-  ``Doctrine\Common\Cache\ApcCache``
+-  ``Doctrine\Common\Cache\ApcuCache``
+-  ``Doctrine\Common\Cache\MemcacheCache``
+-  ``Doctrine\Common\Cache\XcacheCache``
+-  ``Doctrine\Common\Cache\RedisCache``
+
+For development you should use the
+``Doctrine\Common\Cache\ArrayCache`` which only caches data on a
+per-request basis.
+
+Query Cache (***RECOMMENDED***)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+    <?php
+    $config->setQueryCacheImpl($cache);
+    $config->getQueryCacheImpl();
+
+Gets or sets the cache implementation to use for caching DQL
+queries, that is, the result of a DQL parsing process that includes
+the final SQL as well as meta information about how to process the
+SQL result set of a query. Note that the query cache does not
+affect query results. You do not get stale data. This is a pure
+optimization cache without any negative side-effects (except some
+minimal memory usage in your cache).
+
+Usage of a query cache is highly recommended.
+
+The recommended implementations for production are:
+
+
+-  ``Doctrine\Common\Cache\ApcCache``
+-  ``Doctrine\Common\Cache\ApcuCache``
+-  ``Doctrine\Common\Cache\MemcacheCache``
+-  ``Doctrine\Common\Cache\XcacheCache``
+-  ``Doctrine\Common\Cache\RedisCache``
+
+For development you should use the
+``Doctrine\Common\Cache\ArrayCache`` which only caches data on a
+per-request basis.
+
+SQL Logger (***Optional***)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+    <?php
+    $config->setSQLLogger($logger);
+    $config->getSQLLogger();
+
+Gets or sets the logger to use for logging all SQL statements
+executed by Doctrine. The logger class must implement the
+``Doctrine\DBAL\Logging\SQLLogger`` interface. A simple default
+implementation that logs to the standard output using ``echo`` and
+``var_dump`` can be found at
+``Doctrine\DBAL\Logging\EchoSQLLogger``.
+
+Auto-generating Proxy Classes (***OPTIONAL***)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Proxy classes can either be generated manually through the Doctrine
+Console or automatically at runtime by Doctrine. The configuration
+option that controls this behavior is:
+
+.. code-block:: php
+
+    <?php
+    $config->setAutoGenerateProxyClasses($mode);
+
+Possible values for ``$mode`` are:
+
+-  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_NEVER``
+
+Never autogenerate a proxy. You will need to generate the proxies
+manually, for this use the Doctrine Console like so:
+
+.. code-block:: php
+
+    $ ./doctrine orm:generate-proxies
+
+When you do this in a development environment,
+be aware that you may get class/file not found errors if certain proxies
+are not yet generated. You may also get failing lazy-loads if new
+methods were added to the entity class that are not yet in the proxy class.
+In such a case, simply use the Doctrine Console to (re)generate the
+proxy classes.
+
+-  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_ALWAYS``
+
+Always generates a new proxy in every request and writes it to disk.
+
+-  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS``
+
+Generate the proxy class when the proxy file does not exist.
+This strategy causes a file exists call whenever any proxy is
+used the first time in a request.
+
+-  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_EVAL``
+
+Generate the proxy classes and evaluate them on the fly via eval(),
+avoiding writing the proxies to disk.
+This strategy is only sane for development.
+
+In a production environment, it is highly recommended to use
+AUTOGENERATE_NEVER to allow for optimal performances. The other
+options are interesting in development environment.
+
+Before v2.4, ``setAutoGenerateProxyClasses`` would accept a boolean
+value. This is still possible, ``FALSE`` being equivalent to
+AUTOGENERATE_NEVER and ``TRUE`` to AUTOGENERATE_ALWAYS.
+
+Development vs Production Configuration
+---------------------------------------
+
+You should code your Doctrine2 bootstrapping with two different
+runtime models in mind. There are some serious benefits of using
+APC or Memcache in production. In development however this will
+frequently give you fatal errors, when you change your entities and
+the cache still keeps the outdated metadata. That is why we
+recommend the ``ArrayCache`` for development.
+
+Furthermore you should have the Auto-generating Proxy Classes
+option to true in development and to false in production. If this
+option is set to ``TRUE`` it can seriously hurt your script
+performance if several proxy classes are re-generated during script
+execution. Filesystem calls of that magnitude can even slower than
+all the database queries Doctrine issues. Additionally writing a
+proxy sets an exclusive file lock which can cause serious
+performance bottlenecks in systems with regular concurrent
+requests.
+
+Connection Options
+------------------
+
+The ``$connectionOptions`` passed as the first argument to
+``EntityManager::create()`` has to be either an array or an
+instance of ``Doctrine\DBAL\Connection``. If an array is passed it
+is directly passed along to the DBAL Factory
+``Doctrine\DBAL\DriverManager::getConnection()``. The DBAL
+configuration is explained in the
+`DBAL section <https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/configuration.html>`_.
+
+Proxy Objects
+-------------
+
+A proxy object is an object that is put in place or used instead of
+the "real" object. A proxy object can add behavior to the object
+being proxied without that object being aware of it. In Doctrine 2,
+proxy objects are used to realize several features but mainly for
+transparent lazy-loading.
+
+Proxy objects with their lazy-loading facilities help to keep the
+subset of objects that are already in memory connected to the rest
+of the objects. This is an essential property as without it there
+would always be fragile partial objects at the outer edges of your
+object graph.
+
+Doctrine 2 implements a variant of the proxy pattern where it
+generates classes that extend your entity classes and adds
+lazy-loading capabilities to them. Doctrine can then give you an
+instance of such a proxy class whenever you request an object of
+the class being proxied. This happens in two situations:
+
+Reference Proxies
+~~~~~~~~~~~~~~~~~
+
+The method ``EntityManager#getReference($entityName, $identifier)``
+lets you obtain a reference to an entity for which the identifier
+is known, without loading that entity from the database. This is
+useful, for example, as a performance enhancement, when you want to
+establish an association to an entity for which you have the
+identifier. You could simply do this:
+
+.. code-block:: php
+
+    <?php
+    // $em instanceof EntityManager, $cart instanceof MyProject\Model\Cart
+    // $itemId comes from somewhere, probably a request parameter
+    $item = $em->getReference('MyProject\Model\Item', $itemId);
+    $cart->addItem($item);
+
+Here, we added an Item to a Cart without loading the Item from the
+database. If you invoke any method on the Item instance, it would
+fully initialize its state transparently from the database. Here
+$item is actually an instance of the proxy class that was generated
+for the Item class but your code does not need to care. In fact it
+**should not care**. Proxy objects should be transparent to your
+code.
+
+Association proxies
+~~~~~~~~~~~~~~~~~~~
+
+The second most important situation where Doctrine uses proxy
+objects is when querying for objects. Whenever you query for an
+object that has a single-valued association to another object that
+is configured LAZY, without joining that association in the same
+query, Doctrine puts proxy objects in place where normally the
+associated object would be. Just like other proxies it will
+transparently initialize itself on first access.
+
+.. note::
+
+    Joining an association in a DQL or native query
+    essentially means eager loading of that association in that query.
+    This will override the 'fetch' option specified in the mapping for
+    that association, but only for that query.
+
+
+Generating Proxy classes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In a production environment, it is highly recommended to use
+``AUTOGENERATE_NEVER`` to allow for optimal performances.
+However you will be required to generate the proxies manually
+using the Doctrine Console:
+
+.. code-block:: php
+
+    $ ./doctrine orm:generate-proxies
+
+The other options are interesting in development environment:
+
+- ``AUTOGENERATE_ALWAYS`` will require you to create and configure
+  a proxy directory. Proxies will be generated and written to file
+  on each request, so any modification to your code will be acknowledged.
+
+- ``AUTOGENERATE_FILE_NOT_EXISTS`` will not overwrite an existing
+  proxy file. If your code changes, you will need to regenerate the
+  proxies manually.
+
+- ``AUTOGENERATE_EVAL`` will regenerate each proxy on each request,
+  but without writing them to disk.
+
+Autoloading Proxies
+-------------------
+
+When you deserialize proxy objects from the session or any other storage
+it is necessary to have an autoloading mechanism in place for these classes.
+For implementation reasons Proxy class names are not PSR-0 compliant. This
+means that you have to register a special autoloader for these classes:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\Common\Proxy\Autoloader;
+
+    $proxyDir = "/path/to/proxies";
+    $proxyNamespace = "MyProxies";
+
+    Autoloader::register($proxyDir, $proxyNamespace);
+
+If you want to execute additional logic to intercept the proxy file not found
+state you can pass a closure as the third argument. It will be called with
+the arguments proxydir, namespace and className when the proxy file could not
+be found.
+
+Multiple Metadata Sources
+-------------------------
+
+When using different components using Doctrine 2 you may end up
+with them using two different metadata drivers, for example XML and
+YAML. You can use the DriverChain Metadata implementations to
+aggregate these drivers based on namespaces:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\Driver\DriverChain;
+
+    $chain = new DriverChain();
+    $chain->addDriver($xmlDriver, 'Doctrine\Tests\Models\Company');
+    $chain->addDriver($yamlDriver, 'Doctrine\Tests\ORM\Mapping');
+
+Based on the namespace of the entity the loading of entities is
+delegated to the appropriate driver. The chain semantics come from
+the fact that the driver loops through all namespaces and matches
+the entity class name against the namespace using a
+``strpos() === 0`` call. This means you need to order the drivers
+correctly if sub-namespaces use different metadata driver
+implementations.
+
+
+Default Repository (***OPTIONAL***)
+-----------------------------------
+
+Specifies the FQCN of a subclass of the EntityRepository.
+That will be available for all entities without a custom repository class.
+
+.. code-block:: php
+
+    <?php
+    $config->setDefaultRepositoryClassName($fqcn);
+    $config->getDefaultRepositoryClassName();
+
+The default value is ``Doctrine\ORM\EntityRepository``.
+Any repository class must be a subclass of EntityRepository otherwise you got an ORMException
+
+Setting up the Console
+----------------------
+
+Doctrine uses the Symfony Console component for generating the command
+line interface. You can take a look at the ``vendor/bin/doctrine.php``
+script and the ``Doctrine\ORM\Tools\Console\ConsoleRunner`` command
+for inspiration how to setup the cli.
+
+In general the required code looks like this:
+
+.. code-block:: php
+
+    <?php
+    $cli = new Application('Doctrine Command Line Interface', \Doctrine\ORM\Version::VERSION);
+    $cli->setCatchExceptions(true);
+    $cli->setHelperSet($helperSet);
+    Doctrine\ORM\Tools\Console\ConsoleRunner::addCommands($cli);
+    $cli->run();
+

vendor/doctrine/orm/docs/en/reference/architecture.rst

@@ -0,0 +1,197 @@
+Architecture
+============
+
+This chapter gives an overview of the overall architecture,
+terminology and constraints of Doctrine 2. It is recommended to
+read this chapter carefully.
+
+Using an Object-Relational Mapper
+---------------------------------
+
+As the term ORM already hints at, Doctrine 2 aims to simplify the
+translation between database rows and the PHP object model. The
+primary use case for Doctrine are therefore applications that
+utilize the Object-Oriented Programming Paradigm. For applications
+that do not primarily work with objects Doctrine 2 is not suited very
+well.
+
+Requirements
+------------
+
+Doctrine 2 requires a minimum of PHP 7.1. For greatly improved
+performance it is also recommended that you use APC with PHP.
+
+Doctrine 2 Packages
+-------------------
+
+Doctrine 2 is divided into three main packages.
+
+-  Common
+-  DBAL (includes Common)
+-  ORM (includes DBAL+Common)
+
+This manual mainly covers the ORM package, sometimes touching parts
+of the underlying DBAL and Common packages. The Doctrine code base
+is split in to these packages for a few reasons and they are to...
+
+
+-  ...make things more maintainable and decoupled
+-  ...allow you to use the code in Doctrine Common without the ORM
+   or DBAL
+-  ...allow you to use the DBAL without the ORM
+
+The Common Package
+~~~~~~~~~~~~~~~~~~
+
+The Common package contains highly reusable components that have no
+dependencies beyond the package itself (and PHP, of course). The
+root namespace of the Common package is ``Doctrine\Common``.
+
+The DBAL Package
+~~~~~~~~~~~~~~~~
+
+The DBAL package contains an enhanced database abstraction layer on
+top of PDO but is not strongly bound to PDO. The purpose of this
+layer is to provide a single API that bridges most of the
+differences between the different RDBMS vendors. The root namespace
+of the DBAL package is ``Doctrine\DBAL``.
+
+The ORM Package
+~~~~~~~~~~~~~~~
+
+The ORM package contains the object-relational mapping toolkit that
+provides transparent relational persistence for plain PHP objects.
+The root namespace of the ORM package is ``Doctrine\ORM``.
+
+Terminology
+-----------
+
+Entities
+~~~~~~~~
+
+An entity is a lightweight, persistent domain object. An entity can
+be any regular PHP class observing the following restrictions:
+
+
+-  An entity class must not be final or contain final methods.
+-  All persistent properties/field of any entity class should
+   always be private or protected, otherwise lazy-loading might not
+   work as expected. In case you serialize entities (for example Session)
+   properties should be protected (See Serialize section below).
+-  An entity class must not implement ``__clone`` or
+   :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
+-  An entity class must not implement ``__wakeup`` or
+   :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
+   Also consider implementing
+   `Serializable <http://php.net/manual/en/class.serializable.php>`_
+   instead.
+-  Any two entity classes in a class hierarchy that inherit
+   directly or indirectly from one another must not have a mapped
+   property with the same name. That is, if B inherits from A then B
+   must not have a mapped field with the same name as an already
+   mapped field that is inherited from A.
+-  An entity cannot make use of func_get_args() to implement variable parameters.
+   Generated proxies do not support this for performance reasons and your code might
+   actually fail to work when violating this restriction.
+
+Entities support inheritance, polymorphic associations, and
+polymorphic queries. Both abstract and concrete classes can be
+entities. Entities may extend non-entity classes as well as entity
+classes, and non-entity classes may extend entity classes.
+
+.. note::
+
+    The constructor of an entity is only ever invoked when
+    *you* construct a new instance with the *new* keyword. Doctrine
+    never calls entity constructors, thus you are free to use them as
+    you wish and even have it require arguments of any type.
+
+
+Entity states
+~~~~~~~~~~~~~
+
+An entity instance can be characterized as being NEW, MANAGED,
+DETACHED or REMOVED.
+
+
+-  A NEW entity instance has no persistent identity, and is not yet
+   associated with an EntityManager and a UnitOfWork (i.e. those just
+   created with the "new" operator).
+-  A MANAGED entity instance is an instance with a persistent
+   identity that is associated with an EntityManager and whose
+   persistence is thus managed.
+-  A DETACHED entity instance is an instance with a persistent
+   identity that is not (or no longer) associated with an
+   EntityManager and a UnitOfWork.
+-  A REMOVED entity instance is an instance with a persistent
+   identity, associated with an EntityManager, that will be removed
+   from the database upon transaction commit.
+
+.. _architecture_persistent_fields:
+
+Persistent fields
+~~~~~~~~~~~~~~~~~
+
+The persistent state of an entity is represented by instance
+variables. An instance variable must be directly accessed only from
+within the methods of the entity by the entity instance itself.
+Instance variables must not be accessed by clients of the entity.
+The state of the entity is available to clients only through the
+entity’s methods, i.e. accessor methods (getter/setter methods) or
+other business methods.
+
+Collection-valued persistent fields and properties must be defined
+in terms of the ``Doctrine\Common\Collections\Collection``
+interface. The collection implementation type may be used by the
+application to initialize fields or properties before the entity is
+made persistent. Once the entity becomes managed (or detached),
+subsequent access must be through the interface type.
+
+Serializing entities
+~~~~~~~~~~~~~~~~~~~~
+
+Serializing entities can be problematic and is not really
+recommended, at least not as long as an entity instance still holds
+references to proxy objects or is still managed by an
+EntityManager. If you intend to serialize (and unserialize) entity
+instances that still hold references to proxy objects you may run
+into problems with private properties because of technical
+limitations. Proxy objects implement ``__sleep`` and it is not
+possible for ``__sleep`` to return names of private properties in
+parent classes. On the other hand it is not a solution for proxy
+objects to implement ``Serializable`` because Serializable does not
+work well with any potential cyclic object references (at least we
+did not find a way yet, if you did, please contact us).
+
+The EntityManager
+~~~~~~~~~~~~~~~~~
+
+The ``EntityManager`` class is a central access point to the ORM
+functionality provided by Doctrine 2. The ``EntityManager`` API is
+used to manage the persistence of your objects and to query for
+persistent objects.
+
+Transactional write-behind
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An ``EntityManager`` and the underlying ``UnitOfWork`` employ a
+strategy called "transactional write-behind" that delays the
+execution of SQL statements in order to execute them in the most
+efficient way and to execute them at the end of a transaction so
+that all write locks are quickly released. You should see Doctrine
+as a tool to synchronize your in-memory objects with the database
+in well defined units of work. Work with your objects and modify
+them as usual and when you're done call ``EntityManager#flush()``
+to make your changes persistent.
+
+The Unit of Work
+~~~~~~~~~~~~~~~~
+
+Internally an ``EntityManager`` uses a ``UnitOfWork``, which is a
+typical implementation of the
+`Unit of Work pattern <http://martinfowler.com/eaaCatalog/unitOfWork.html>`_,
+to keep track of all the things that need to be done the next time
+``flush`` is invoked. You usually do not directly interact with a
+``UnitOfWork`` but with the ``EntityManager`` instead.
+
+

vendor/doctrine/orm/docs/en/reference/basic-mapping.rst

@@ -0,0 +1,504 @@
+Basic Mapping
+=============
+
+This guide explains the basic mapping of entities and properties.
+After working through this guide you should know:
+
+- How to create PHP objects that can be saved to the database with Doctrine;
+- How to configure the mapping between columns on tables and properties on
+  entities;
+- What Doctrine mapping types are;
+- Defining primary keys and how identifiers are generated by Doctrine;
+- How quoting of reserved symbols works in Doctrine.
+
+Mapping of associations will be covered in the next chapter on
+:doc:`Association Mapping <association-mapping>`.
+
+Guide Assumptions
+-----------------
+
+You should have already :doc:`installed and configure <configuration>`
+Doctrine.
+
+Creating Classes for the Database
+---------------------------------
+
+Every PHP object that you want to save in the database using Doctrine
+is called an "Entity". The term "Entity" describes objects
+that have an identity over many independent requests. This identity is
+usually achieved by assigning a unique identifier to an entity.
+In this tutorial the following ``Message`` PHP class will serve as the
+example Entity:
+
+.. code-block:: php
+
+    <?php
+    class Message
+    {
+        private $id;
+        private $text;
+        private $postedAt;
+    }
+
+Because Doctrine is a generic library, it only knows about your
+entities because you will describe their existence and structure using
+mapping metadata, which is configuration that tells Doctrine how your
+entity should be stored in the database. The documentation will often
+speak of "mapping something", which means writing the mapping metadata
+that describes your entity.
+
+Doctrine provides several different ways to specify object-relational
+mapping metadata:
+
+-  :doc:`Docblock Annotations <annotations-reference>`
+-  :doc:`XML <xml-mapping>`
+-  :doc:`YAML <yaml-mapping>`
+-  :doc:`PHP code <php-mapping>`
+
+This manual will usually show mapping metadata via docblock annotations, though
+many examples also show the equivalent configuration in YAML and XML.
+
+.. note::
+
+    All metadata drivers perform equally. Once the metadata of a class has been
+    read from the source (annotations, xml or yaml) it is stored in an instance
+    of the ``Doctrine\ORM\Mapping\ClassMetadata`` class and these instances are
+    stored in the metadata cache.  If you're not using a metadata cache (not
+    recommended!) then the XML driver is the fastest.
+
+Marking our ``Message`` class as an entity for Doctrine is straightforward:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        /** @Entity */
+        class Message
+        {
+            //...
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="Message">
+              <!-- ... -->
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        Message:
+          type: entity
+          # ...
+
+With no additional information, Doctrine expects the entity to be saved
+into a table with the same name as the class in our case ``Message``.
+You can change this by configuring information about the table:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        /**
+         * @Entity
+         * @Table(name="message")
+         */
+        class Message
+        {
+            //...
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="Message" table="message">
+              <!-- ... -->
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        Message:
+          type: entity
+          table: message
+          # ...
+
+Now the class ``Message`` will be saved and fetched from the table ``message``.
+
+Property Mapping
+----------------
+
+The next step after marking a PHP class as an entity is mapping its properties
+to columns in a table.
+
+To configure a property use the ``@Column`` docblock annotation. The ``type``
+attribute specifies the :ref:`Doctrine Mapping Type <reference-mapping-types>`
+to use for the field. If the type is not specified, ``string`` is used as the
+default.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        /** @Entity */
+        class Message
+        {
+            /** @Column(type="integer") */
+            private $id;
+            /** @Column(length=140) */
+            private $text;
+            /** @Column(type="datetime", name="posted_at") */
+            private $postedAt;
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="Message">
+            <field name="id" type="integer" />
+            <field name="text" length="140" />
+            <field name="postedAt" column="posted_at" type="datetime" />
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        Message:
+          type: entity
+          fields:
+            id:
+              type: integer
+            text:
+              length: 140
+            postedAt:
+              type: datetime
+              column: posted_at
+
+When we don't explicitly specify a column name via the ``name`` option, Doctrine
+assumes the field name is also the column name. This means that:
+
+* the ``id`` property will map to the column ``id`` using the type ``integer``;
+* the ``text`` property will map to the column ``text`` with the default mapping type ``string``;
+* the ``postedAt`` property will map to the ``posted_at`` column with the ``datetime`` type.
+
+The Column annotation has some more attributes. Here is a complete
+list:
+
+- ``type``: (optional, defaults to 'string') The mapping type to
+  use for the column.
+- ``name``: (optional, defaults to field name) The name of the
+  column in the database.
+- ``length``: (optional, default 255) The length of the column in
+  the database. (Applies only if a string-valued column is used).
+- ``unique``: (optional, default FALSE) Whether the column is a
+  unique key.
+- ``nullable``: (optional, default FALSE) Whether the database
+  column is nullable.
+- ``precision``: (optional, default 0) The precision for a decimal
+  (exact numeric) column (applies only for decimal column),
+  which is the maximum number of digits that are stored for the values.
+- ``scale``: (optional, default 0) The scale for a decimal (exact
+  numeric) column (applies only for decimal column), which represents
+  the number of digits to the right of the decimal point and must
+  not be greater than *precision*.
+- ``columnDefinition``: (optional) Allows to define a custom
+  DDL snippet that is used to create the column. Warning: This normally
+  confuses the SchemaTool to always detect the column as changed.
+- ``options``: (optional) Key-value pairs of options that get passed
+  to the underlying database platform when generating DDL statements.
+
+.. _reference-mapping-types:
+
+Doctrine Mapping Types
+----------------------
+
+The ``type`` option used in the ``@Column`` accepts any of the existing
+Doctrine types or even your own custom types. A Doctrine type defines
+the conversion between PHP and SQL types, independent from the database vendor
+you are using. All Mapping Types that ship with Doctrine are fully portable
+between the supported database systems.
+
+As an example, the Doctrine Mapping Type ``string`` defines the
+mapping from a PHP string to a SQL VARCHAR (or VARCHAR2 etc.
+depending on the RDBMS brand). Here is a quick overview of the
+built-in mapping types:
+
+-  ``string``: Type that maps a SQL VARCHAR to a PHP string.
+-  ``integer``: Type that maps a SQL INT to a PHP integer.
+-  ``smallint``: Type that maps a database SMALLINT to a PHP
+   integer.
+-  ``bigint``: Type that maps a database BIGINT to a PHP string.
+-  ``boolean``: Type that maps a SQL boolean or equivalent (TINYINT) to a PHP boolean.
+-  ``decimal``: Type that maps a SQL DECIMAL to a PHP string.
+-  ``date``: Type that maps a SQL DATETIME to a PHP DateTime
+   object.
+-  ``time``: Type that maps a SQL TIME to a PHP DateTime object.
+-  ``datetime``: Type that maps a SQL DATETIME/TIMESTAMP to a PHP
+   DateTime object.
+-  ``datetimetz``: Type that maps a SQL DATETIME/TIMESTAMP to a PHP
+   DateTime object with timezone.
+-  ``text``: Type that maps a SQL CLOB to a PHP string.
+-  ``object``: Type that maps a SQL CLOB to a PHP object using
+   ``serialize()`` and ``unserialize()``
+-  ``array``: Type that maps a SQL CLOB to a PHP array using
+   ``serialize()`` and ``unserialize()``
+-  ``simple_array``: Type that maps a SQL CLOB to a PHP array using
+   ``implode()`` and ``explode()``, with a comma as delimiter. *IMPORTANT*
+   Only use this type if you are sure that your values cannot contain a ",".
+-  ``json_array``: Type that maps a SQL CLOB to a PHP array using
+   ``json_encode()`` and ``json_decode()``
+-  ``float``: Type that maps a SQL Float (Double Precision) to a
+   PHP double. *IMPORTANT*: Works only with locale settings that use
+   decimal points as separator.
+-  ``guid``: Type that maps a database GUID/UUID to a PHP string. Defaults to
+   varchar but uses a specific type if the platform supports it.
+-  ``blob``: Type that maps a SQL BLOB to a PHP resource stream
+
+A cookbook article shows how to define :doc:`your own custom mapping types
+<../cookbook/custom-mapping-types>`.
+
+.. note::
+
+    DateTime and Object types are compared by reference, not by value. Doctrine
+    updates this values if the reference changes and therefore behaves as if
+    these objects are immutable value objects.
+
+.. warning::
+
+    All Date types assume that you are exclusively using the default timezone
+    set by `date_default_timezone_set() <http://php.net/manual/en/function.date-default-timezone-set.php>`_
+    or by the php.ini configuration ``date.timezone``. Working with
+    different timezones will cause troubles and unexpected behavior.
+
+    If you need specific timezone handling you have to handle this
+    in your domain, converting all the values back and forth from UTC.
+    There is also a :doc:`cookbook entry <../cookbook/working-with-datetime>`
+    on working with datetimes that gives hints for implementing
+    multi timezone applications.
+
+Identifiers / Primary Keys
+--------------------------
+
+Every entity class must have an identifier/primary key. You can select
+the field that serves as the identifier with the ``@Id``
+annotation.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        class Message
+        {
+            /**
+             * @Id
+             * @Column(type="integer")
+             * @GeneratedValue
+             */
+            private $id;
+            //...
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="Message">
+            <id name="id" type="integer">
+                <generator strategy="AUTO" />
+            </id>
+            <!-- -->
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        Message:
+          type: entity
+          id:
+            id:
+              type: integer
+              generator:
+                strategy: AUTO
+          fields:
+            # fields here
+
+In most cases using the automatic generator strategy (``@GeneratedValue``) is
+what you want. It defaults to the identifier generation mechanism your current
+database vendor prefers: AUTO_INCREMENT with MySQL, sequences with PostgreSQL 
+and Oracle and so on.
+
+Identifier Generation Strategies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The previous example showed how to use the default identifier
+generation strategy without knowing the underlying database with
+the AUTO-detection strategy. It is also possible to specify the
+identifier generation strategy more explicitly, which allows you to
+make use of some additional features.
+
+Here is the list of possible generation strategies:
+
+-  ``AUTO`` (default): Tells Doctrine to pick the strategy that is
+   preferred by the used database platform. The preferred strategies
+   are IDENTITY for MySQL, SQLite, MsSQL and SQL Anywhere and SEQUENCE
+   for Oracle and PostgreSQL. This strategy provides full portability.
+-  ``SEQUENCE``: Tells Doctrine to use a database sequence for ID
+   generation. This strategy does currently not provide full
+   portability. Sequences are supported by Oracle, PostgreSql and
+   SQL Anywhere.
+-  ``IDENTITY``: Tells Doctrine to use special identity columns in
+   the database that generate a value on insertion of a row. This
+   strategy does currently not provide full portability and is
+   supported by the following platforms: MySQL/SQLite/SQL Anywhere
+   (AUTO\_INCREMENT), MSSQL (IDENTITY) and PostgreSQL (SERIAL).
+-  ``UUID``: Tells Doctrine to use the built-in Universally Unique Identifier
+   generator. This strategy provides full portability.
+-  ``TABLE``: Tells Doctrine to use a separate table for ID
+   generation. This strategy provides full portability.
+   ***This strategy is not yet implemented!***
+-  ``NONE``: Tells Doctrine that the identifiers are assigned (and
+   thus generated) by your code. The assignment must take place before
+   a new entity is passed to ``EntityManager#persist``. NONE is the
+   same as leaving off the @GeneratedValue entirely.
+-  ``CUSTOM``: With this option, you can use the ``@CustomIdGenerator`` annotation.
+   It will allow you to pass a :doc:`class of your own to generate the identifiers.<_annref_customidgenerator>`
+
+Sequence Generator
+^^^^^^^^^^^^^^^^^^
+
+The Sequence Generator can currently be used in conjunction with
+Oracle or Postgres and allows some additional configuration options
+besides specifying the sequence's name:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        class Message
+        {
+            /**
+             * @Id
+             * @GeneratedValue(strategy="SEQUENCE")
+             * @SequenceGenerator(sequenceName="message_seq", initialValue=1, allocationSize=100)
+             */
+            protected $id = null;
+            //...
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="Message">
+            <id name="id" type="integer">
+                <generator strategy="SEQUENCE" />
+                <sequence-generator sequence-name="message_seq" allocation-size="100" initial-value="1" />
+            </id>
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        Message:
+          type: entity
+          id:
+            id:
+              type: integer
+              generator:
+                strategy: SEQUENCE
+              sequenceGenerator:
+                sequenceName: message_seq
+                allocationSize: 100
+                initialValue: 1
+
+The initial value specifies at which value the sequence should
+start.
+
+The allocationSize is a powerful feature to optimize INSERT
+performance of Doctrine. The allocationSize specifies by how much
+values the sequence is incremented whenever the next value is
+retrieved. If this is larger than 1 (one) Doctrine can generate
+identifier values for the allocationSizes amount of entities. In
+the above example with ``allocationSize=100`` Doctrine 2 would only
+need to access the sequence once to generate the identifiers for
+100 new entities.
+
+*The default allocationSize for a @SequenceGenerator is currently 10.*
+
+.. caution::
+
+    The allocationSize is detected by SchemaTool and
+    transformed into an "INCREMENT BY " clause in the CREATE SEQUENCE
+    statement. For a database schema created manually (and not
+    SchemaTool) you have to make sure that the allocationSize
+    configuration option is never larger than the actual sequences
+    INCREMENT BY value, otherwise you may get duplicate keys.
+
+
+.. note::
+
+    It is possible to use strategy="AUTO" and at the same time
+    specifying a @SequenceGenerator. In such a case, your custom
+    sequence settings are used in the case where the preferred strategy
+    of the underlying platform is SEQUENCE, such as for Oracle and
+    PostgreSQL.
+
+
+Composite Keys
+~~~~~~~~~~~~~~
+
+With Doctrine 2 you can use composite primary keys, using ``@Id`` on more then
+one column. Some restrictions exist opposed to using a single identifier in
+this case: The use of the ``@GeneratedValue`` annotation is not supported,
+which means you can only use composite keys if you generate the primary key
+values yourself before calling ``EntityManager#persist()`` on the entity.
+
+More details on composite primary keys are discussed in a :doc:`dedicated tutorial
+<../tutorials/composite-primary-keys>`.
+
+Quoting Reserved Words
+----------------------
+
+Sometimes it is necessary to quote a column or table name because of reserved
+word conflicts. Doctrine does not quote identifiers automatically, because it
+leads to more problems than it would solve. Quoting tables and column names
+needs to be done explicitly using ticks in the definition.
+
+.. code-block:: php
+
+    <?php
+    /** @Column(name="`number`", type="integer") */
+    private $number;
+
+Doctrine will then quote this column name in all SQL statements
+according to the used database platform.
+
+.. warning::
+
+    Identifier Quoting does not work for join column names or discriminator
+    column names unless you are using a custom ``QuoteStrategy``.
+
+.. _reference-basic-mapping-custom-mapping-types:
+
+.. versionadded: 2.3
+
+For more control over column quoting the ``Doctrine\ORM\Mapping\QuoteStrategy`` interface
+was introduced in 2.3. It is invoked for every column, table, alias and other
+SQL names. You can implement the QuoteStrategy and set it by calling
+``Doctrine\ORM\Configuration#setQuoteStrategy()``.
+
+.. versionadded: 2.4
+
+The ANSI Quote Strategy was added, which assumes quoting is not necessary for any SQL name.
+You can use it with the following code:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\AnsiQuoteStrategy;
+
+    $configuration->setQuoteStrategy(new AnsiQuoteStrategy());

vendor/doctrine/orm/docs/en/reference/batch-processing.rst

@@ -0,0 +1,196 @@
+Batch Processing
+================
+
+This chapter shows you how to accomplish bulk inserts, updates and
+deletes with Doctrine in an efficient way. The main problem with
+bulk operations is usually not to run out of memory and this is
+especially what the strategies presented here provide help with.
+
+.. warning::
+
+    An ORM tool is not primarily well-suited for mass
+    inserts, updates or deletions. Every RDBMS has its own, most
+    effective way of dealing with such operations and if the options
+    outlined below are not sufficient for your purposes we recommend
+    you use the tools for your particular RDBMS for these bulk
+    operations.
+
+
+.. note::
+
+    Having an SQL logger enabled when processing batches can have a serious impact on performance and resource usage.
+    To avoid that you should disable it in the DBAL configuration:
+.. code-block:: php
+
+    <?php
+    $em->getConnection()->getConfiguration()->setSQLLogger(null);
+
+Bulk Inserts
+------------
+
+Bulk inserts in Doctrine are best performed in batches, taking
+advantage of the transactional write-behind behavior of an
+``EntityManager``. The following code shows an example for
+inserting 10000 objects with a batch size of 20. You may need to
+experiment with the batch size to find the size that works best for
+you. Larger batch sizes mean more prepared statement reuse
+internally but also mean more work during ``flush``.
+
+.. code-block:: php
+
+    <?php
+    $batchSize = 20;
+    for ($i = 1; $i <= 10000; ++$i) {
+        $user = new CmsUser;
+        $user->setStatus('user');
+        $user->setUsername('user' . $i);
+        $user->setName('Mr.Smith-' . $i);
+        $em->persist($user);
+        if (($i % $batchSize) === 0) {
+            $em->flush();
+            $em->clear(); // Detaches all objects from Doctrine!
+        }
+    }
+    $em->flush(); //Persist objects that did not make up an entire batch
+    $em->clear();
+
+Bulk Updates
+------------
+
+There are 2 possibilities for bulk updates with Doctrine.
+
+DQL UPDATE
+~~~~~~~~~~
+
+The by far most efficient way for bulk updates is to use a DQL
+UPDATE query. Example:
+
+.. code-block:: php
+
+    <?php
+    $q = $em->createQuery('update MyProject\Model\Manager m set m.salary = m.salary * 0.9');
+    $numUpdated = $q->execute();
+
+Iterating results
+~~~~~~~~~~~~~~~~~
+
+An alternative solution for bulk updates is to use the
+``Query#iterate()`` facility to iterate over the query results step
+by step instead of loading the whole result into memory at once.
+The following example shows how to do this, combining the iteration
+with the batching strategy that was already used for bulk inserts:
+
+.. code-block:: php
+
+    <?php
+    $batchSize = 20;
+    $i = 1;
+    $q = $em->createQuery('select u from MyProject\Model\User u');
+    $iterableResult = $q->iterate();
+    foreach ($iterableResult as $row) {
+        $user = $row[0];
+        $user->increaseCredit();
+        $user->calculateNewBonuses();
+        if (($i % $batchSize) === 0) {
+            $em->flush(); // Executes all updates.
+            $em->clear(); // Detaches all objects from Doctrine!
+        }
+        ++$i;
+    }
+    $em->flush();
+
+.. note::
+
+    Iterating results is not possible with queries that
+    fetch-join a collection-valued association. The nature of such SQL
+    result sets is not suitable for incremental hydration.
+
+.. note::
+
+    Results may be fully buffered by the database client/ connection allocating
+    additional memory not visible to the PHP process. For large sets this
+    may easily kill the process for no apparent reason.
+
+
+Bulk Deletes
+------------
+
+There are two possibilities for bulk deletes with Doctrine. You can
+either issue a single DQL DELETE query or you can iterate over
+results removing them one at a time.
+
+DQL DELETE
+~~~~~~~~~~
+
+The by far most efficient way for bulk deletes is to use a DQL
+DELETE query.
+
+Example:
+
+.. code-block:: php
+
+    <?php
+    $q = $em->createQuery('delete from MyProject\Model\Manager m where m.salary > 100000');
+    $numDeleted = $q->execute();
+
+Iterating results
+~~~~~~~~~~~~~~~~~
+
+An alternative solution for bulk deletes is to use the
+``Query#iterate()`` facility to iterate over the query results step
+by step instead of loading the whole result into memory at once.
+The following example shows how to do this:
+
+.. code-block:: php
+
+    <?php
+    $batchSize = 20;
+    $i = 1;
+    $q = $em->createQuery('select u from MyProject\Model\User u');
+    $iterableResult = $q->iterate();
+    while (($row = $iterableResult->next()) !== false) {
+        $em->remove($row[0]);
+        if (($i % $batchSize) === 0) {
+            $em->flush(); // Executes all deletions.
+            $em->clear(); // Detaches all objects from Doctrine!
+        }
+        ++$i;
+    }
+    $em->flush();
+
+.. note::
+
+    Iterating results is not possible with queries that
+    fetch-join a collection-valued association. The nature of such SQL
+    result sets is not suitable for incremental hydration.
+
+
+Iterating Large Results for Data-Processing
+-------------------------------------------
+
+You can use the ``iterate()`` method just to iterate over a large
+result and no UPDATE or DELETE intention. The ``IterableResult``
+instance returned from ``$query->iterate()`` implements the
+Iterator interface so you can process a large result without memory
+problems using the following approach:
+
+.. code-block:: php
+
+    <?php
+    $q = $this->_em->createQuery('select u from MyProject\Model\User u');
+    $iterableResult = $q->iterate();
+    foreach ($iterableResult as $row) {
+        // do stuff with the data in the row, $row[0] is always the object
+    
+        // detach from Doctrine, so that it can be Garbage-Collected immediately
+        $this->_em->detach($row[0]);
+    }
+
+.. note::
+
+    Iterating results is not possible with queries that
+    fetch-join a collection-valued association. The nature of such SQL
+    result sets is not suitable for incremental hydration.
+
+
+

vendor/doctrine/orm/docs/en/reference/best-practices.rst

@@ -0,0 +1,111 @@
+Best Practices
+==============
+
+The best practices mentioned here that affect database
+design generally refer to best practices when working with Doctrine
+and do not necessarily reflect best practices for database design
+in general.
+
+Constrain relationships as much as possible
+-------------------------------------------
+
+It is important to constrain relationships as much as possible.
+This means:
+
+
+-  Impose a traversal direction (avoid bidirectional associations
+   if possible)
+-  Eliminate nonessential associations
+
+This has several benefits:
+
+
+-  Reduced coupling in your domain model
+-  Simpler code in your domain model (no need to maintain
+   bidirectionality properly)
+-  Less work for Doctrine
+
+Avoid composite keys
+--------------------
+
+Even though Doctrine fully supports composite keys it is best not
+to use them if possible. Composite keys require additional work by
+Doctrine and thus have a higher probability of errors.
+
+Use events judiciously
+----------------------
+
+The event system of Doctrine is great and fast. Even though making
+heavy use of events, especially lifecycle events, can have a
+negative impact on the performance of your application. Thus you
+should use events judiciously.
+
+Use cascades judiciously
+------------------------
+
+Automatic cascades of the persist/remove/merge/etc. operations are
+very handy but should be used wisely. Do NOT simply add all
+cascades to all associations. Think about which cascades actually
+do make sense for you for a particular association, given the
+scenarios it is most likely used in.
+
+Don't use special characters
+----------------------------
+
+Avoid using any non-ASCII characters in class, field, table or
+column names. Doctrine itself is not unicode-safe in many places
+and will not be until PHP itself is fully unicode-aware.
+
+Don't use identifier quoting
+----------------------------
+
+Identifier quoting is a workaround for using reserved words that
+often causes problems in edge cases. Do not use identifier quoting
+and avoid using reserved words as table or column names.
+
+Initialize collections in the constructor
+-----------------------------------------
+
+It is recommended best practice to initialize any business
+collections in entities in the constructor. Example:
+
+.. code-block:: php
+
+    <?php
+    namespace MyProject\Model;
+    use Doctrine\Common\Collections\ArrayCollection;
+    
+    class User {
+        private $addresses;
+        private $articles;
+    
+        public function __construct() {
+            $this->addresses = new ArrayCollection;
+            $this->articles = new ArrayCollection;
+        }
+    }
+
+Don't map foreign keys to fields in an entity
+---------------------------------------------
+
+Foreign keys have no meaning whatsoever in an object model. Foreign
+keys are how a relational database establishes relationships. Your
+object model establishes relationships through object references.
+Thus mapping foreign keys to object fields heavily leaks details of
+the relational model into the object model, something you really
+should not do.
+
+Use explicit transaction demarcation
+------------------------------------
+
+While Doctrine will automatically wrap all DML operations in a
+transaction on flush(), it is considered best practice to
+explicitly set the transaction boundaries yourself. Otherwise every
+single query is wrapped in a small transaction (Yes, SELECT
+queries, too) since you can not talk to your database outside of a
+transaction. While such short transactions for read-only (SELECT)
+queries generally don't have any noticeable performance impact, it
+is still preferable to use fewer, well-defined transactions that
+are established through explicit transaction boundaries.
+
+

vendor/doctrine/orm/docs/en/reference/caching.rst

@@ -0,0 +1,467 @@
+Caching
+=======
+
+Doctrine provides cache drivers in the ``doctrine/cache`` package for some
+of the most popular caching implementations such as APCu, Memcache
+and Xcache. We also provide an ``ArrayCache`` driver which stores
+the data in a PHP array. Obviously, when using ``ArrayCache``, the 
+cache does not persist between requests, but this is useful for 
+testing in a development environment.
+
+Cache Drivers
+-------------
+
+The cache drivers follow a simple interface that is defined in
+``Doctrine\Common\Cache\Cache``. All the cache drivers extend a
+base class ``Doctrine\Common\Cache\CacheProvider`` which implements
+this interface.
+
+The interface defines the following public methods for you to implement:
+
+
+-  fetch($id) - Fetches an entry from the cache
+-  contains($id) - Test if an entry exists in the cache
+-  save($id, $data, $lifeTime = false) - Puts data into the cache for x seconds. 0 = infinite time
+-  delete($id) - Deletes a cache entry
+
+Each driver extends the ``CacheProvider`` class which defines a few
+abstract protected methods that each of the drivers must
+implement:
+
+
+-  doFetch($id)
+-  doContains($id)
+-  doSave($id, $data, $lifeTime = false)
+-  doDelete($id)
+
+The public methods ``fetch()``, ``contains()`` etc. use the
+above protected methods which are implemented by the drivers. The
+code is organized this way so that the protected methods in the
+drivers do the raw interaction with the cache implementation and
+the ``CacheProvider`` can build custom functionality on top of
+these methods.
+
+This documentation does not cover every single cache driver included
+with Doctrine. For an up-to-date-list, see the
+`cache directory on GitHub <https://github.com/doctrine/cache/tree/master/lib/Doctrine/Common/Cache>`_.
+
+PhpFileCache
+~~~~~~~~~~~~
+
+The preferred cache driver for metadata and query caches is ``PhpFileCache``.
+This driver serializes cache items and writes them to a file. This allows for
+opcode caching to be used and provides high performance in most scenarios.
+
+In order to use the ``PhpFileCache`` driver it must be able to write to
+a directory.
+
+Below is an example of how to use the ``PhpFileCache`` driver by itself.
+
+.. code-block:: php
+
+    <?php
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
+        '/path/to/writable/directory'
+    );
+    $cacheDriver->save('cache_id', 'my_data');
+
+The PhpFileCache is not distributed across multiple machines if you are running
+your application in a distributed setup. This is ok for the metadata and query
+cache but is not a good approach for the result cache.
+
+Memcache
+~~~~~~~~
+
+In order to use the Memcache cache driver you must have it compiled
+and enabled in your php.ini. You can read about Memcache
+`on the PHP website <http://php.net/memcache>`_. It will
+give you a little background information about what it is and how
+you can use it as well as how to install it.
+
+Below is a simple example of how you could use the Memcache cache
+driver by itself.
+
+.. code-block:: php
+
+    <?php
+    $memcache = new Memcache();
+    $memcache->connect('memcache_host', 11211);
+    
+    $cacheDriver = new \Doctrine\Common\Cache\MemcacheCache();
+    $cacheDriver->setMemcache($memcache);
+    $cacheDriver->save('cache_id', 'my_data');
+
+Memcached
+~~~~~~~~~
+
+Memcached is a more recent and complete alternative extension to
+Memcache.
+
+In order to use the Memcached cache driver you must have it compiled
+and enabled in your php.ini. You can read about Memcached
+`on the PHP website <http://php.net/memcached>`_. It will
+give you a little background information about what it is and how
+you can use it as well as how to install it.
+
+Below is a simple example of how you could use the Memcached cache
+driver by itself.
+
+.. code-block:: php
+
+    <?php
+    $memcached = new Memcached();
+    $memcached->addServer('memcache_host', 11211);
+    
+    $cacheDriver = new \Doctrine\Common\Cache\MemcachedCache();
+    $cacheDriver->setMemcached($memcached);
+    $cacheDriver->save('cache_id', 'my_data');
+
+Redis
+~~~~~
+
+In order to use the Redis cache driver you must have it compiled
+and enabled in your php.ini. You can read about what Redis is
+`from here <http://redis.io/>`_. Also check
+`A PHP extension for Redis <https://github.com/nicolasff/phpredis/>`_ for how you can use
+and install the Redis PHP extension.
+
+Below is a simple example of how you could use the Redis cache
+driver by itself.
+
+.. code-block:: php
+
+    <?php
+    $redis = new Redis();
+    $redis->connect('redis_host', 6379);
+
+    $cacheDriver = new \Doctrine\Common\Cache\RedisCache();
+    $cacheDriver->setRedis($redis);
+    $cacheDriver->save('cache_id', 'my_data');
+
+Using Cache Drivers
+-------------------
+
+In this section we'll describe how you can fully utilize the API of
+the cache drivers to save data to a cache, check if some cached data 
+exists, fetch the cached data and delete the cached data. We'll use the
+``ArrayCache`` implementation as our example here.
+
+.. code-block:: php
+
+    <?php
+    $cacheDriver = new \Doctrine\Common\Cache\ArrayCache();
+
+Saving
+~~~~~~
+
+Saving some data to the cache driver is as simple as using the
+``save()`` method.
+
+.. code-block:: php
+
+    <?php
+    $cacheDriver->save('cache_id', 'my_data');
+
+The ``save()`` method accepts three arguments which are described
+below:
+
+
+-  ``$id`` - The cache id
+-  ``$data`` - The cache entry/data.
+-  ``$lifeTime`` - The lifetime. If != false, sets a specific
+   lifetime for this cache entry (null => infinite lifeTime).
+
+You can save any type of data whether it be a string, array,
+object, etc.
+
+.. code-block:: php
+
+    <?php
+    $array = array(
+        'key1' => 'value1',
+        'key2' => 'value2'
+    );
+    $cacheDriver->save('my_array', $array);
+
+Checking
+~~~~~~~~
+
+Checking whether cached data exists is very simple: just use the
+``contains()`` method. It accepts a single argument which is the ID
+of the cache entry.
+
+.. code-block:: php
+
+    <?php
+    if ($cacheDriver->contains('cache_id')) {
+        echo 'cache exists';
+    } else {
+        echo 'cache does not exist';
+    }
+
+Fetching
+~~~~~~~~
+
+Now if you want to retrieve some cache entry you can use the
+``fetch()`` method. It also accepts a single argument just like
+``contains()`` which is again the ID of the cache entry.
+
+.. code-block:: php
+
+    <?php
+    $array = $cacheDriver->fetch('my_array');
+
+Deleting
+~~~~~~~~
+
+As you might guess, deleting is just as easy as saving, checking
+and fetching. You can delete by an individual ID, or you can 
+delete all entries.
+
+By Cache ID
+^^^^^^^^^^^
+
+.. code-block:: php
+
+    <?php
+    $cacheDriver->delete('my_array');
+
+All
+^^^
+
+If you simply want to delete all cache entries you can do so with
+the ``deleteAll()`` method.
+
+.. code-block:: php
+
+    <?php
+    $deleted = $cacheDriver->deleteAll();
+
+Namespaces
+~~~~~~~~~~
+
+If you heavily use caching in your application and use it in
+multiple parts of your application, or use it in different
+applications on the same server you may have issues with cache
+naming collisions. This can be worked around by using namespaces.
+You can set the namespace a cache driver should use by using the
+``setNamespace()`` method.
+
+.. code-block:: php
+
+    <?php
+    $cacheDriver->setNamespace('my_namespace_');
+
+.. _integrating-with-the-orm:
+
+Integrating with the ORM
+------------------------
+
+The Doctrine ORM package is tightly integrated with the cache
+drivers to allow you to improve the performance of various aspects of
+Doctrine by simply making some additional configurations and
+method calls.
+
+Query Cache
+~~~~~~~~~~~
+
+It is highly recommended that in a production environment you cache
+the transformation of a DQL query to its SQL counterpart. It
+doesn't make sense to do this parsing multiple times as it doesn't
+change unless you alter the DQL query.
+
+This can be done by configuring the query cache implementation to
+use on your ORM configuration.
+
+.. code-block:: php
+
+    <?php
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
+        '/path/to/writable/directory'
+    );
+    $config = new \Doctrine\ORM\Configuration();
+    $config->setQueryCacheImpl($cacheDriver);
+
+Result Cache
+~~~~~~~~~~~~
+
+The result cache can be used to cache the results of your queries
+so that we don't have to query the database or hydrate the data
+again after the first time. You just need to configure the result
+cache implementation.
+
+.. code-block:: php
+
+    <?php
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
+        '/path/to/writable/directory'
+    );
+    $config = new \Doctrine\ORM\Configuration();
+    $config->setResultCacheImpl($cacheDriver);
+
+Now when you're executing DQL queries you can configure them to use
+the result cache.
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('select u from \Entities\User u');
+    $query->enableResultCache();
+
+You can also configure an individual query to use a different
+result cache driver.
+
+.. code-block:: php
+
+    <?php
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
+        '/path/to/writable/directory'
+    );
+    $query->setResultCacheDriver($cacheDriver);
+
+.. note::
+
+    Setting the result cache driver on the query will
+    automatically enable the result cache for the query. If you want to
+    disable it use ``disableResultCache()``.
+
+    ::
+
+        <?php
+        $query->disableResultCache();
+
+
+If you want to set the time the cache has to live you can use the
+``setResultCacheLifetime()`` method.
+
+.. code-block:: php
+
+    <?php
+    $query->setResultCacheLifetime(3600);
+
+The ID used to store the result set cache is a hash which is
+automatically generated for you if you don't set a custom ID
+yourself with the ``setResultCacheId()`` method.
+
+.. code-block:: php
+
+    <?php
+    $query->setResultCacheId('my_custom_id');
+
+You can also set the lifetime and cache ID by passing the values as
+the first and second argument to ``enableResultCache()``.
+
+.. code-block:: php
+
+    <?php
+    $query->enableResultCache(3600, 'my_custom_id');
+
+Metadata Cache
+~~~~~~~~~~~~~~
+
+Your class metadata can be parsed from a few different sources like
+YAML, XML, Annotations, etc. Instead of parsing this information on
+each request we should cache it using one of the cache drivers.
+
+Just like the query and result cache we need to configure it
+first.
+
+.. code-block:: php
+
+    <?php
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
+        '/path/to/writable/directory'
+    );
+    $config = new \Doctrine\ORM\Configuration();
+    $config->setMetadataCacheImpl($cacheDriver);
+
+Now the metadata information will only be parsed once and stored in
+the cache driver.
+
+Clearing the Cache
+------------------
+
+We've already shown you how you can use the API of the
+cache drivers to manually delete cache entries. For your
+convenience we offer command line tasks to help you with
+clearing the query, result and metadata cache.
+
+From the Doctrine command line you can run the following commands:
+
+To clear the query cache use the ``orm:clear-cache:query`` task.
+
+.. code-block:: php
+
+    $ ./doctrine orm:clear-cache:query
+
+To clear the metadata cache use the ``orm:clear-cache:metadata`` task.
+
+.. code-block:: php
+
+    $ ./doctrine orm:clear-cache:metadata
+
+To clear the result cache use the ``orm:clear-cache:result`` task.
+
+.. code-block:: php
+
+    $ ./doctrine orm:clear-cache:result
+
+All these tasks accept a ``--flush`` option to flush the entire
+contents of the cache instead of invalidating the entries.
+
+.. note::
+
+    None of these tasks will work with APC, APCu, or XCache drivers
+    because the memory that the cache is stored in is only accessible
+    to the webserver.
+
+Cache Chaining
+--------------
+
+A common pattern is to use a static cache to store data that is
+requested many times in a single PHP request. Even though this data
+may be stored in a fast memory cache, often that cache is over a
+network link leading to sizable network traffic.
+
+The ChainCache class allows multiple caches to be registered at once.
+For example, a per-request ArrayCache can be used first, followed by
+a (relatively) slower MemcacheCache if the ArrayCache misses.
+ChainCache automatically handles pushing data up to faster caches in
+the chain and clearing data in the entire stack when it is deleted.
+
+A ChainCache takes a simple array of CacheProviders in the order that
+they should be used.
+
+.. code-block:: php
+
+    $arrayCache = new \Doctrine\Common\Cache\ArrayCache();
+    $memcache = new Memcache();
+    $memcache->connect('memcache_host', 11211);
+    $chainCache = new \Doctrine\Common\Cache\ChainCache([
+        $arrayCache,
+        $memcache,
+    ]);
+
+ChainCache itself extends the CacheProvider interface, so it is
+possible to create chains of chains. While this may seem like an easy
+way to build a simple high-availability cache, ChainCache does not
+implement any exception handling so using it as a high-availability
+mechanism is not recommended.
+
+Cache Slams
+-----------
+
+Something to be careful of when using the cache drivers is
+"cache slams". Imagine you have a heavily trafficked website with some
+code that checks for the existence of a cache record and if it does
+not exist it generates the information and saves it to the cache.
+Now, if 100 requests were issued all at the same time and each one
+sees the cache does not exist and they all try to insert the same
+cache entry it could lock up APC, Xcache, etc. and cause problems.
+Ways exist to work around this, like pre-populating your cache and
+not letting your users' requests populate the cache.
+
+You can read more about cache slams
+`in this blog post <http://notmysock.org/blog/php/user-cache-timebomb.html>`_.
+
+

vendor/doctrine/orm/docs/en/reference/change-tracking-policies.rst

@@ -0,0 +1,151 @@
+Change Tracking Policies
+========================
+
+Change tracking is the process of determining what has changed in
+managed entities since the last time they were synchronized with
+the database.
+
+Doctrine provides 3 different change tracking policies, each having
+its particular advantages and disadvantages. The change tracking
+policy can be defined on a per-class basis (or more precisely,
+per-hierarchy).
+
+Deferred Implicit
+~~~~~~~~~~~~~~~~~
+
+The deferred implicit policy is the default change tracking policy
+and the most convenient one. With this policy, Doctrine detects the
+changes by a property-by-property comparison at commit time and
+also detects changes to entities or new entities that are
+referenced by other managed entities ("persistence by
+reachability"). Although the most convenient policy, it can have
+negative effects on performance if you are dealing with large units
+of work (see "Understanding the Unit of Work"). Since Doctrine
+can't know what has changed, it needs to check all managed entities
+for changes every time you invoke EntityManager#flush(), making
+this operation rather costly.
+
+Deferred Explicit
+~~~~~~~~~~~~~~~~~
+
+The deferred explicit policy is similar to the deferred implicit
+policy in that it detects changes through a property-by-property
+comparison at commit time. The difference is that Doctrine 2 only
+considers entities that have been explicitly marked for change detection
+through a call to EntityManager#persist(entity) or through a save
+cascade. All other entities are skipped. This policy therefore
+gives improved performance for larger units of work while
+sacrificing the behavior of "automatic dirty checking".
+
+Therefore, flush() operations are potentially cheaper with this
+policy. The negative aspect this has is that if you have a rather
+large application and you pass your objects through several layers
+for processing purposes and business tasks you may need to track
+yourself which entities have changed on the way so you can pass
+them to EntityManager#persist().
+
+This policy can be configured as follows:
+
+.. code-block:: php
+
+    <?php
+    /**
+     * @Entity
+     * @ChangeTrackingPolicy("DEFERRED_EXPLICIT")
+     */
+    class User
+    {
+        // ...
+    }
+
+Notify
+~~~~~~
+
+This policy is based on the assumption that the entities notify
+interested listeners of changes to their properties. For that
+purpose, a class that wants to use this policy needs to implement
+the ``NotifyPropertyChanged`` interface from the Doctrine
+namespace. As a guideline, such an implementation can look as
+follows:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\Persistence\NotifyPropertyChanged,
+        Doctrine\Persistence\PropertyChangedListener;
+    
+    /**
+     * @Entity
+     * @ChangeTrackingPolicy("NOTIFY")
+     */
+    class MyEntity implements NotifyPropertyChanged
+    {
+        // ...
+    
+        private $_listeners = array();
+    
+        public function addPropertyChangedListener(PropertyChangedListener $listener)
+        {
+            $this->_listeners[] = $listener;
+        }
+    }
+
+Then, in each property setter of this class or derived classes, you
+need to notify all the ``PropertyChangedListener`` instances. As an
+example we add a convenience method on ``MyEntity`` that shows this
+behaviour:
+
+.. code-block:: php
+
+    <?php
+    // ...
+    
+    class MyEntity implements NotifyPropertyChanged
+    {
+        // ...
+    
+        protected function _onPropertyChanged($propName, $oldValue, $newValue)
+        {
+            if ($this->_listeners) {
+                foreach ($this->_listeners as $listener) {
+                    $listener->propertyChanged($this, $propName, $oldValue, $newValue);
+                }
+            }
+        }
+    
+        public function setData($data)
+        {
+            if ($data != $this->data) {
+                $this->_onPropertyChanged('data', $this->data, $data);
+                $this->data = $data;
+            }
+        }
+    }
+
+You have to invoke ``_onPropertyChanged`` inside every method that
+changes the persistent state of ``MyEntity``.
+
+The check whether the new value is different from the old one is
+not mandatory but recommended. That way you also have full control
+over when you consider a property changed.
+
+The negative point of this policy is obvious: You need implement an
+interface and write some plumbing code. But also note that we tried
+hard to keep this notification functionality abstract. Strictly
+speaking, it has nothing to do with the persistence layer and the
+Doctrine ORM or DBAL. You may find that property notification
+events come in handy in many other scenarios as well. As mentioned
+earlier, the ``Doctrine\Common`` namespace is not that evil and
+consists solely of very small classes and interfaces that have
+almost no external dependencies (none to the DBAL and none to the
+ORM) and that you can easily take with you should you want to swap
+out the persistence layer. This change tracking policy does not
+introduce a dependency on the Doctrine DBAL/ORM or the persistence
+layer.
+
+The positive point and main advantage of this policy is its
+effectiveness. It has the best performance characteristics of the 3
+policies with larger units of work and a flush() operation is very
+cheap when nothing has changed.
+
+

vendor/doctrine/orm/docs/en/reference/configuration.rst

@@ -0,0 +1,144 @@
+Installation and Configuration
+==============================
+
+Doctrine can be installed with `Composer <https://getcomposer.org>`_.
+
+Define the following requirement in your ``composer.json`` file:
+
+::
+
+    {
+        "require": {
+            "doctrine/orm": "*"
+        }
+    }
+
+Then call ``composer install`` from your command line. If you don't know
+how Composer works, check out their `Getting Started <https://getcomposer.org/doc/00-intro.md>`_ to set up.
+
+Class loading
+-------------
+
+Autoloading is taken care of by Composer. You just have to include the composer autoload file in your project:
+
+.. code-block:: php
+
+    <?php
+    // bootstrap.php
+    // Include Composer Autoload (relative to project root).
+    require_once "vendor/autoload.php";
+
+Obtaining an EntityManager
+--------------------------
+
+Once you have prepared the class loading, you acquire an
+*EntityManager* instance. The EntityManager class is the primary
+access point to ORM functionality provided by Doctrine.
+
+.. code-block:: php
+
+    <?php
+    // bootstrap.php
+    require_once "vendor/autoload.php";
+
+    use Doctrine\ORM\Tools\Setup;
+    use Doctrine\ORM\EntityManager;
+
+    $paths = array("/path/to/entity-files");
+    $isDevMode = false;
+
+    // the connection configuration
+    $dbParams = array(
+        'driver'   => 'pdo_mysql',
+        'user'     => 'root',
+        'password' => '',
+        'dbname'   => 'foo',
+    );
+
+    $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode);
+    $entityManager = EntityManager::create($dbParams, $config);
+
+Or if you prefer XML:
+
+.. code-block:: php
+
+    <?php
+    $paths = array("/path/to/xml-mappings");
+    $config = Setup::createXMLMetadataConfiguration($paths, $isDevMode);
+    $entityManager = EntityManager::create($dbParams, $config);
+
+Or if you prefer YAML:
+
+.. code-block:: php
+
+    <?php
+    $paths = array("/path/to/yml-mappings");
+    $config = Setup::createYAMLMetadataConfiguration($paths, $isDevMode);
+    $entityManager = EntityManager::create($dbParams, $config);
+
+.. note::
+    If you want to use yml mapping you should add yaml dependency to your `composer.json`:
+    
+    ::
+    
+        "symfony/yaml": "*"
+
+Inside the ``Setup`` methods several assumptions are made:
+
+-  If `$isDevMode` is true caching is done in memory with the ``ArrayCache``. Proxy objects are recreated on every request.
+-  If `$isDevMode` is false, check for Caches in the order APC, Xcache, Memcache (127.0.0.1:11211), Redis (127.0.0.1:6379) unless `$cache` is passed as fourth argument.
+-  If `$isDevMode` is false, set then proxy classes have to be explicitly created through the command line.
+-  If third argument `$proxyDir` is not set, use the systems temporary directory.
+
+If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration <reference/advanced-configuration>` section.
+
+.. note::
+
+    You can learn more about the database connection configuration in the
+    `Doctrine DBAL connection configuration reference <http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html>`_.
+
+Setting up the Commandline Tool
+-------------------------------
+
+Doctrine ships with a number of command line tools that are very helpful
+during development. You can call this command from the Composer binary
+directory:
+
+.. code-block:: sh
+
+    $ php vendor/bin/doctrine
+
+You need to register your applications EntityManager to the console tool
+to make use of the tasks by creating a ``cli-config.php`` file with the
+following content:
+
+On Doctrine 2.4 and above:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Tools\Console\ConsoleRunner;
+
+    // replace with file to your own project bootstrap
+    require_once 'bootstrap.php';
+
+    // replace with mechanism to retrieve EntityManager in your app
+    $entityManager = GetEntityManager();
+
+    return ConsoleRunner::createHelperSet($entityManager);
+
+On Doctrine 2.3 and below:
+
+.. code-block:: php
+
+    <?php
+    // cli-config.php
+    require_once 'my_bootstrap.php';
+
+    // Any way to access the EntityManager from  your application
+    $em = GetMyEntityManager();
+
+    $helperSet = new \Symfony\Component\Console\Helper\HelperSet(array(
+        'db' => new \Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper($em->getConnection()),
+        'em' => new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($em)
+    ));

vendor/doctrine/orm/docs/en/reference/events.rst

@@ -0,0 +1,997 @@
+Events
+======
+
+Doctrine 2 features a lightweight event system that is part of the
+Common package. Doctrine uses it to dispatch system events, mainly
+:ref:`lifecycle events <reference-events-lifecycle-events>`.
+You can also use it for your own custom events.
+
+The Event System
+----------------
+
+The event system is controlled by the ``EventManager``. It is the
+central point of Doctrine's event listener system. Listeners are
+registered on the manager and events are dispatched through the
+manager.
+
+.. code-block:: php
+
+    <?php
+    $evm = new EventManager();
+
+Now we can add some event listeners to the ``$evm``. Let's create a
+``TestEvent`` class to play around with.
+
+.. code-block:: php
+
+    <?php
+    class TestEvent
+    {
+        const preFoo = 'preFoo';
+        const postFoo = 'postFoo';
+
+        private $_evm;
+
+        public $preFooInvoked = false;
+        public $postFooInvoked = false;
+
+        public function __construct($evm)
+        {
+            $evm->addEventListener(array(self::preFoo, self::postFoo), $this);
+        }
+
+        public function preFoo(EventArgs $e)
+        {
+            $this->preFooInvoked = true;
+        }
+
+        public function postFoo(EventArgs $e)
+        {
+            $this->postFooInvoked = true;
+        }
+    }
+
+    // Create a new instance
+    $test = new TestEvent($evm);
+
+Events can be dispatched by using the ``dispatchEvent()`` method.
+
+.. code-block:: php
+
+    <?php
+    $evm->dispatchEvent(TestEvent::preFoo);
+    $evm->dispatchEvent(TestEvent::postFoo);
+
+You can easily remove a listener with the ``removeEventListener()``
+method.
+
+.. code-block:: php
+
+    <?php
+    $evm->removeEventListener(array(self::preFoo, self::postFoo), $this);
+
+The Doctrine 2 event system also has a simple concept of event
+subscribers. We can define a simple ``TestEventSubscriber`` class
+which implements the ``\Doctrine\Common\EventSubscriber`` interface
+and implements a ``getSubscribedEvents()`` method which returns an
+array of events it should be subscribed to.
+
+.. code-block:: php
+
+    <?php
+    class TestEventSubscriber implements \Doctrine\Common\EventSubscriber
+    {
+        public $preFooInvoked = false;
+
+        public function preFoo()
+        {
+            $this->preFooInvoked = true;
+        }
+
+        public function getSubscribedEvents()
+        {
+            return array(TestEvent::preFoo);
+        }
+    }
+
+    $eventSubscriber = new TestEventSubscriber();
+    $evm->addEventSubscriber($eventSubscriber);
+
+.. note::
+
+    The array to return in the ``getSubscribedEvents`` method is a simple array
+    with the values being the event names. The subscriber must have a method
+    that is named exactly like the event.
+
+Now when you dispatch an event, any event subscribers will be
+notified for that event.
+
+.. code-block:: php
+
+    <?php
+    $evm->dispatchEvent(TestEvent::preFoo);
+
+Now you can test the ``$eventSubscriber`` instance to see if the
+``preFoo()`` method was invoked.
+
+.. code-block:: php
+
+    <?php
+    if ($eventSubscriber->preFooInvoked) {
+        echo 'pre foo invoked!';
+    }
+
+Naming convention
+~~~~~~~~~~~~~~~~~
+
+Events being used with the Doctrine 2 EventManager are best named
+with camelcase and the value of the corresponding constant should
+be the name of the constant itself, even with spelling. This has
+several reasons:
+
+
+-  It is easy to read.
+-  Simplicity.
+-  Each method within an EventSubscriber is named after the
+   corresponding constant's value. If the constant's name and value differ
+   it contradicts the intention of using the constant and makes your code
+   harder to maintain.
+
+An example for a correct notation can be found in the example
+``TestEvent`` above.
+
+.. _reference-events-lifecycle-events:
+
+Lifecycle Events
+----------------
+
+The ``EntityManager`` and ``UnitOfWork`` classes trigger a bunch of
+events during the life-time of their registered entities.
+
+
+
+-  ``preRemove`` - The ``preRemove`` event occurs for a given entity
+   before the respective ``EntityManager`` remove operation for that
+   entity is executed.  It is not called for a DQL ``DELETE`` statement.
+-  ``postRemove`` - The ``postRemove`` event occurs for an entity after the
+   entity has been deleted. It will be invoked after the database
+   delete operations. It is not called for a DQL ``DELETE`` statement.
+-  ``prePersist`` - The ``prePersist`` event occurs for a given entity
+   before the respective ``EntityManager`` persist operation for that
+   entity is executed. It should be noted that this event is only triggered on
+   *initial* persist of an entity (i.e. it does not trigger on future updates).
+-  ``postPersist`` - The ``postPersist`` event occurs for an entity after
+   the entity has been made persistent. It will be invoked after the
+   database insert operations. Generated primary key values are
+   available in the postPersist event.
+-  ``preUpdate`` - The ``preUpdate`` event occurs before the database
+   update operations to entity data. It is not called for a DQL
+   ``UPDATE`` statement nor when the computed changeset is empty.
+-  ``postUpdate`` - The ``postUpdate`` event occurs after the database
+   update operations to entity data. It is not called for a DQL
+   ``UPDATE`` statement.
+-  ``postLoad`` - The postLoad event occurs for an entity after the
+   entity has been loaded into the current ``EntityManager`` from the
+   database or after the refresh operation has been applied to it.
+-  ``loadClassMetadata`` - The ``loadClassMetadata`` event occurs after the
+   mapping metadata for a class has been loaded from a mapping source
+   (annotations/xml/yaml). This event is not a lifecycle callback.
+-  ``onClassMetadataNotFound`` - Loading class metadata for a particular
+   requested class name failed. Manipulating the given event args instance
+   allows providing fallback metadata even when no actual metadata exists
+   or could be found. This event is not a lifecycle callback.
+-  ``preFlush`` - The ``preFlush`` event occurs at the very beginning of
+   a flush operation.
+-  ``onFlush`` - The ``onFlush`` event occurs after the change-sets of all
+   managed entities are computed. This event is not a lifecycle
+   callback.
+-  ``postFlush`` - The ``postFlush`` event occurs at the end of a flush operation. This
+   event is not a lifecycle callback.
+-  ``onClear`` - The ``onClear`` event occurs when the
+   ``EntityManager#clear()`` operation is invoked, after all references
+   to entities have been removed from the unit of work. This event is not
+   a lifecycle callback.
+
+
+.. warning::
+
+    Note that, when using ``Doctrine\ORM\AbstractQuery#iterate()``, ``postLoad``
+    events will be executed immediately after objects are being hydrated, and therefore
+    associations are not guaranteed to be initialized. It is not safe to combine
+    usage of ``Doctrine\ORM\AbstractQuery#iterate()`` and ``postLoad`` event
+    handlers.
+
+.. warning::
+
+    Note that the ``postRemove`` event or any events triggered after an entity removal
+    can receive an uninitializable proxy in case you have configured an entity to
+    cascade remove relations. In this case, you should load yourself the proxy in
+    the associated pre event.
+
+You can access the Event constants from the ``Events`` class in the
+ORM package.
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Events;
+    echo Events::preUpdate;
+
+These can be hooked into by two different types of event
+listeners:
+
+-  Lifecycle Callbacks are methods on the entity classes that are
+   called when the event is triggered. As of v2.4 they receive some kind
+   of ``EventArgs`` instance.
+-  Lifecycle Event Listeners and Subscribers are classes with specific callback
+   methods that receives some kind of ``EventArgs`` instance.
+
+The ``EventArgs`` instance received by the listener gives access to the entity,
+``EntityManager`` instance and other relevant data.
+
+.. note::
+
+    All Lifecycle events that happen during the ``flush()`` of
+    an ``EntityManager`` have very specific constraints on the allowed
+    operations that can be executed. Please read the
+    :ref:`reference-events-implementing-listeners` section very carefully
+    to understand which operations are allowed in which lifecycle event.
+
+
+Lifecycle Callbacks
+-------------------
+
+Lifecycle Callbacks are defined on an entity class. They allow you to
+trigger callbacks whenever an instance of that entity class experiences
+a relevant lifecycle event. More than one callback can be defined for each
+lifecycle event. Lifecycle Callbacks are best used for simple operations
+specific to a particular entity class's lifecycle.
+
+
+.. note::
+
+    Note that Licecycle Callbacks are not supported for Embeddables.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Entity @HasLifecycleCallbacks */
+    class User
+    {
+        // ...
+
+        /**
+         * @Column(type="string", length=255)
+         */
+        public $value;
+
+        /** @Column(name="created_at", type="string", length=255) */
+        private $createdAt;
+
+        /** @PrePersist */
+        public function doStuffOnPrePersist()
+        {
+            $this->createdAt = date('Y-m-d H:i:s');
+        }
+
+        /** @PrePersist */
+        public function doOtherStuffOnPrePersist()
+        {
+            $this->value = 'changed from prePersist callback!';
+        }
+
+        /** @PostPersist */
+        public function doStuffOnPostPersist()
+        {
+            $this->value = 'changed from postPersist callback!';
+        }
+
+        /** @PostLoad */
+        public function doStuffOnPostLoad()
+        {
+            $this->value = 'changed from postLoad callback!';
+        }
+
+        /** @PreUpdate */
+        public function doStuffOnPreUpdate()
+        {
+            $this->value = 'changed from preUpdate callback!';
+        }
+    }
+
+Note that the methods set as lifecycle callbacks need to be public and,
+when using these annotations, you have to apply the
+``@HasLifecycleCallbacks`` marker annotation on the entity class.
+
+If you want to register lifecycle callbacks from YAML or XML you
+can do it with the following.
+
+.. code-block:: yaml
+
+    User:
+      type: entity
+      fields:
+    # ...
+        name:
+          type: string(50)
+      lifecycleCallbacks:
+        prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersist ]
+        postPersist: [ doStuffOnPostPersist ]
+
+In YAML the ``key`` of the lifecycleCallbacks entry is the event that you
+are triggering on and the value is the method (or methods) to call. The allowed
+event types are the ones listed in the previous Lifecycle Events section.
+
+XML would look something like this:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8"?>
+
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
+        <entity name="User">
+
+            <lifecycle-callbacks>
+                <lifecycle-callback type="prePersist" method="doStuffOnPrePersist"/>
+                <lifecycle-callback type="postPersist" method="doStuffOnPostPersist"/>
+            </lifecycle-callbacks>
+
+        </entity>
+
+    </doctrine-mapping>
+
+In XML the ``type`` of the lifecycle-callback entry is the event that you
+are triggering on and the ``method`` is the method to call. The allowed event
+types are the ones listed in the previous Lifecycle Events section.
+
+When using YAML or XML you need to remember to create public methods to match the
+callback names you defined. E.g. in these examples ``doStuffOnPrePersist()``,
+``doOtherStuffOnPrePersist()`` and ``doStuffOnPostPersist()`` methods need to be
+defined on your ``User`` model.
+
+.. code-block:: php
+
+    <?php
+    // ...
+
+    class User
+    {
+        // ...
+
+        public function doStuffOnPrePersist()
+        {
+            // ...
+        }
+
+        public function doOtherStuffOnPrePersist()
+        {
+            // ...
+        }
+
+        public function doStuffOnPostPersist()
+        {
+            // ...
+        }
+    }
+
+
+Lifecycle Callbacks Event Argument
+-----------------------------------
+
+.. versionadded:: 2.4
+
+Since 2.4 the triggered event is given to the lifecycle-callback.
+
+With the additional argument you have access to the
+``EntityManager`` and ``UnitOfWork`` APIs inside these callback methods.
+
+.. code-block:: php
+
+    <?php
+    // ...
+
+    class User
+    {
+        public function preUpdate(PreUpdateEventArgs $event)
+        {
+            if ($event->hasChangedField('username')) {
+                // Do something when the username is changed.
+            }
+        }
+    }
+
+Listening and subscribing to Lifecycle Events
+---------------------------------------------
+
+Lifecycle event listeners are much more powerful than the simple
+lifecycle callbacks that are defined on the entity classes. They
+sit at a level above the entities and allow you to implement re-usable
+behaviors across different entity classes.
+
+Note that they require much more detailed knowledge about the inner
+workings of the ``EntityManager`` and ``UnitOfWork`` classes. Please
+read the :ref:`reference-events-implementing-listeners` section
+carefully if you are trying to write your own listener.
+
+For event subscribers, there are no surprises. They declare the
+lifecycle events in their ``getSubscribedEvents`` method and provide
+public methods that expect the relevant arguments.
+
+A lifecycle event listener looks like the following:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\Persistence\Event\LifecycleEventArgs;
+
+    class MyEventListener
+    {
+        public function preUpdate(LifecycleEventArgs $args)
+        {
+            $entity = $args->getObject();
+            $entityManager = $args->getObjectManager();
+
+            // perhaps you only want to act on some "Product" entity
+            if ($entity instanceof Product) {
+                // do something with the Product
+            }
+        }
+    }
+
+A lifecycle event subscriber may look like this:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Events;
+    use Doctrine\EventSubscriber;
+    use Doctrine\Persistence\Event\LifecycleEventArgs;
+
+    class MyEventSubscriber implements EventSubscriber
+    {
+        public function getSubscribedEvents()
+        {
+            return array(
+                Events::postUpdate,
+            );
+        }
+
+        public function postUpdate(LifecycleEventArgs $args)
+        {
+            $entity = $args->getObject();
+            $entityManager = $args->getObjectManager();
+
+            // perhaps you only want to act on some "Product" entity
+            if ($entity instanceof Product) {
+                // do something with the Product
+            }
+        }
+
+.. note::
+
+    Lifecycle events are triggered for all entities. It is the responsibility
+    of the listeners and subscribers to check if the entity is of a type
+    it wants to handle.
+
+To register an event listener or subscriber, you have to hook it into the
+EventManager that is passed to the EntityManager factory:
+
+.. code-block:: php
+
+    <?php
+    $eventManager = new EventManager();
+    $eventManager->addEventListener(array(Events::preUpdate), new MyEventListener());
+    $eventManager->addEventSubscriber(new MyEventSubscriber());
+
+    $entityManager = EntityManager::create($dbOpts, $config, $eventManager);
+
+You can also retrieve the event manager instance after the
+EntityManager was created:
+
+.. code-block:: php
+
+    <?php
+    $entityManager->getEventManager()->addEventListener(array(Events::preUpdate), new MyEventListener());
+    $entityManager->getEventManager()->addEventSubscriber(new MyEventSubscriber());
+
+.. _reference-events-implementing-listeners:
+
+Implementing Event Listeners
+----------------------------
+
+This section explains what is and what is not allowed during
+specific lifecycle events of the ``UnitOfWork`` class. Although you get
+passed the ``EntityManager`` instance in all of these events, you have
+to follow these restrictions very carefully since operations in the
+wrong event may produce lots of different errors, such as inconsistent
+data and lost updates/persists/removes.
+
+For the described events that are also lifecycle callback events
+the restrictions apply as well, with the additional restriction
+that (prior to version 2.4) you do not have access to the
+``EntityManager`` or ``UnitOfWork`` APIs inside these events.
+
+prePersist
+~~~~~~~~~~
+
+There are two ways for the ``prePersist`` event to be triggered.
+One is obviously when you call ``EntityManager#persist()``. The
+event is also called for all cascaded associations.
+
+There is another way for ``prePersist`` to be called, inside the
+``flush()`` method when changes to associations are computed and
+this association is marked as cascade persist. Any new entity found
+during this operation is also persisted and ``prePersist`` called
+on it. This is called "persistence by reachability".
+
+In both cases you get passed a ``LifecycleEventArgs`` instance
+which has access to the entity and the entity manager.
+
+The following restrictions apply to ``prePersist``:
+
+
+-  If you are using a PrePersist Identity Generator such as
+   sequences the ID value will *NOT* be available within any
+   PrePersist events.
+-  Doctrine will not recognize changes made to relations in a prePersist
+   event. This includes modifications to
+   collections such as additions, removals or replacement.
+
+preRemove
+~~~~~~~~~
+
+The ``preRemove`` event is called on every entity when its passed
+to the ``EntityManager#remove()`` method. It is cascaded for all
+associations that are marked as cascade delete.
+
+There are no restrictions to what methods can be called inside the
+``preRemove`` event, except when the remove method itself was
+called during a flush operation.
+
+preFlush
+~~~~~~~~
+
+``preFlush`` is called at ``EntityManager#flush()`` before
+anything else. ``EntityManager#flush()`` should not be called inside
+its listeners, since `preFlush` event is dispatched in it, which would
+result in infinite loop.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\ORM\Event\PreFlushEventArgs;
+
+    class PreFlushExampleListener
+    {
+        public function preFlush(PreFlushEventArgs $args)
+        {
+            // ...
+        }
+    }
+
+onFlush
+~~~~~~~
+
+OnFlush is a very powerful event. It is called inside
+``EntityManager#flush()`` after the changes to all the managed
+entities and their associations have been computed. This means, the
+``onFlush`` event has access to the sets of:
+
+
+-  Entities scheduled for insert
+-  Entities scheduled for update
+-  Entities scheduled for removal
+-  Collections scheduled for update
+-  Collections scheduled for removal
+
+To make use of the ``onFlush`` event you have to be familiar with the
+internal ``UnitOfWork`` API, which grants you access to the previously
+mentioned sets. See this example:
+
+.. code-block:: php
+
+    <?php
+    class FlushExampleListener
+    {
+        public function onFlush(OnFlushEventArgs $eventArgs)
+        {
+            $em = $eventArgs->getEntityManager();
+            $uow = $em->getUnitOfWork();
+
+            foreach ($uow->getScheduledEntityInsertions() as $entity) {
+
+            }
+
+            foreach ($uow->getScheduledEntityUpdates() as $entity) {
+
+            }
+
+            foreach ($uow->getScheduledEntityDeletions() as $entity) {
+
+            }
+
+            foreach ($uow->getScheduledCollectionDeletions() as $col) {
+
+            }
+
+            foreach ($uow->getScheduledCollectionUpdates() as $col) {
+
+            }
+        }
+    }
+
+The following restrictions apply to the onFlush event:
+
+
+-  If you create and persist a new entity in ``onFlush``, then
+   calling ``EntityManager#persist()`` is not enough.
+   You have to execute an additional call to
+   ``$unitOfWork->computeChangeSet($classMetadata, $entity)``.
+-  Changing primitive fields or associations requires you to
+   explicitly trigger a re-computation of the changeset of the
+   affected entity. This can be done by calling
+   ``$unitOfWork->recomputeSingleEntityChangeSet($classMetadata, $entity)``.
+
+postFlush
+~~~~~~~~~
+
+``postFlush`` is called at the end of ``EntityManager#flush()``.
+``EntityManager#flush()`` can **NOT** be called safely inside its listeners.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\ORM\Event\PostFlushEventArgs;
+
+    class PostFlushExampleListener
+    {
+        public function postFlush(PostFlushEventArgs $args)
+        {
+            // ...
+        }
+    }
+
+preUpdate
+~~~~~~~~~
+
+PreUpdate is the most restrictive to use event, since it is called
+right before an update statement is called for an entity inside the
+``EntityManager#flush()`` method. Note that this event is not
+triggered when the computed changeset is empty.
+
+Changes to associations of the updated entity are never allowed in
+this event, since Doctrine cannot guarantee to correctly handle
+referential integrity at this point of the flush operation. This
+event has a powerful feature however, it is executed with a
+``PreUpdateEventArgs`` instance, which contains a reference to the
+computed change-set of this entity.
+
+This means you have access to all the fields that have changed for
+this entity with their old and new value. The following methods are
+available on the ``PreUpdateEventArgs``:
+
+
+-  ``getEntity()`` to get access to the actual entity.
+-  ``getEntityChangeSet()`` to get a copy of the changeset array.
+   Changes to this returned array do not affect updating.
+-  ``hasChangedField($fieldName)`` to check if the given field name
+   of the current entity changed.
+-  ``getOldValue($fieldName)`` and ``getNewValue($fieldName)`` to
+   access the values of a field.
+-  ``setNewValue($fieldName, $value)`` to change the value of a
+   field to be updated.
+
+A simple example for this event looks like:
+
+.. code-block:: php
+
+    <?php
+    class NeverAliceOnlyBobListener
+    {
+        public function preUpdate(PreUpdateEventArgs $eventArgs)
+        {
+            if ($eventArgs->getEntity() instanceof User) {
+                if ($eventArgs->hasChangedField('name') && $eventArgs->getNewValue('name') == 'Alice') {
+                    $eventArgs->setNewValue('name', 'Bob');
+                }
+            }
+        }
+    }
+
+You could also use this listener to implement validation of all the
+fields that have changed. This is more efficient than using a
+lifecycle callback when there are expensive validations to call:
+
+.. code-block:: php
+
+    <?php
+    class ValidCreditCardListener
+    {
+        public function preUpdate(PreUpdateEventArgs $eventArgs)
+        {
+            if ($eventArgs->getEntity() instanceof Account) {
+                if ($eventArgs->hasChangedField('creditCard')) {
+                    $this->validateCreditCard($eventArgs->getNewValue('creditCard'));
+                }
+            }
+        }
+
+        private function validateCreditCard($no)
+        {
+            // throw an exception to interrupt flush event. Transaction will be rolled back.
+        }
+    }
+
+Restrictions for this event:
+
+
+-  Changes to associations of the passed entities are not
+   recognized by the flush operation anymore.
+-  Changes to fields of the passed entities are not recognized by
+   the flush operation anymore, use the computed change-set passed to
+   the event to modify primitive field values, e.g. use
+   ``$eventArgs->setNewValue($field, $value);`` as in the Alice to Bob example above.
+-  Any calls to ``EntityManager#persist()`` or
+   ``EntityManager#remove()``, even in combination with the ``UnitOfWork``
+   API are strongly discouraged and don't work as expected outside the
+   flush operation.
+
+postUpdate, postRemove, postPersist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The three post events are called inside ``EntityManager#flush()``.
+Changes in here are not relevant to the persistence in the
+database, but you can use these events to alter non-persistable items,
+like non-mapped fields, logging or even associated classes that are
+not directly mapped by Doctrine.
+
+postLoad
+~~~~~~~~
+
+This event is called after an entity is constructed by the
+EntityManager.
+
+Entity listeners
+----------------
+
+.. versionadded:: 2.4
+
+An entity listener is a lifecycle listener class used for an entity.
+
+- The entity listener's mapping may be applied to an entity class or mapped superclass.
+- An entity listener is defined by mapping the entity class with the corresponding mapping.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Entity;
+
+        /** @Entity @EntityListeners({"UserListener"}) */
+        class User
+        {
+            // ....
+        }
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Entity\User">
+                <entity-listeners>
+                    <entity-listener class="UserListener"/>
+                </entity-listeners>
+                <!-- .... -->
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Entity\User:
+          type: entity
+          entityListeners:
+            UserListener:
+          # ....
+
+.. _reference-entity-listeners:
+
+Entity listeners class
+~~~~~~~~~~~~~~~~~~~~~~
+
+An ``Entity Listener`` could be any class, by default it should be a class with a no-arg constructor.
+
+- Different from :ref:`reference-events-implementing-listeners` an ``Entity Listener`` is invoked just to the specified entity
+- An entity listener method receives two arguments, the entity instance and the lifecycle event.
+- The callback method can be defined by naming convention or specifying a method mapping.
+- When a listener mapping is not given the parser will use the naming convention to look for a matching method,
+  e.g. it will look for a public ``preUpdate()`` method if you are listening to the ``preUpdate`` event.
+- When a listener mapping is given the parser will not look for any methods using the naming convention.
+
+.. code-block:: php
+
+    <?php
+    class UserListener
+    {
+        public function preUpdate(User $user, PreUpdateEventArgs $event)
+        {
+            // Do something on pre update.
+        }
+    }
+
+To define a specific event listener method (one that does not follow the naming convention)
+you need to map the listener method using the event type mapping:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        class UserListener
+        {
+            /** @PrePersist */
+            public function prePersistHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+            /** @PostPersist */
+            public function postPersistHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+            /** @PreUpdate */
+            public function preUpdateHandler(User $user, PreUpdateEventArgs $event) { // ... }
+
+            /** @PostUpdate */
+            public function postUpdateHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+            /** @PostRemove */
+            public function postRemoveHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+            /** @PreRemove */
+            public function preRemoveHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+            /** @PreFlush */
+            public function preFlushHandler(User $user, PreFlushEventArgs $event) { // ... }
+
+            /** @PostLoad */
+            public function postLoadHandler(User $user, LifecycleEventArgs $event) { // ... }
+        }
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Entity\User">
+                 <entity-listeners>
+                    <entity-listener class="UserListener">
+                        <lifecycle-callback type="preFlush"      method="preFlushHandler"/>
+                        <lifecycle-callback type="postLoad"      method="postLoadHandler"/>
+
+                        <lifecycle-callback type="postPersist"   method="postPersistHandler"/>
+                        <lifecycle-callback type="prePersist"    method="prePersistHandler"/>
+
+                        <lifecycle-callback type="postUpdate"    method="postUpdateHandler"/>
+                        <lifecycle-callback type="preUpdate"     method="preUpdateHandler"/>
+
+                        <lifecycle-callback type="postRemove"    method="postRemoveHandler"/>
+                        <lifecycle-callback type="preRemove"     method="preRemoveHandler"/>
+                    </entity-listener>
+                </entity-listeners>
+                <!-- .... -->
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Entity\User:
+          type: entity
+          entityListeners:
+            UserListener:
+              preFlush: [preFlushHandler]
+              postLoad: [postLoadHandler]
+
+              postPersist: [postPersistHandler]
+              prePersist: [prePersistHandler]
+
+              postUpdate: [postUpdateHandler]
+              preUpdate: [preUpdateHandler]
+
+              postRemove: [postRemoveHandler]
+              preRemove: [preRemoveHandler]
+          # ....
+
+.. note::
+
+    The order of execution of multiple methods for the same event (e.g. multiple @PrePersist) is not guaranteed.
+
+
+Entity listeners resolver
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Doctrine invokes the listener resolver to get the listener instance.
+
+- A resolver allows you register a specific entity listener instance.
+- You can also implement your own resolver by extending ``Doctrine\ORM\Mapping\DefaultEntityListenerResolver`` or implementing ``Doctrine\ORM\Mapping\EntityListenerResolver``
+
+Specifying an entity listener instance :
+
+.. code-block:: php
+
+    <?php
+    // User.php
+
+    /** @Entity @EntityListeners({"UserListener"}) */
+    class User
+    {
+        // ....
+    }
+
+    // UserListener.php
+    class UserListener
+    {
+        public function __construct(MyService $service)
+        {
+            $this->service = $service;
+        }
+
+        public function preUpdate(User $user, PreUpdateEventArgs $event)
+        {
+            $this->service->doSomething($user);
+        }
+    }
+
+    // register a entity listener.
+    $listener = $container->get('user_listener');
+    $em->getConfiguration()->getEntityListenerResolver()->register($listener);
+
+Implementing your own resolver :
+
+.. code-block:: php
+
+    <?php
+    class MyEntityListenerResolver extends \Doctrine\ORM\Mapping\DefaultEntityListenerResolver
+    {
+        public function __construct($container)
+        {
+            $this->container = $container;
+        }
+
+        public function resolve($className)
+        {
+            // resolve the service id by the given class name;
+            $id = 'user_listener';
+
+            return $this->container->get($id);
+        }
+    }
+
+    // Configure the listener resolver only before instantiating the EntityManager
+    $configurations->setEntityListenerResolver(new MyEntityListenerResolver);
+    EntityManager::create(.., $configurations, ..);
+
+Load ClassMetadata Event
+------------------------
+
+When the mapping information for an entity is read, it is populated
+in to a ``ClassMetadataInfo`` instance. You can hook in to this
+process and manipulate the instance.
+
+.. code-block:: php
+
+    <?php
+    $test = new TestEvent();
+    $metadataFactory = $em->getMetadataFactory();
+    $evm = $em->getEventManager();
+    $evm->addEventListener(Events::loadClassMetadata, $test);
+
+    class TestEvent
+    {
+        public function loadClassMetadata(\Doctrine\ORM\Event\LoadClassMetadataEventArgs $eventArgs)
+        {
+            $classMetadata = $eventArgs->getClassMetadata();
+            $fieldMapping = array(
+                'fieldName' => 'about',
+                'type' => 'string',
+                'length' => 255
+            );
+            $classMetadata->mapField($fieldMapping);
+        }
+    }
+

vendor/doctrine/orm/docs/en/reference/faq.rst

@@ -0,0 +1,233 @@
+Frequently Asked Questions
+==========================
+
+.. note::
+
+    This FAQ is a work in progress. We will add lots of questions and not answer them right away just to remember
+    what is often asked. If you stumble across an unanswered question please write a mail to the mailing-list or
+    join the #doctrine channel on Freenode IRC.
+
+Database Schema
+---------------
+
+How do I set the charset and collation for MySQL tables?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can't set these values inside the annotations, yml or xml mapping files. To make a database
+work with the default charset and collation you should configure MySQL to use it as default charset,
+or create the database with charset and collation details. This way they get inherited to all newly
+created database tables and columns.
+
+Entity Classes
+--------------
+
+How can I add default values to a column?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Doctrine does not support to set the default values in columns through the "DEFAULT" keyword in SQL.
+This is not necessary however, you can just use your class properties as default values. These are then used
+upon insert:
+
+.. code-block:: php
+
+    class User
+    {
+        const STATUS_DISABLED = 0;
+        const STATUS_ENABLED = 1;
+
+        private $algorithm = "sha1";
+        private $status = self:STATUS_DISABLED;
+    }
+
+.
+
+Mapping
+-------
+
+Why do I get exceptions about unique constraint failures during ``$em->flush()``?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Doctrine does not check if you are re-adding entities with a primary key that already exists
+or adding entities to a collection twice. You have to check for both conditions yourself
+in the code before calling ``$em->flush()`` if you know that unique constraint failures
+can occur.
+
+In `Symfony2 <http://www.symfony.com>`_ for example there is a Unique Entity Validator
+to achieve this task.
+
+For collections you can check with ``$collection->contains($entity)`` if an entity is already
+part of this collection. For a FETCH=LAZY collection this will initialize the collection,
+however for FETCH=EXTRA_LAZY this method will use SQL to determine if this entity is already
+part of the collection.
+
+Associations
+------------
+
+What is wrong when I get an InvalidArgumentException "A new entity was found through the relationship.."?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This exception is thrown during ``EntityManager#flush()`` when there exists an object in the identity map
+that contains a reference to an object that Doctrine does not know about. Say for example you grab
+a "User"-entity from the database with a specific id and set a completely new object into one of the associations
+of the User object. If you then call ``EntityManager#flush()`` without letting Doctrine know about
+this new object using ``EntityManager#persist($newObject)`` you will see this exception.
+
+You can solve this exception by:
+
+* Calling ``EntityManager#persist($newObject)`` on the new object
+* Using cascade=persist on the association that contains the new object
+
+How can I filter an association?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Natively you can't filter associations in 2.0 and 2.1. You should use DQL queries to query for the filtered set of entities.
+
+I call clear() on a One-To-Many collection but the entities are not deleted
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an expected behavior that has to do with the inverse/owning side handling of Doctrine.
+By definition a One-To-Many association is on the inverse side, that means changes to it
+will not be recognized by Doctrine.
+
+If you want to perform the equivalent of the clear operation you have to iterate the
+collection and set the owning side many-to-one reference to NULL as well to detach all entities
+from the collection. This will trigger the appropriate UPDATE statements on the database.
+
+How can I add columns to a many-to-many table?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The many-to-many association is only supporting foreign keys in the table definition
+To work with many-to-many tables containing extra columns you have to use the
+foreign keys as primary keys feature of Doctrine introduced in version 2.1.
+
+See :doc:`the tutorial on composite primary keys for more information<../tutorials/composite-primary-keys>`.
+
+
+How can i paginate fetch-joined collections?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are issuing a DQL statement that fetches a collection as well you cannot easily iterate
+over this collection using a LIMIT statement (or vendor equivalent).
+
+Doctrine does not offer a solution for this out of the box but there are several extensions
+that do:
+
+* `DoctrineExtensions <http://github.com/beberlei/DoctrineExtensions>`_
+* `Pagerfanta <http://github.com/whiteoctober/pagerfanta>`_
+
+Why does pagination not work correctly with fetch joins?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pagination in Doctrine uses a LIMIT clause (or vendor equivalent) to restrict the results.
+However when fetch-joining this is not returning the correct number of results since joining
+with a one-to-many or many-to-many association multiplies the number of rows by the number
+of associated entities.
+
+See the previous question for a solution to this task.
+
+Inheritance
+-----------
+
+Can I use Inheritance with Doctrine 2?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ 
+Yes, you can use Single- or Joined-Table Inheritance in Doctrine 2.
+
+See the documentation chapter on :doc:`inheritance mapping <inheritance-mapping>` for
+the details.
+
+Why does Doctrine not create proxy objects for my inheritance hierarchy?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you set a many-to-one or one-to-one association target-entity to any parent class of
+an inheritance hierarchy Doctrine does not know what PHP class the foreign is actually of.
+To find this out it has to execute a SQL query to look this information up in the database.
+
+EntityGenerator
+---------------
+
+Why does the EntityGenerator not do X?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The EntityGenerator is not a full fledged code-generator that solves all tasks. Code-Generation
+is not a first-class priority in Doctrine 2 anymore (compared to Doctrine 1). The EntityGenerator
+is supposed to kick-start you, but not towards 100%.
+
+Why does the EntityGenerator not generate inheritance correctly?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just from the details of the discriminator map the EntityGenerator cannot guess the inheritance hierarchy.
+This is why the generation of inherited entities does not fully work. You have to adjust some additional
+code to get this one working correctly.
+
+Performance
+-----------
+
+Why is an extra SQL query executed every time I fetch an entity with a one-to-one relation?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If Doctrine detects that you are fetching an inverse side one-to-one association
+it has to execute an additional query to load this object, because it cannot know
+if there is no such object (setting null) or if it should set a proxy and which id this proxy has.
+
+To solve this problem currently a query has to be executed to find out this information.
+
+Doctrine Query Language
+-----------------------
+
+What is DQL?
+~~~~~~~~~~~~
+
+DQL stands for Doctrine Query Language, a query language that very much looks like SQL
+but has some important benefits when using Doctrine:
+
+-  It uses class names and fields instead of tables and columns, separating concerns between backend and your object model.
+-  It utilizes the metadata defined to offer a range of shortcuts when writing. For example you do not have to specify the ON clause of joins, since Doctrine already knows about them.
+-  It adds some functionality that is related to object management and transforms them into SQL.
+
+It also has some drawbacks of course:
+
+-  The syntax is slightly different to SQL so you have to learn and remember the differences.
+-  To be vendor independent it can only implement a subset of all the existing SQL dialects. Vendor specific functionality and optimizations cannot be used through DQL unless implemented by you explicitly.
+-  For some DQL constructs subselects are used which are known to be slow in MySQL.
+
+Can I sort by a function (for example ORDER BY RAND()) in DQL?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+No, it is not supported to sort by function in DQL. If you need this functionality you should either
+use a native-query or come up with another solution. As a side note: Sorting with ORDER BY RAND() is painfully slow
+starting with 1000 rows.
+
+Is it better to write DQL or to generate it with the query builder?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The purpose of the ``QueryBuilder`` is to generate DQL dynamically,
+which is useful when you have optional filters, conditional joins, etc.
+
+But the ``QueryBuilder`` is not an alternative to DQL, it actually generates DQL
+queries at runtime, which are then interpreted by Doctrine. This means that
+using the ``QueryBuilder`` to build and run a query is actually always slower
+than only running the corresponding DQL query.
+
+So if you only need to generate a query and bind parameters to it,
+you should use plain DQL, as this is a simpler and much more readable solution.
+You should only use the ``QueryBuilder`` when you can't achieve what you want to do with a DQL query.
+
+A Query fails, how can I debug it?
+----------------------------------
+
+First, if you are using the QueryBuilder you can use
+``$queryBuilder->getDQL()`` to get the DQL string of this query. The
+corresponding SQL you can get from the Query instance by calling
+``$query->getSQL()``.
+
+.. code-block:: php
+
+    <?php
+    $dql = "SELECT u FROM User u";
+    $query = $entityManager->createQuery($dql);
+    var_dump($query->getSQL());
+
+    $qb = $entityManager->createQueryBuilder();
+    $qb->select('u')->from('User', 'u');
+    var_dump($qb->getDQL());

vendor/doctrine/orm/docs/en/reference/filters.rst

@@ -0,0 +1,93 @@
+Filters
+=======
+
+.. versionadded:: 2.2
+
+Doctrine 2.2 features a filter system that allows the developer to add SQL to
+the conditional clauses of queries, regardless the place where the SQL is
+generated (e.g. from a DQL query, or by loading associated entities).
+
+The filter functionality works on SQL level. Whether a SQL query is generated
+in a Persister, during lazy loading, in extra lazy collections or from DQL.
+Each time the system iterates over all the enabled filters, adding a new SQL
+part as a filter returns.
+
+By adding SQL to the conditional clauses of queries, the filter system filters
+out rows belonging to the entities at the level of the SQL result set. This
+means that the filtered entities are never hydrated (which can be expensive).
+
+
+Example filter class
+--------------------
+Throughout this document the example ``MyLocaleFilter`` class will be used to
+illustrate how the filter feature works. A filter class must extend the base
+``Doctrine\ORM\Query\Filter\SQLFilter`` class and implement the ``addFilterConstraint``
+method. The method receives the ``ClassMetadata`` of the filtered entity and the
+table alias of the SQL table of the entity.
+
+.. note::
+
+    In the case of joined or single table inheritance, you always get passed the ClassMetadata of the
+    inheritance root. This is necessary to avoid edge cases that would break the SQL when applying the filters.
+
+Parameters for the query should be set on the filter object by
+``SQLFilter#setParameter()``. Only parameters set via this function can be used
+in filters.  The ``SQLFilter#getParameter()`` function takes care of the
+proper quoting of parameters.
+
+.. code-block:: php
+
+    <?php
+    namespace Example;
+    use Doctrine\ORM\Mapping\ClassMetadata,
+        Doctrine\ORM\Query\Filter\SQLFilter;
+
+    class MyLocaleFilter extends SQLFilter
+    {
+        public function addFilterConstraint(ClassMetadata $targetEntity, $targetTableAlias)
+        {
+            // Check if the entity implements the LocalAware interface
+            if (!$targetEntity->reflClass->implementsInterface('LocaleAware')) {
+                return "";
+            }
+
+            return $targetTableAlias.'.locale = ' . $this->getParameter('locale'); // getParameter applies quoting automatically
+        }
+    }
+
+
+Configuration
+-------------
+Filter classes are added to the configuration as following:
+
+.. code-block:: php
+
+    <?php
+    $config->addFilter("locale", "\Doctrine\Tests\ORM\Functional\MyLocaleFilter");
+
+
+The ``Configuration#addFilter()`` method takes a name for the filter and the name of the
+class responsible for the actual filtering.
+
+
+Disabling/Enabling Filters and Setting Parameters
+---------------------------------------------------
+Filters can be disabled and enabled via the ``FilterCollection`` which is
+stored in the ``EntityManager``. The ``FilterCollection#enable($name)`` method
+will retrieve the filter object. You can set the filter parameters on that
+object.
+
+.. code-block:: php
+
+    <?php
+    $filter = $em->getFilters()->enable("locale");
+    $filter->setParameter('locale', 'en');
+
+    // Disable it
+    $filter = $em->getFilters()->disable("locale");
+
+.. warning::
+    Disabling and enabling filters has no effect on managed entities. If you
+    want to refresh or reload an object after having modified a filter or the
+    FilterCollection, then you should clear the EntityManager and re-fetch your
+    entities, having the new rules for filtering applied.

vendor/doctrine/orm/docs/en/reference/improving-performance.rst

@@ -0,0 +1,78 @@
+Improving Performance
+=====================
+
+Bytecode Cache
+--------------
+
+It is highly recommended to make use of a bytecode cache like OPcache.
+A bytecode cache removes the need for parsing PHP code on every
+request and can greatly improve performance.
+
+    "If you care about performance and don't use a bytecode
+    cache then you don't really care about performance. Please get one
+    and start using it."
+    
+    *Stas Malyshev, Core Contributor to PHP and Zend Employee*
+
+
+Metadata and Query caches
+-------------------------
+
+As already mentioned earlier in the chapter about configuring
+Doctrine, it is strongly discouraged to use Doctrine without a
+Metadata and Query cache.
+
+Operating Doctrine without these caches means
+Doctrine will need to load your mapping information on every single
+request and has to parse each DQL query on every single request.
+This is a waste of resources.
+
+The preferred cache driver for metadata and query caches is ``PhpFileCache``. 
+This driver serializes cache items and writes them to a file. 
+This allows for opcode caching to be used and provides high performance in most scenarios.
+
+See :ref:`integrating-with-the-orm`
+
+Alternative Query Result Formats
+--------------------------------
+
+Make effective use of the available alternative query result
+formats like nested array graphs or pure scalar results, especially
+in scenarios where data is loaded for read-only purposes.
+
+Read-Only Entities
+------------------
+
+Starting with Doctrine 2.1 you can mark entities as read only (See metadata mapping
+references for details). This means that the entity marked as read only is never considered
+for updates, which means when you call flush on the EntityManager these entities are skipped
+even if properties changed. Read-Only allows to persist new entities of a kind and remove existing
+ones, they are just not considered for updates.
+
+See :ref:`annref_entity`
+
+Extra-Lazy Collections
+----------------------
+
+If entities hold references to large collections you will get performance and memory problems initializing them.
+To solve this issue you can use the EXTRA_LAZY fetch-mode feature for collections. See the :doc:`tutorial <../tutorials/extra-lazy-associations>`
+for more information on how this fetch mode works.
+
+Temporarily change fetch mode in DQL
+------------------------------------
+
+See :ref:`dql-temporarily-change-fetch-mode`
+
+
+Apply Best Practices
+--------------------
+
+A lot of the points mentioned in the Best Practices chapter will
+also positively affect the performance of Doctrine.
+
+See :doc:`Best Practices <reference/best-practices>`
+
+Change Tracking policies
+------------------------
+
+See: :doc:`Change Tracking Policies <reference/change-tracking-policies>`

vendor/doctrine/orm/docs/en/reference/inheritance-mapping.rst

@@ -0,0 +1,612 @@
+Inheritance Mapping
+===================
+
+Mapped Superclasses
+-------------------
+
+A mapped superclass is an abstract or concrete class that provides
+persistent entity state and mapping information for its subclasses,
+but which is not itself an entity. Typically, the purpose of such a
+mapped superclass is to define state and mapping information that
+is common to multiple entity classes.
+
+Mapped superclasses, just as regular, non-mapped classes, can
+appear in the middle of an otherwise mapped inheritance hierarchy
+(through Single Table Inheritance or Class Table Inheritance).
+
+.. note::
+
+    A mapped superclass cannot be an entity, it is not query-able and
+    persistent relationships defined by a mapped superclass must be
+    unidirectional (with an owning side only). This means that One-To-Many
+    associations are not possible on a mapped superclass at all.
+    Furthermore Many-To-Many associations are only possible if the
+    mapped superclass is only used in exactly one entity at the moment.
+    For further support of inheritance, the single or
+    joined table inheritance features have to be used.
+
+
+Example:
+
+.. code-block:: php
+
+    <?php
+    /** @MappedSuperclass */
+    class MappedSuperclassBase
+    {
+        /** @Column(type="integer") */
+        protected $mapped1;
+        /** @Column(type="string") */
+        protected $mapped2;
+        /**
+         * @OneToOne(targetEntity="MappedSuperclassRelated1")
+         * @JoinColumn(name="related1_id", referencedColumnName="id")
+         */
+        protected $mappedRelated1;
+    
+        // ... more fields and methods
+    }
+    
+    /** @Entity */
+    class EntitySubClass extends MappedSuperclassBase
+    {
+        /** @Id @Column(type="integer") */
+        private $id;
+        /** @Column(type="string") */
+        private $name;
+    
+        // ... more fields and methods
+    }
+
+The DDL for the corresponding database schema would look something
+like this (this is for SQLite):
+
+.. code-block:: sql
+
+    CREATE TABLE EntitySubClass (mapped1 INTEGER NOT NULL, mapped2 TEXT NOT NULL, id INTEGER NOT NULL, name TEXT NOT NULL, related1_id INTEGER DEFAULT NULL, PRIMARY KEY(id))
+
+As you can see from this DDL snippet, there is only a single table
+for the entity subclass. All the mappings from the mapped
+superclass were inherited to the subclass as if they had been
+defined on that class directly.
+
+Single Table Inheritance
+------------------------
+
+`Single Table Inheritance <http://martinfowler.com/eaaCatalog/singleTableInheritance.html>`_
+is an inheritance mapping strategy where all classes of a hierarchy
+are mapped to a single database table. In order to distinguish
+which row represents which type in the hierarchy a so-called
+discriminator column is used.
+
+Example:
+
+.. configuration-block::
+
+    .. code-block:: php
+    
+        <?php
+        namespace MyProject\Model;
+        
+        /**
+         * @Entity
+         * @InheritanceType("SINGLE_TABLE")
+         * @DiscriminatorColumn(name="discr", type="string")
+         * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
+         */
+        class Person
+        {
+            // ...
+        }
+        
+        /**
+         * @Entity
+         */
+        class Employee extends Person
+        {
+            // ...
+        }
+
+    .. code-block:: yaml
+    
+        MyProject\Model\Person:
+          type: entity
+          inheritanceType: SINGLE_TABLE
+          discriminatorColumn:
+            name: discr
+            type: string
+          discriminatorMap:
+            person: Person
+            employee: Employee
+                
+        MyProject\Model\Employee:
+          type: entity
+            
+Things to note:
+
+
+-  The @InheritanceType and @DiscriminatorColumn must be specified 
+   on the topmost class that is part of the mapped entity hierarchy.
+-  The @DiscriminatorMap specifies which values of the
+   discriminator column identify a row as being of a certain type. In
+   the case above a value of "person" identifies a row as being of
+   type ``Person`` and "employee" identifies a row as being of type
+   ``Employee``.
+-  All entity classes that is part of the mapped entity hierarchy
+   (including the topmost class) should be specified in the
+   @DiscriminatorMap. In the case above Person class included.
+-  The names of the classes in the discriminator map do not need to
+   be fully qualified if the classes are contained in the same
+   namespace as the entity class on which the discriminator map is
+   applied.
+-  If no discriminator map is provided, then the map is generated
+   automatically. The automatically generated discriminator map 
+   contains the lowercase short name of each class as key.
+
+Design-time considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This mapping approach works well when the type hierarchy is fairly
+simple and stable. Adding a new type to the hierarchy and adding
+fields to existing supertypes simply involves adding new columns to
+the table, though in large deployments this may have an adverse
+impact on the index and column layout inside the database.
+
+Performance impact
+~~~~~~~~~~~~~~~~~~
+
+This strategy is very efficient for querying across all types in
+the hierarchy or for specific types. No table joins are required,
+only a WHERE clause listing the type identifiers. In particular,
+relationships involving types that employ this mapping strategy are
+very performing.
+
+There is a general performance consideration with Single Table
+Inheritance: If the target-entity of a many-to-one or one-to-one 
+association is an STI entity, it is preferable for performance reasons that it 
+be a leaf entity in the inheritance hierarchy, (ie. have no subclasses). 
+Otherwise Doctrine *CANNOT* create proxy instances
+of this entity and will *ALWAYS* load the entity eagerly.
+
+SQL Schema considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For Single-Table-Inheritance to work in scenarios where you are
+using either a legacy database schema or a self-written database
+schema you have to make sure that all columns that are not in the
+root entity but in any of the different sub-entities has to allow
+null values. Columns that have NOT NULL constraints have to be on
+the root entity of the single-table inheritance hierarchy.
+
+Class Table Inheritance
+-----------------------
+
+`Class Table Inheritance <http://martinfowler.com/eaaCatalog/classTableInheritance.html>`_
+is an inheritance mapping strategy where each class in a hierarchy
+is mapped to several tables: its own table and the tables of all
+parent classes. The table of a child class is linked to the table
+of a parent class through a foreign key constraint. Doctrine 2
+implements this strategy through the use of a discriminator column
+in the topmost table of the hierarchy because this is the easiest
+way to achieve polymorphic queries with Class Table Inheritance.
+
+Example:
+
+.. code-block:: php
+
+    <?php
+    namespace MyProject\Model;
+    
+    /**
+     * @Entity
+     * @InheritanceType("JOINED")
+     * @DiscriminatorColumn(name="discr", type="string")
+     * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
+     */
+    class Person
+    {
+        // ...
+    }
+    
+    /** @Entity */
+    class Employee extends Person
+    {
+        // ...
+    }
+
+Things to note:
+
+
+-  The @InheritanceType, @DiscriminatorColumn and @DiscriminatorMap
+   must be specified on the topmost class that is part of the mapped
+   entity hierarchy.
+-  The @DiscriminatorMap specifies which values of the
+   discriminator column identify a row as being of which type. In the
+   case above a value of "person" identifies a row as being of type
+   ``Person`` and "employee" identifies a row as being of type
+   ``Employee``.
+-  The names of the classes in the discriminator map do not need to
+   be fully qualified if the classes are contained in the same
+   namespace as the entity class on which the discriminator map is
+   applied.
+-  If no discriminator map is provided, then the map is generated
+   automatically. The automatically generated discriminator map 
+   contains the lowercase short name of each class as key.
+
+.. note::
+
+    When you do not use the SchemaTool to generate the
+    required SQL you should know that deleting a class table
+    inheritance makes use of the foreign key property
+    ``ON DELETE CASCADE`` in all database implementations. A failure to
+    implement this yourself will lead to dead rows in the database.
+
+
+Design-time considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Introducing a new type to the hierarchy, at any level, simply
+involves interjecting a new table into the schema. Subtypes of that
+type will automatically join with that new type at runtime.
+Similarly, modifying any entity type in the hierarchy by adding,
+modifying or removing fields affects only the immediate table
+mapped to that type. This mapping strategy provides the greatest
+flexibility at design time, since changes to any type are always
+limited to that type's dedicated table.
+
+Performance impact
+~~~~~~~~~~~~~~~~~~
+
+This strategy inherently requires multiple JOIN operations to
+perform just about any query which can have a negative impact on
+performance, especially with large tables and/or large hierarchies.
+When partial objects are allowed, either globally or on the
+specific query, then querying for any type will not cause the
+tables of subtypes to be OUTER JOINed which can increase
+performance but the resulting partial objects will not fully load
+themselves on access of any subtype fields, so accessing fields of
+subtypes after such a query is not safe.
+
+There is a general performance consideration with Class Table
+Inheritance: If the target-entity of a many-to-one or one-to-one 
+association is a CTI entity, it is preferable for performance reasons that it 
+be a leaf entity in the inheritance hierarchy, (ie. have no subclasses). 
+Otherwise Doctrine *CANNOT* create proxy instances
+of this entity and will *ALWAYS* load the entity eagerly.
+
+SQL Schema considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For each entity in the Class-Table Inheritance hierarchy all the
+mapped fields have to be columns on the table of this entity.
+Additionally each child table has to have an id column that matches
+the id column definition on the root table (except for any sequence
+or auto-increment details). Furthermore each child table has to
+have a foreign key pointing from the id column to the root table id
+column and cascading on delete.
+
+.. _inheritence_mapping_overrides:
+
+Overrides
+---------
+
+Used to override a mapping for an entity field or relationship.  Can only be
+applied to an entity that extends a mapped superclass or uses a trait to
+override a relationship or field mapping defined by the mapped superclass or
+trait.
+
+It is not possible to override attributes or associations in entity to entity
+inheritance scenarios, because this can cause unforseen edge case behavior and
+increases complexity in ORM internal classes.
+
+
+Association Override
+~~~~~~~~~~~~~~~~~~~~
+Override a mapping for an entity relationship.
+
+Could be used by an entity that extends a mapped superclass
+to override a relationship mapping defined by the mapped superclass.
+
+Example:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        // user mapping
+        namespace MyProject\Model;
+        /**
+         * @MappedSuperclass
+         */
+        class User
+        {
+            //other fields mapping
+
+            /**
+             * @ManyToMany(targetEntity="Group", inversedBy="users")
+             * @JoinTable(name="users_groups",
+             *  joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
+             *  inverseJoinColumns={@JoinColumn(name="group_id", referencedColumnName="id")}
+             * )
+             */
+            protected $groups;
+
+            /**
+             * @ManyToOne(targetEntity="Address")
+             * @JoinColumn(name="address_id", referencedColumnName="id")
+             */
+            protected $address;
+        }
+
+        // admin mapping
+        namespace MyProject\Model;
+        /**
+         * @Entity
+         * @AssociationOverrides({
+         *      @AssociationOverride(name="groups",
+         *          joinTable=@JoinTable(
+         *              name="users_admingroups",
+         *              joinColumns=@JoinColumn(name="adminuser_id"),
+         *              inverseJoinColumns=@JoinColumn(name="admingroup_id")
+         *          )
+         *      ),
+         *      @AssociationOverride(name="address",
+         *          joinColumns=@JoinColumn(
+         *              name="adminaddress_id", referencedColumnName="id"
+         *          )
+         *      )
+         * })
+         */
+        class Admin extends User
+        {
+        }
+
+    .. code-block:: xml
+
+        <!-- user mapping -->
+        <doctrine-mapping>
+          <mapped-superclass name="MyProject\Model\User">
+                <!-- other fields mapping -->
+                <many-to-many field="groups" target-entity="Group" inversed-by="users">
+                    <cascade>
+                        <cascade-persist/>
+                        <cascade-merge/>
+                        <cascade-detach/>
+                    </cascade>
+                    <join-table name="users_groups">
+                        <join-columns>
+                            <join-column name="user_id" referenced-column-name="id" />
+                        </join-columns>
+                        <inverse-join-columns>
+                            <join-column name="group_id" referenced-column-name="id" />
+                        </inverse-join-columns>
+                    </join-table>
+                </many-to-many>
+            </mapped-superclass>
+        </doctrine-mapping>
+
+        <!-- admin mapping -->
+        <doctrine-mapping>
+            <entity name="MyProject\Model\Admin">
+                <association-overrides>
+                    <association-override name="groups">
+                        <join-table name="users_admingroups">
+                            <join-columns>
+                                <join-column name="adminuser_id"/>
+                            </join-columns>
+                            <inverse-join-columns>
+                                <join-column name="admingroup_id"/>
+                            </inverse-join-columns>
+                        </join-table>
+                    </association-override>
+                    <association-override name="address">
+                        <join-columns>
+                            <join-column name="adminaddress_id" referenced-column-name="id"/>
+                        </join-columns>
+                    </association-override>
+                </association-overrides>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        # user mapping
+        MyProject\Model\User:
+          type: mappedSuperclass
+          # other fields mapping
+          manyToOne:
+            address:
+              targetEntity: Address
+              joinColumn:
+                name: address_id
+                referencedColumnName: id
+              cascade: [ persist, merge ]
+          manyToMany:
+            groups:
+              targetEntity: Group
+              joinTable:
+                name: users_groups
+                joinColumns:
+                  user_id:
+                    referencedColumnName: id
+                inverseJoinColumns:
+                  group_id:
+                    referencedColumnName: id
+              cascade: [ persist, merge, detach ]
+
+        # admin mapping
+        MyProject\Model\Admin:
+          type: entity
+          associationOverride:
+            address:
+              joinColumn:
+                adminaddress_id:
+                  name: adminaddress_id
+                  referencedColumnName: id
+            groups:
+              joinTable:
+                name: users_admingroups
+                joinColumns:
+                  adminuser_id:
+                    referencedColumnName: id
+                inverseJoinColumns:
+                  admingroup_id:
+                    referencedColumnName: id
+
+
+Things to note:
+
+-  The "association override" specifies the overrides base on the property name.
+-  This feature is available for all kind of associations. (OneToOne, OneToMany, ManyToOne, ManyToMany)
+-  The association type *CANNOT* be changed.
+-  The override could redefine the joinTables or joinColumns depending on the association type.
+-  The override could redefine inversedBy to reference more than one extended entity.
+-  The override could redefine fetch to modify the fetch strategy of the extended entity.
+
+Attribute Override
+~~~~~~~~~~~~~~~~~~~~
+Override the mapping of a field.
+
+Could be used by an entity that extends a mapped superclass to override a field mapping defined by the mapped superclass.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        // user mapping
+        namespace MyProject\Model;
+        /**
+         * @MappedSuperclass
+         */
+        class User
+        {
+            /** @Id @GeneratedValue @Column(type="integer", name="user_id", length=150) */
+            protected $id;
+
+            /** @Column(name="user_name", nullable=true, unique=false, length=250) */
+            protected $name;
+
+            // other fields mapping
+        }
+
+        // guest mapping
+        namespace MyProject\Model;
+        /**
+         * @Entity
+         * @AttributeOverrides({
+         *      @AttributeOverride(name="id",
+         *          column=@Column(
+         *              name     = "guest_id",
+         *              type     = "integer",
+         *              length   = 140
+         *          )
+         *      ),
+         *      @AttributeOverride(name="name",
+         *          column=@Column(
+         *              name     = "guest_name",
+         *              nullable = false,
+         *              unique   = true,
+         *              length   = 240
+         *          )
+         *      )
+         * })
+         */
+        class Guest extends User
+        {
+        }
+
+    .. code-block:: xml
+
+        <!-- user mapping -->
+        <doctrine-mapping>
+          <mapped-superclass name="MyProject\Model\User">
+                <id name="id" type="integer" column="user_id" length="150">
+                    <generator strategy="AUTO"/>
+                </id>
+                <field name="name" column="user_name" type="string" length="250" nullable="true" unique="false" />
+                <many-to-one field="address" target-entity="Address">
+                    <cascade>
+                        <cascade-persist/>
+                        <cascade-merge/>
+                    </cascade>
+                    <join-column name="address_id" referenced-column-name="id"/>
+                </many-to-one>
+                <!-- other fields mapping -->
+            </mapped-superclass>
+        </doctrine-mapping>
+
+        <!-- admin mapping -->
+        <doctrine-mapping>
+            <entity name="MyProject\Model\Guest">
+                <attribute-overrides>
+                    <attribute-override name="id">
+                        <field column="guest_id" length="140"/>
+                    </attribute-override>
+                    <attribute-override name="name">
+                        <field column="guest_name" type="string" length="240" nullable="false" unique="true" />
+                    </attribute-override>
+                </attribute-overrides>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        # user mapping
+        MyProject\Model\User:
+          type: mappedSuperclass
+          id:
+            id:
+              type: integer
+              column: user_id
+              length: 150
+              generator:
+                strategy: AUTO
+          fields:
+            name:
+              type: string
+              column: user_name
+              length: 250
+              nullable: true
+              unique: false
+          #other fields mapping
+
+
+        # guest mapping
+        MyProject\Model\Guest:
+          type: entity
+          attributeOverride:
+            id:
+              column: guest_id
+              type: integer
+              length: 140
+            name:
+              column: guest_name
+              type: string
+              length: 240
+              nullable: false
+              unique: true
+
+Things to note:
+
+-  The "attribute override" specifies the overrides base on the property name.
+-  The column type *CANNOT* be changed. If the column type is not equal you get a ``MappingException``
+-  The override can redefine all the attributes except the type.
+
+Query the Type
+--------------
+
+It may happen that the entities of a special type should be queried. Because there
+is no direct access to the discriminator column, Doctrine provides the
+``INSTANCE OF`` construct.
+
+The following example shows how to use ``INSTANCE OF``. There is a three level hierarchy
+with a base entity ``NaturalPerson`` which is extended by ``Staff`` which in turn
+is extended by ``Technician``.
+
+Querying for the staffs without getting any technicians can be achieved by this DQL:
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery("SELECT staff FROM MyProject\Model\Staff staff WHERE staff NOT INSTANCE OF MyProject\Model\Technician");
+    $staffs = $query->getResult();

vendor/doctrine/orm/docs/en/reference/installation.rst

@@ -0,0 +1,4 @@
+Installation
+============
+
+The installation chapter has moved to :doc:`Installation and Configuration <reference/configuration>`_.

vendor/doctrine/orm/docs/en/reference/limitations-and-known-issues.rst

@@ -0,0 +1,203 @@
+Limitations and Known Issues
+============================
+
+We try to make using Doctrine2 a very pleasant experience.
+Therefore we think it is very important to be honest about the
+current limitations to our users. Much like every other piece of
+software Doctrine2 is not perfect and far from feature complete.
+This section should give you an overview of current limitations of
+Doctrine 2 as well as critical known issues that you should know
+about.
+
+Current Limitations
+-------------------
+
+There is a set of limitations that exist currently which might be
+solved in the future. Any of this limitations now stated has at
+least one ticket in the Tracker and is discussed for future
+releases.
+
+Join-Columns with non-primary keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is not possible to use join columns pointing to non-primary keys. Doctrine will think these are the primary
+keys and create lazy-loading proxies with the data, which can lead to unexpected results. Doctrine can for performance
+reasons not validate the correctness of this settings at runtime but only through the Validate Schema command.
+
+Mapping Arrays to a Join Table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Related to the previous limitation with "Foreign Keys as
+Identifier" you might be interested in mapping the same table
+structure as given above to an array. However this is not yet
+possible either. See the following example:
+
+.. code-block:: sql
+
+    CREATE TABLE product (
+        id INTEGER,
+        name VARCHAR,
+        PRIMARY KEY(id)
+    );
+    
+    CREATE TABLE product_attributes (
+        product_id INTEGER,
+        attribute_name VARCHAR,
+        attribute_value VARCHAR,
+        PRIMARY KEY (product_id, attribute_name)
+    );
+
+This schema should be mapped to a Product Entity as follows:
+
+.. code-block:: php
+
+    class Product
+    {
+        private $id;
+        private $name;
+        private $attributes = array();
+    }
+
+Where the ``attribute_name`` column contains the key and
+``attribute_value`` contains the value of each array element in
+``$attributes``.
+
+The feature request for persistence of primitive value arrays
+`is described in the DDC-298 ticket <https://github.com/doctrine/orm/issues/3743>`_.
+
+Cascade Merge with Bi-directional Associations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two bugs now that concern the use of cascade merge in combination with bi-directional associations.
+Make sure to study the behavior of cascade merge if you are using it:
+
+-  `DDC-875 <https://github.com/doctrine/orm/issues/5398>`_ Merge can sometimes add the same entity twice into a collection
+-  `DDC-763 <https://github.com/doctrine/orm/issues/5277>`_ Cascade merge on associated entities can insert too many rows through "Persistence by Reachability"
+
+Custom Persisters
+~~~~~~~~~~~~~~~~~
+
+A Persister in Doctrine is an object that is responsible for the
+hydration and write operations of an entity against the database.
+Currently there is no way to overwrite the persister implementation
+for a given entity, however there are several use-cases that can
+benefit from custom persister implementations:
+
+-  `Add Upsert Support <https://github.com/doctrine/orm/issues/5178>`_
+-  `Evaluate possible ways in which stored-procedures can be used <https://github.com/doctrine/orm/issues/4946>`_
+
+Persist Keys of Collections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PHP Arrays are ordered hash-maps and so should be the
+``Doctrine\Common\Collections\Collection`` interface. We plan to
+evaluate a feature that optionally persists and hydrates the keys
+of a Collection instance.
+
+`Ticket DDC-213 <https://github.com/doctrine/orm/issues/2817>`_
+
+Mapping many tables to one entity
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is not possible to map several equally looking tables onto one
+entity. For example if you have a production and an archive table
+of a certain business concept then you cannot have both tables map
+to the same entity.
+
+Behaviors
+~~~~~~~~~
+
+Doctrine 2 will **never** include a behavior system like Doctrine 1
+in the core library. We don't think behaviors add more value than
+they cost pain and debugging hell. Please see the many different
+blog posts we have written on this topics:
+
+-  `Doctrine2 "Behaviors" in a Nutshell <http://www.doctrine-project.org/2010/02/17/doctrine2-behaviours-nutshell.html>`_
+-  `A re-usable Versionable behavior for Doctrine2 <http://www.doctrine-project.org/2010/02/24/doctrine2-versionable.html>`_
+-  `Write your own ORM on top of Doctrine2 <http://www.doctrine-project.org/2010/07/19/your-own-orm-doctrine2.html>`_
+-  `Doctrine 2 Behavioral Extensions <http://www.doctrine-project.org/2010/11/18/doctrine2-behavioral-extensions.html>`_
+
+Doctrine 2 has enough hooks and extension points so that **you** can
+add whatever you want on top of it. None of this will ever become
+core functionality of Doctrine2 however, you will have to rely on
+third party extensions for magical behaviors.
+
+Nested Set
+~~~~~~~~~~
+
+NestedSet was offered as a behavior in Doctrine 1 and will not be
+included in the core of Doctrine 2. However there are already two
+extensions out there that offer support for Nested Set with
+Doctrine 2:
+
+
+-  `Doctrine2 Hierarchical-Structural Behavior <http://github.com/guilhermeblanco/Doctrine2-Hierarchical-Structural-Behavior>`_
+-  `Doctrine2 NestedSet <http://github.com/blt04/doctrine2-nestedset>`_
+
+Known Issues
+------------
+
+The Known Issues section describes critical/blocker bugs and other
+issues that are either complicated to fix, not fixable due to
+backwards compatibility issues or where no simple fix exists (yet).
+We don't plan to add every bug in the tracker there, just those
+issues that can potentially cause nightmares or pain of any sort.
+
+See bugs, improvement and feature requests on `Github issues <https://github.com/doctrine/orm/issues>`_.
+
+Identifier Quoting and Legacy Databases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For compatibility reasons between all the supported vendors and
+edge case problems Doctrine 2 does **NOT** do automatic identifier
+quoting. This can lead to problems when trying to get
+legacy-databases to work with Doctrine 2.
+
+
+-  You can quote column-names as described in the
+   :doc:`Basic-Mapping <basic-mapping>` section.
+-  You cannot quote join column names.
+-  You cannot use non [a-zA-Z0-9\_]+ characters, they will break
+   several SQL statements.
+
+Having problems with these kind of column names? Many databases
+support all CRUD operations on views that semantically map to
+certain tables. You can create views for all your problematic
+tables and column names to avoid the legacy quoting nightmare.
+
+Microsoft SQL Server and Doctrine "datetime"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Doctrine assumes that you use ``DateTime2`` data-types. If your legacy database contains DateTime
+datatypes then you have to add your own data-type (see Basic Mapping for an example).
+
+MySQL with MyISAM tables
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Doctrine cannot provide atomic operations when calling ``EntityManager#flush()`` if one
+of the tables involved uses the storage engine MyISAM. You must use InnoDB or
+other storage engines that support transactions if you need integrity.
+
+Entities, Proxies and Reflection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using methods for Reflection on entities can be prone to error, when the entity
+is actually a proxy the following methods will not work correctly:
+
+- ``new ReflectionClass``
+- ``new ReflectionObject``
+- ``get_class()``
+- ``get_parent_class()``
+
+This is why ``Doctrine\Common\Util\ClassUtils`` class exists that has similar
+methods, which resolve the proxy problem beforehand.
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\Common\Util\ClassUtils;
+
+    $bookProxy = $entityManager->getReference('Acme\Book');
+
+    $reflection = ClassUtils::newReflectionClass($bookProxy);
+    $class = ClassUtils::getClass($bookProxy)¸

vendor/doctrine/orm/docs/en/reference/metadata-drivers.rst

@@ -0,0 +1,194 @@
+Metadata Drivers
+================
+
+The heart of an object relational mapper is the mapping information
+that glues everything together. It instructs the EntityManager how
+it should behave when dealing with the different entities.
+
+Core Metadata Drivers
+---------------------
+
+Doctrine provides a few different ways for you to specify your
+metadata:
+
+
+-  **XML files** (XmlDriver)
+-  **Class DocBlock Annotations** (AnnotationDriver)
+-  **YAML files** (YamlDriver)
+-  **PHP Code in files or static functions** (PhpDriver)
+
+Something important to note about the above drivers is they are all
+an intermediate step to the same end result. The mapping
+information is populated to ``Doctrine\ORM\Mapping\ClassMetadata``
+instances. So in the end, Doctrine only ever has to work with the
+API of the ``ClassMetadata`` class to get mapping information for
+an entity.
+
+.. note::
+
+    The populated ``ClassMetadata`` instances are also cached
+    so in a production environment the parsing and populating only ever
+    happens once. You can configure the metadata cache implementation
+    using the ``setMetadataCacheImpl()`` method on the
+    ``Doctrine\ORM\Configuration`` class:
+
+    .. code-block:: php
+
+        <?php
+        $em->getConfiguration()->setMetadataCacheImpl(new ApcuCache());
+
+
+If you want to use one of the included core metadata drivers you
+just need to configure it. All the drivers are in the
+``Doctrine\ORM\Mapping\Driver`` namespace:
+
+.. code-block:: php
+
+    <?php
+    $driver = new \Doctrine\ORM\Mapping\Driver\XmlDriver('/path/to/mapping/files');
+    $em->getConfiguration()->setMetadataDriverImpl($driver);
+
+Implementing Metadata Drivers
+-----------------------------
+
+In addition to the included metadata drivers you can very easily
+implement your own. All you need to do is define a class which
+implements the ``Driver`` interface:
+
+.. code-block:: php
+
+    <?php
+    namespace Doctrine\ORM\Mapping\Driver;
+    
+    use Doctrine\ORM\Mapping\ClassMetadataInfo;
+    
+    interface Driver
+    {
+        /**
+         * Loads the metadata for the specified class into the provided container.
+         * 
+         * @param string $className
+         * @param ClassMetadataInfo $metadata
+         */
+        function loadMetadataForClass($className, ClassMetadataInfo $metadata);
+    
+        /**
+         * Gets the names of all mapped classes known to this driver.
+         * 
+         * @return array The names of all mapped classes known to this driver.
+         */
+        function getAllClassNames(); 
+    
+        /**
+         * Whether the class with the specified name should have its metadata loaded.
+         * This is only the case if it is either mapped as an Entity or a
+         * MappedSuperclass.
+         *
+         * @param string $className
+         * @return boolean
+         */
+        function isTransient($className);
+    }
+
+If you want to write a metadata driver to parse information from
+some file format we've made your life a little easier by providing
+the ``AbstractFileDriver`` implementation for you to extend from:
+
+.. code-block:: php
+
+    <?php
+    class MyMetadataDriver extends AbstractFileDriver
+    {
+        /**
+         * {@inheritdoc}
+         */
+        protected $_fileExtension = '.dcm.ext';
+    
+        /**
+         * {@inheritdoc}
+         */
+        public function loadMetadataForClass($className, ClassMetadataInfo $metadata)
+        {
+            $data = $this->_loadMappingFile($file);
+    
+            // populate ClassMetadataInfo instance from $data
+        }
+    
+        /**
+         * {@inheritdoc}
+         */
+        protected function _loadMappingFile($file)
+        {
+            // parse contents of $file and return php data structure
+        }
+    }
+
+.. note::
+
+    When using the ``AbstractFileDriver`` it requires that you
+    only have one entity defined per file and the file named after the
+    class described inside where namespace separators are replaced by
+    periods. So if you have an entity named ``Entities\User`` and you
+    wanted to write a mapping file for your driver above you would need
+    to name the file ``Entities.User.dcm.ext`` for it to be
+    recognized.
+
+
+Now you can use your ``MyMetadataDriver`` implementation by setting
+it with the ``setMetadataDriverImpl()`` method:
+
+.. code-block:: php
+
+    <?php
+    $driver = new MyMetadataDriver('/path/to/mapping/files');
+    $em->getConfiguration()->setMetadataDriverImpl($driver);
+
+ClassMetadata
+-------------
+
+The last piece you need to know and understand about metadata in
+Doctrine 2 is the API of the ``ClassMetadata`` classes. You need to
+be familiar with them in order to implement your own drivers but
+more importantly to retrieve mapping information for a certain
+entity when needed.
+
+You have all the methods you need to manually specify the mapping
+information instead of using some mapping file to populate it from.
+The base ``ClassMetadataInfo`` class is responsible for only data
+storage and is not meant for runtime use. It does not require that
+the class actually exists yet so it is useful for describing some
+entity before it exists and using that information to generate for
+example the entities themselves. The class ``ClassMetadata``
+extends ``ClassMetadataInfo`` and adds some functionality required
+for runtime usage and requires that the PHP class is present and
+can be autoloaded.
+
+You can read more about the API of the ``ClassMetadata`` classes in
+the PHP Mapping chapter.
+
+Getting ClassMetadata Instances
+-------------------------------
+
+If you want to get the ``ClassMetadata`` instance for an entity in
+your project to programmatically use some mapping information to
+generate some HTML or something similar you can retrieve it through
+the ``ClassMetadataFactory``:
+
+.. code-block:: php
+
+    <?php
+    $cmf = $em->getMetadataFactory();
+    $class = $cmf->getMetadataFor('MyEntityName');
+
+Now you can learn about the entity and use the data stored in the
+``ClassMetadata`` instance to get all mapped fields for example and
+iterate over them:
+
+.. code-block:: php
+
+    <?php
+    foreach ($class->fieldMappings as $fieldMapping) {
+        echo $fieldMapping['fieldName'] . "\n";
+    }
+
+

vendor/doctrine/orm/docs/en/reference/namingstrategy.rst

@@ -0,0 +1,141 @@
+Implementing a NamingStrategy
+==============================
+
+.. versionadded:: 2.3
+
+Using a naming strategy you can provide rules for generating database identifiers,
+column or table names. This feature helps
+reduce the verbosity of the mapping document, eliminating repetitive noise (eg: ``TABLE_``).
+
+.. warning
+
+    The naming strategy is always overridden by entity mapping such as the `Table` annotation.
+
+Configuring a naming strategy
+-----------------------------
+The default strategy used by Doctrine is quite minimal.
+
+By default the ``Doctrine\ORM\Mapping\DefaultNamingStrategy``
+uses the simple class name and the attribute names to generate tables and columns.
+
+You can specify a different strategy by calling ``Doctrine\ORM\Configuration#setNamingStrategy()``:
+
+.. code-block:: php
+
+    <?php
+    $namingStrategy = new MyNamingStrategy();
+    $configuration->setNamingStrategy($namingStrategy);
+
+Underscore naming strategy
+---------------------------
+
+``\Doctrine\ORM\Mapping\UnderscoreNamingStrategy`` is a built-in strategy.
+
+.. code-block:: php
+
+    <?php
+    $namingStrategy = new \Doctrine\ORM\Mapping\UnderscoreNamingStrategy(CASE_UPPER);
+    $configuration->setNamingStrategy($namingStrategy);
+
+For SomeEntityName the strategy will generate the table SOME_ENTITY_NAME with the
+``CASE_UPPER`` option, or some_entity_name with the ``CASE_LOWER`` option.
+
+Naming strategy interface
+-------------------------
+The interface ``Doctrine\ORM\Mapping\NamingStrategy`` allows you to specify
+a naming strategy for database tables and columns.
+
+.. code-block:: php
+
+    <?php
+    /**
+     * Return a table name for an entity class
+     *
+     * @param string $className The fully-qualified class name
+     * @return string A table name
+     */
+    function classToTableName($className);
+
+    /**
+     * Return a column name for a property
+     *
+     * @param string $propertyName A property
+     * @return string A column name
+     */
+    function propertyToColumnName($propertyName);
+
+    /**
+     * Return the default reference column name
+     *
+     * @return string A column name
+     */
+    function referenceColumnName();
+
+    /**
+     * Return a join column name for a property
+     *
+     * @param string $propertyName A property
+     * @return string A join column name
+     */
+    function joinColumnName($propertyName, $className = null);
+
+    /**
+     * Return a join table name
+     *
+     * @param string $sourceEntity The source entity
+     * @param string $targetEntity The target entity
+     * @param string $propertyName A property
+     * @return string A join table name
+     */
+    function joinTableName($sourceEntity, $targetEntity, $propertyName = null);
+
+    /**
+     * Return the foreign key column name for the given parameters
+     *
+     * @param string $entityName A entity
+     * @param string $referencedColumnName A property
+     * @return string A join column name
+     */
+    function joinKeyColumnName($entityName, $referencedColumnName = null);
+
+Implementing a naming strategy
+-------------------------------
+If you have database naming standards, like all table names should be prefixed
+by the application prefix, all column names should be lower case, you can easily
+achieve such standards by implementing a naming strategy.
+
+You need to create a class which implements ``Doctrine\ORM\Mapping\NamingStrategy``.
+
+
+.. code-block:: php
+
+    <?php
+    class MyAppNamingStrategy implements NamingStrategy
+    {
+        public function classToTableName($className)
+        {
+            return 'MyApp_' . substr($className, strrpos($className, '\\') + 1);
+        }
+        public function propertyToColumnName($propertyName)
+        {
+            return $propertyName;
+        }
+        public function referenceColumnName()
+        {
+            return 'id';
+        }
+        public function joinColumnName($propertyName, $className = null)
+        {
+            return $propertyName . '_' . $this->referenceColumnName();
+        }
+        public function joinTableName($sourceEntity, $targetEntity, $propertyName = null)
+        {
+            return strtolower($this->classToTableName($sourceEntity) . '_' .
+                    $this->classToTableName($targetEntity));
+        }
+        public function joinKeyColumnName($entityName, $referencedColumnName = null)
+        {
+            return strtolower($this->classToTableName($entityName) . '_' .
+                    ($referencedColumnName ?: $this->referenceColumnName()));
+        }
+    }

vendor/doctrine/orm/docs/en/reference/native-sql.rst

@@ -0,0 +1,905 @@
+Native SQL
+==========
+
+With ``NativeQuery`` you can execute native SELECT SQL statements
+and map the results to Doctrine entities or any other result format
+supported by Doctrine.
+
+In order to make this mapping possible, you need to describe
+to Doctrine what columns in the result map to which entity property.
+This description is represented by a ``ResultSetMapping`` object.
+
+With this feature you can map arbitrary SQL code to objects, such as highly
+vendor-optimized SQL or stored-procedures.
+
+Writing ``ResultSetMapping`` from scratch is complex, but there is a convenience
+wrapper around it called a ``ResultSetMappingBuilder``. It can generate
+the mappings for you based on Entities and even generates the ``SELECT``
+clause based on this information for you.
+
+.. note::
+
+    If you want to execute DELETE, UPDATE or INSERT statements
+    the Native SQL API cannot be used and will probably throw errors.
+    Use ``EntityManager#getConnection()`` to access the native database
+    connection and call the ``executeUpdate()`` method for these
+    queries.
+
+The NativeQuery class
+---------------------
+
+To create a ``NativeQuery`` you use the method
+``EntityManager#createNativeQuery($sql, $resultSetMapping)``. As you can see in
+the signature of this method, it expects 2 ingredients: The SQL you want to
+execute and the ``ResultSetMapping`` that describes how the results will be
+mapped.
+
+Once you obtained an instance of a ``NativeQuery``, you can bind parameters to
+it with the same API that ``Query`` has and execute it.
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Query\ResultSetMapping;
+
+    $rsm = new ResultSetMapping();
+    // build rsm here
+
+    $query = $entityManager->createNativeQuery('SELECT id, name, discr FROM users WHERE name = ?', $rsm);
+    $query->setParameter(1, 'romanb');
+
+    $users = $query->getResult();
+
+ResultSetMappingBuilder
+-----------------------
+
+An easy start into ResultSet mapping is the ``ResultSetMappingBuilder`` object.
+This has several benefits:
+
+- The builder takes care of automatically updating your ``ResultSetMapping``
+  when the fields or associations change on the metadata of an entity.
+- You can generate the required ``SELECT`` expression for a builder
+  by converting it to a string.
+- The API is much simpler than the usual ``ResultSetMapping`` API.
+
+One downside is that the builder API does not yet support entities
+with inheritance hierarchies.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\ORM\Query\ResultSetMappingBuilder;
+
+    $sql = "SELECT u.id, u.name, a.id AS address_id, a.street, a.city " . 
+           "FROM users u INNER JOIN address a ON u.address_id = a.id";
+
+    $rsm = new ResultSetMappingBuilder($entityManager);
+    $rsm->addRootEntityFromClassMetadata('MyProject\User', 'u');
+    $rsm->addJoinedEntityFromClassMetadata('MyProject\Address', 'a', 'u', 'address', array('id' => 'address_id'));
+
+The builder extends the ``ResultSetMapping`` class and as such has all the functionality of it as well.
+
+.. versionadded:: 2.4
+
+Starting with Doctrine ORM 2.4 you can generate the ``SELECT`` clause
+from a ``ResultSetMappingBuilder``. You can either cast the builder
+object to ``(string)`` and the DQL aliases are used as SQL table aliases
+or use the ``generateSelectClause($tableAliases)`` method and pass
+a mapping from DQL alias (key) to SQL alias (value)
+
+.. code-block:: php
+
+    <?php
+
+    $selectClause = $rsm->generateSelectClause(array(
+        'u' => 't1',
+        'g' => 't2'
+    ));
+    $sql = "SELECT " . $selectClause . " FROM users t1 JOIN groups t2 ON t1.group_id = t2.id";
+
+
+The ResultSetMapping
+--------------------
+
+Understanding the ``ResultSetMapping`` is the key to using a
+``NativeQuery``. A Doctrine result can contain the following
+components:
+
+
+-  Entity results. These represent root result elements.
+-  Joined entity results. These represent joined entities in
+   associations of root entity results.
+-  Field results. These represent a column in the result set that
+   maps to a field of an entity. A field result always belongs to an
+   entity result or joined entity result.
+-  Scalar results. These represent scalar values in the result set
+   that will appear in each result row. Adding scalar results to a
+   ResultSetMapping can also cause the overall result to become
+   **mixed** (see DQL - Doctrine Query Language) if the same
+   ResultSetMapping also contains entity results.
+-  Meta results. These represent columns that contain
+   meta-information, such as foreign keys and discriminator columns.
+   When querying for objects (``getResult()``), all meta columns of
+   root entities or joined entities must be present in the SQL query
+   and mapped accordingly using ``ResultSetMapping#addMetaResult``.
+
+.. note::
+
+    It might not surprise you that Doctrine uses
+    ``ResultSetMapping`` internally when you create DQL queries. As
+    the query gets parsed and transformed to SQL, Doctrine fills a
+    ``ResultSetMapping`` that describes how the results should be
+    processed by the hydration routines.
+
+
+We will now look at each of the result types that can appear in a
+ResultSetMapping in detail.
+
+Entity results
+~~~~~~~~~~~~~~
+
+An entity result describes an entity type that appears as a root
+element in the transformed result. You add an entity result through
+``ResultSetMapping#addEntityResult()``. Let's take a look at the
+method signature in detail:
+
+.. code-block:: php
+
+    <?php
+    /**
+     * Adds an entity result to this ResultSetMapping.
+     *
+     * @param string $class The class name of the entity.
+     * @param string $alias The alias for the class. The alias must be unique among all entity
+     *                      results or joined entity results within this ResultSetMapping.
+     */
+    public function addEntityResult($class, $alias)
+
+The first parameter is the fully qualified name of the entity
+class. The second parameter is some arbitrary alias for this entity
+result that must be unique within a ``ResultSetMapping``. You use
+this alias to attach field results to the entity result. It is very
+similar to an identification variable that you use in DQL to alias
+classes or relationships.
+
+An entity result alone is not enough to form a valid
+``ResultSetMapping``. An entity result or joined entity result
+always needs a set of field results, which we will look at soon.
+
+Joined entity results
+~~~~~~~~~~~~~~~~~~~~~
+
+A joined entity result describes an entity type that appears as a
+joined relationship element in the transformed result, attached to
+a (root) entity result. You add a joined entity result through
+``ResultSetMapping#addJoinedEntityResult()``. Let's take a look at
+the method signature in detail:
+
+.. code-block:: php
+
+    <?php
+    /**
+     * Adds a joined entity result.
+     *
+     * @param string $class The class name of the joined entity.
+     * @param string $alias The unique alias to use for the joined entity.
+     * @param string $parentAlias The alias of the entity result that is the parent of this joined result.
+     * @param object $relation The association field that connects the parent entity result with the joined entity result.
+     */
+    public function addJoinedEntityResult($class, $alias, $parentAlias, $relation)
+
+The first parameter is the class name of the joined entity. The
+second parameter is an arbitrary alias for the joined entity that
+must be unique within the ``ResultSetMapping``. You use this alias
+to attach field results to the entity result. The third parameter
+is the alias of the entity result that is the parent type of the
+joined relationship. The fourth and last parameter is the name of
+the field on the parent entity result that should contain the
+joined entity result.
+
+Field results
+~~~~~~~~~~~~~
+
+A field result describes the mapping of a single column in a SQL
+result set to a field in an entity. As such, field results are
+inherently bound to entity results. You add a field result through
+``ResultSetMapping#addFieldResult()``. Again, let's examine the
+method signature in detail:
+
+.. code-block:: php
+
+    <?php
+    /**
+     * Adds a field result that is part of an entity result or joined entity result.
+     *
+     * @param string $alias The alias of the entity result or joined entity result.
+     * @param string $columnName The name of the column in the SQL result set.
+     * @param string $fieldName The name of the field on the (joined) entity.
+     */
+    public function addFieldResult($alias, $columnName, $fieldName)
+
+The first parameter is the alias of the entity result to which the
+field result will belong. The second parameter is the name of the
+column in the SQL result set. Note that this name is case
+sensitive, i.e. if you use a native query against Oracle it must be
+all uppercase. The third parameter is the name of the field on the
+entity result identified by ``$alias`` into which the value of the
+column should be set.
+
+Scalar results
+~~~~~~~~~~~~~~
+
+A scalar result describes the mapping of a single column in a SQL
+result set to a scalar value in the Doctrine result. Scalar results
+are typically used for aggregate values but any column in the SQL
+result set can be mapped as a scalar value. To add a scalar result
+use ``ResultSetMapping#addScalarResult()``. The method signature in
+detail:
+
+.. code-block:: php
+
+    <?php
+    /**
+     * Adds a scalar result mapping.
+     *
+     * @param string $columnName The name of the column in the SQL result set.
+     * @param string $alias The result alias with which the scalar result should be placed in the result structure.
+     */
+    public function addScalarResult($columnName, $alias)
+
+The first parameter is the name of the column in the SQL result set
+and the second parameter is the result alias under which the value
+of the column will be placed in the transformed Doctrine result.
+
+Meta results
+~~~~~~~~~~~~
+
+A meta result describes a single column in a SQL result set that
+is either a foreign key or a discriminator column. These columns
+are essential for Doctrine to properly construct objects out of SQL
+result sets. To add a column as a meta result use
+``ResultSetMapping#addMetaResult()``. The method signature in
+detail:
+
+.. code-block:: php
+
+    <?php
+    /**
+     * Adds a meta column (foreign key or discriminator column) to the result set.
+     * 
+     * @param string  $alias
+     * @param string  $columnAlias
+     * @param string  $columnName
+     * @param boolean $isIdentifierColumn
+     */
+    public function addMetaResult($alias, $columnAlias, $columnName, $isIdentifierColumn = false)
+
+The first parameter is the alias of the entity result to which the
+meta column belongs. A meta result column (foreign key or
+discriminator column) always belongs to an entity result. The
+second parameter is the column alias/name of the column in the SQL
+result set and the third parameter is the column name used in the
+mapping.
+The fourth parameter should be set to true in case the primary key
+of the entity is the foreign key you're adding.
+
+Discriminator Column
+~~~~~~~~~~~~~~~~~~~~
+
+When joining an inheritance tree you have to give Doctrine a hint
+which meta-column is the discriminator column of this tree.
+
+.. code-block:: php
+
+    <?php
+    /**
+     * Sets a discriminator column for an entity result or joined entity result.
+     * The discriminator column will be used to determine the concrete class name to
+     * instantiate.
+     *
+     * @param string $alias The alias of the entity result or joined entity result the discriminator
+     *                      column should be used for.
+     * @param string $discrColumn The name of the discriminator column in the SQL result set.
+     */
+    public function setDiscriminatorColumn($alias, $discrColumn)
+
+Examples
+~~~~~~~~
+
+Understanding a ResultSetMapping is probably easiest through
+looking at some examples.
+
+First a basic example that describes the mapping of a single
+entity.
+
+.. code-block:: php
+
+    <?php
+    // Equivalent DQL query: "select u from User u where u.name=?1"
+    // User owns no associations.
+    $rsm = new ResultSetMapping;
+    $rsm->addEntityResult('User', 'u');
+    $rsm->addFieldResult('u', 'id', 'id');
+    $rsm->addFieldResult('u', 'name', 'name');
+    
+    $query = $this->_em->createNativeQuery('SELECT id, name FROM users WHERE name = ?', $rsm);
+    $query->setParameter(1, 'romanb');
+    
+    $users = $query->getResult();
+
+The result would look like this:
+
+.. code-block:: php
+
+    array(
+        [0] => User (Object)
+    )
+
+Note that this would be a partial object if the entity has more
+fields than just id and name. In the example above the column and
+field names are identical but that is not necessary, of course.
+Also note that the query string passed to createNativeQuery is
+**real native SQL**. Doctrine does not touch this SQL in any way.
+
+In the previous basic example, a User had no relations and the
+table the class is mapped to owns no foreign keys. The next example
+assumes User has a unidirectional or bidirectional one-to-one
+association to a CmsAddress, where the User is the owning side and
+thus owns the foreign key.
+
+.. code-block:: php
+
+    <?php
+    // Equivalent DQL query: "select u from User u where u.name=?1"
+    // User owns an association to an Address but the Address is not loaded in the query.
+    $rsm = new ResultSetMapping;
+    $rsm->addEntityResult('User', 'u');
+    $rsm->addFieldResult('u', 'id', 'id');
+    $rsm->addFieldResult('u', 'name', 'name');
+    $rsm->addMetaResult('u', 'address_id', 'address_id');
+    
+    $query = $this->_em->createNativeQuery('SELECT id, name, address_id FROM users WHERE name = ?', $rsm);
+    $query->setParameter(1, 'romanb');
+    
+    $users = $query->getResult();
+
+Foreign keys are used by Doctrine for lazy-loading purposes when
+querying for objects. In the previous example, each user object in
+the result will have a proxy (a "ghost") in place of the address
+that contains the address\_id. When the ghost proxy is accessed, it
+loads itself based on this key.
+
+Consequently, associations that are *fetch-joined* do not require
+the foreign keys to be present in the SQL result set, only
+associations that are lazy.
+
+.. code-block:: php
+
+    <?php
+    // Equivalent DQL query: "select u from User u join u.address a WHERE u.name = ?1"
+    // User owns association to an Address and the Address is loaded in the query.
+    $rsm = new ResultSetMapping;
+    $rsm->addEntityResult('User', 'u');
+    $rsm->addFieldResult('u', 'id', 'id');
+    $rsm->addFieldResult('u', 'name', 'name');
+    $rsm->addJoinedEntityResult('Address' , 'a', 'u', 'address');
+    $rsm->addFieldResult('a', 'address_id', 'id');
+    $rsm->addFieldResult('a', 'street', 'street');
+    $rsm->addFieldResult('a', 'city', 'city');
+    
+    $sql = 'SELECT u.id, u.name, a.id AS address_id, a.street, a.city FROM users u ' .
+           'INNER JOIN address a ON u.address_id = a.id WHERE u.name = ?';
+    $query = $this->_em->createNativeQuery($sql, $rsm);
+    $query->setParameter(1, 'romanb');
+    
+    $users = $query->getResult();
+
+In this case the nested entity ``Address`` is registered with the
+``ResultSetMapping#addJoinedEntityResult`` method, which notifies
+Doctrine that this entity is not hydrated at the root level, but as
+a joined entity somewhere inside the object graph. In this case we
+specify the alias 'u' as third parameter and ``address`` as fourth
+parameter, which means the ``Address`` is hydrated into the
+``User::$address`` property.
+
+If a fetched entity is part of a mapped hierarchy that requires a
+discriminator column, this column must be present in the result set
+as a meta column so that Doctrine can create the appropriate
+concrete type. This is shown in the following example where we
+assume that there are one or more subclasses that extend User and
+either Class Table Inheritance or Single Table Inheritance is used
+to map the hierarchy (both use a discriminator column).
+
+.. code-block:: php
+
+    <?php
+    // Equivalent DQL query: "select u from User u where u.name=?1"
+    // User is a mapped base class for other classes. User owns no associations.
+    $rsm = new ResultSetMapping;
+    $rsm->addEntityResult('User', 'u');
+    $rsm->addFieldResult('u', 'id', 'id');
+    $rsm->addFieldResult('u', 'name', 'name');
+    $rsm->addMetaResult('u', 'discr', 'discr'); // discriminator column
+    $rsm->setDiscriminatorColumn('u', 'discr');
+    
+    $query = $this->_em->createNativeQuery('SELECT id, name, discr FROM users WHERE name = ?', $rsm);
+    $query->setParameter(1, 'romanb');
+    
+    $users = $query->getResult();
+
+Note that in the case of Class Table Inheritance, an example as
+above would result in partial objects if any objects in the result
+are actually a subtype of User. When using DQL, Doctrine
+automatically includes the necessary joins for this mapping
+strategy but with native SQL it is your responsibility.
+
+Named Native Query
+------------------
+
+You can also map a native query using a named native query mapping.
+
+To achieve that, you must describe the SQL resultset structure
+using named native query (and sql resultset mappings if is a several resultset mappings).
+
+Like named query, a named native query can be defined at class level or in a XML or YAML file.
+
+
+A resultSetMapping parameter is defined in @NamedNativeQuery,
+it represents the name of a defined @SqlResultSetMapping.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Model;
+        /**
+         * @NamedNativeQueries({
+         *      @NamedNativeQuery(
+         *          name            = "fetchMultipleJoinsEntityResults",
+         *          resultSetMapping= "mappingMultipleJoinsEntityResults",
+         *          query           = "SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM users u INNER JOIN addresses a ON u.id = a.user_id INNER JOIN phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username"
+         *      ),
+         * })
+         * @SqlResultSetMappings({
+         *      @SqlResultSetMapping(
+         *          name    = "mappingMultipleJoinsEntityResults",
+         *          entities= {
+         *              @EntityResult(
+         *                  entityClass = "__CLASS__",
+         *                  fields      = {
+         *                      @FieldResult(name = "id",       column="u_id"),
+         *                      @FieldResult(name = "name",     column="u_name"),
+         *                      @FieldResult(name = "status",   column="u_status"),
+         *                  }
+         *              ),
+         *              @EntityResult(
+         *                  entityClass = "Address",
+         *                  fields      = {
+         *                      @FieldResult(name = "id",       column="a_id"),
+         *                      @FieldResult(name = "zip",      column="a_zip"),
+         *                      @FieldResult(name = "country",  column="a_country"),
+         *                  }
+         *              )
+         *          },
+         *          columns = {
+         *              @ColumnResult("numphones")
+         *          }
+         *      )
+         *})
+         */
+         class User
+        {
+            /** @Id @Column(type="integer") @GeneratedValue */
+            public $id;
+
+            /** @Column(type="string", length=50, nullable=true) */
+            public $status;
+
+            /** @Column(type="string", length=255, unique=true) */
+            public $username;
+
+            /** @Column(type="string", length=255) */
+            public $name;
+
+            /** @OneToMany(targetEntity="Phonenumber") */
+            public $phonenumbers;
+
+            /** @OneToOne(targetEntity="Address") */
+            public $address;
+
+            // ....
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\User">
+                <named-native-queries>
+                    <named-native-query name="fetchMultipleJoinsEntityResults" result-set-mapping="mappingMultipleJoinsEntityResults">
+                        <query>SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM users u INNER JOIN addresses a ON u.id = a.user_id INNER JOIN phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username</query>
+                    </named-native-query>
+                </named-native-queries>
+                <sql-result-set-mappings>
+                    <sql-result-set-mapping name="mappingMultipleJoinsEntityResults">
+                        <entity-result entity-class="__CLASS__">
+                            <field-result name="id" column="u_id"/>
+                            <field-result name="name" column="u_name"/>
+                            <field-result name="status" column="u_status"/>
+                        </entity-result>
+                        <entity-result entity-class="Address">
+                            <field-result name="id" column="a_id"/>
+                            <field-result name="zip" column="a_zip"/>
+                            <field-result name="country" column="a_country"/>
+                        </entity-result>
+                        <column-result name="numphones"/>
+                    </sql-result-set-mapping>
+                </sql-result-set-mappings>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Model\User:
+          type: entity
+          namedNativeQueries:
+            fetchMultipleJoinsEntityResults:
+              name: fetchMultipleJoinsEntityResults
+              resultSetMapping: mappingMultipleJoinsEntityResults
+              query: SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM users u INNER JOIN addresses a ON u.id = a.user_id INNER JOIN phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username
+          sqlResultSetMappings:
+            mappingMultipleJoinsEntityResults:
+              name: mappingMultipleJoinsEntityResults
+              columnResult:
+                0:
+                  name: numphones
+              entityResult:
+                0:
+                  entityClass: __CLASS__
+                  fieldResult:
+                    0:
+                      name: id
+                      column: u_id
+                    1:
+                      name: name
+                      column: u_name
+                    2:
+                      name: status
+                      column: u_status
+                1:
+                  entityClass: Address
+                  fieldResult:
+                    0:
+                      name: id
+                      column: a_id
+                    1:
+                      name: zip
+                      column: a_zip
+                    2:
+                      name: country
+                      column: a_country
+
+
+Things to note:
+    - The resultset mapping declares the entities retrieved by this native query.
+    - Each field of the entity is bound to a SQL alias (or column name).
+    - All fields of the entity including the ones of subclasses
+      and the foreign key columns of related entities have to be present in the SQL query.
+    - Field definitions are optional provided that they map to the same
+      column name as the one declared on the class property.
+    - ``__CLASS__`` is an alias for the mapped class
+
+
+In the above example,
+the ``fetchJoinedAddress`` named query use the joinMapping result set mapping.
+This mapping returns 2 entities, User and Address, each property is declared and associated to a column name,
+actually the column name retrieved by the query.
+
+Let's now see an implicit declaration of the property / column.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Model;
+            /**
+             * @NamedNativeQueries({
+             *      @NamedNativeQuery(
+             *          name                = "findAll",
+             *          resultSetMapping    = "mappingFindAll",
+             *          query               = "SELECT * FROM addresses"
+             *      ),
+             * })
+             * @SqlResultSetMappings({
+             *      @SqlResultSetMapping(
+             *          name    = "mappingFindAll",
+             *          entities= {
+             *              @EntityResult(
+             *                  entityClass = "Address"
+             *              )
+             *          }
+             *      )
+             * })
+             */
+           class Address
+           {
+                /**  @Id @Column(type="integer") @GeneratedValue */
+                public $id;
+
+                /** @Column() */
+                public $country;
+
+                /** @Column() */
+                public $zip;
+
+                /** @Column()*/
+                public $city;
+
+                // ....
+            }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\Address">
+                <named-native-queries>
+                    <named-native-query name="findAll" result-set-mapping="mappingFindAll">
+                        <query>SELECT * FROM addresses</query>
+                    </named-native-query>
+                </named-native-queries>
+                <sql-result-set-mappings>
+                    <sql-result-set-mapping name="mappingFindAll">
+                        <entity-result entity-class="Address"/>
+                    </sql-result-set-mapping>
+                </sql-result-set-mappings>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Model\Address:
+          type: entity
+          namedNativeQueries:
+            findAll:
+              resultSetMapping: mappingFindAll
+              query: SELECT * FROM addresses
+          sqlResultSetMappings:
+            mappingFindAll:
+              name: mappingFindAll
+              entityResult:
+                address:
+                  entityClass: Address
+
+
+In this example, we only describe the entity member of the result set mapping.
+The property / column mappings is done using the entity mapping values.
+In this case the model property is bound to the model_txt column.
+If the association to a related entity involve a composite primary key,
+a @FieldResult element should be used for each foreign key column.
+The @FieldResult name is composed of the property name for the relationship,
+followed by a dot ("."), followed by the name or the field or property of the primary key.
+
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Model;
+            /**
+             * @NamedNativeQueries({
+             *      @NamedNativeQuery(
+             *          name            = "fetchJoinedAddress",
+             *          resultSetMapping= "mappingJoinedAddress",
+             *          query           = "SELECT u.id, u.name, u.status, a.id AS a_id, a.country AS a_country, a.zip AS a_zip, a.city AS a_city FROM users u INNER JOIN addresses a ON u.id = a.user_id WHERE u.username = ?"
+             *      ),
+             * })
+             * @SqlResultSetMappings({
+             *      @SqlResultSetMapping(
+             *          name    = "mappingJoinedAddress",
+             *          entities= {
+             *              @EntityResult(
+             *                  entityClass = "__CLASS__",
+             *                  fields      = {
+             *                      @FieldResult(name = "id"),
+             *                      @FieldResult(name = "name"),
+             *                      @FieldResult(name = "status"),
+             *                      @FieldResult(name = "address.id", column = "a_id"),
+             *                      @FieldResult(name = "address.zip", column = "a_zip"),
+             *                      @FieldResult(name = "address.city", column = "a_city"),
+             *                      @FieldResult(name = "address.country", column = "a_country"),
+             *                  }
+             *              )
+             *          }
+             *      )
+             * })
+             */
+            class User
+            {
+                /** @Id @Column(type="integer") @GeneratedValue */
+                public $id;
+
+                /** @Column(type="string", length=50, nullable=true) */
+                public $status;
+
+                /** @Column(type="string", length=255, unique=true) */
+                public $username;
+
+                /** @Column(type="string", length=255) */
+                public $name;
+
+                /** @OneToOne(targetEntity="Address") */
+                public $address;
+
+                // ....
+            }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\User">
+                <named-native-queries>
+                    <named-native-query name="fetchJoinedAddress" result-set-mapping="mappingJoinedAddress">
+                        <query>SELECT u.id, u.name, u.status, a.id AS a_id, a.country AS a_country, a.zip AS a_zip, a.city AS a_city FROM users u INNER JOIN addresses a ON u.id = a.user_id WHERE u.username = ?</query>
+                    </named-native-query>
+                </named-native-queries>
+                <sql-result-set-mappings>
+                    <sql-result-set-mapping name="mappingJoinedAddress">
+                        <entity-result entity-class="__CLASS__">
+                            <field-result name="id"/>
+                            <field-result name="name"/>
+                            <field-result name="status"/>
+                            <field-result name="address.id" column="a_id"/>
+                            <field-result name="address.zip"  column="a_zip"/>
+                            <field-result name="address.city"  column="a_city"/>
+                            <field-result name="address.country" column="a_country"/>
+                        </entity-result>
+                    </sql-result-set-mapping>
+                </sql-result-set-mappings>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Model\User:
+          type: entity
+          namedNativeQueries:
+            fetchJoinedAddress:
+              name: fetchJoinedAddress
+              resultSetMapping: mappingJoinedAddress
+              query: SELECT u.id, u.name, u.status, a.id AS a_id, a.country AS a_country, a.zip AS a_zip, a.city AS a_city FROM users u INNER JOIN addresses a ON u.id = a.user_id WHERE u.username = ?
+          sqlResultSetMappings:
+            mappingJoinedAddress:
+              entityResult:
+                0:
+                  entityClass: __CLASS__
+                  fieldResult:
+                    0:
+                      name: id
+                    1:
+                      name: name
+                    2:
+                      name: status
+                    3:
+                      name: address.id
+                      column: a_id
+                    4:
+                      name: address.zip
+                      column: a_zip
+                    5:
+                      name: address.city
+                      column: a_city
+                    6:
+                      name: address.country
+                      column: a_country
+                    
+
+
+If you retrieve a single entity and if you use the default mapping,
+you can use the resultClass attribute instead of resultSetMapping:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Model;
+            /**
+             * @NamedNativeQueries({
+             *      @NamedNativeQuery(
+             *          name           = "find-by-id",
+             *          resultClass    = "Address",
+             *          query          = "SELECT * FROM addresses"
+             *      ),
+             * })
+             */
+           class Address
+           {
+                // ....
+           }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\Address">
+                <named-native-queries>
+                    <named-native-query name="find-by-id" result-class="Address">
+                        <query>SELECT * FROM addresses WHERE id = ?</query>
+                    </named-native-query>
+                </named-native-queries>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Model\Address:
+          type: entity
+          namedNativeQueries:
+            findAll:
+              name: findAll
+              resultClass: Address
+              query: SELECT * FROM addresses
+
+
+In some of your native queries, you'll have to return scalar values,
+for example when building report queries.
+You can map them in the @SqlResultsetMapping through @ColumnResult.
+You actually can even mix, entities and scalar returns in the same native query (this is probably not that common though).
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Model;
+            /**
+             * @NamedNativeQueries({
+             *      @NamedNativeQuery(
+             *          name            = "count",
+             *          resultSetMapping= "mappingCount",
+             *          query           = "SELECT COUNT(*) AS count FROM addresses"
+             *      )
+             * })
+             * @SqlResultSetMappings({
+             *      @SqlResultSetMapping(
+             *          name    = "mappingCount",
+             *          columns = {
+             *              @ColumnResult(
+             *                  name = "count"
+             *              )
+             *          }
+             *      )
+             * })
+             */
+           class Address
+           {
+                // ....
+           }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\Address">
+                <named-native-query name="count" result-set-mapping="mappingCount">
+                    <query>SELECT COUNT(*) AS count FROM addresses</query>
+                </named-native-query>
+                <sql-result-set-mappings>
+                    <sql-result-set-mapping name="mappingCount">
+                        <column-result name="count"/>
+                    </sql-result-set-mapping>
+                </sql-result-set-mappings>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Model\Address:
+          type: entity
+          namedNativeQueries:
+            count:
+              name: count
+              resultSetMapping: mappingCount
+              query: SELECT COUNT(*) AS count FROM addresses
+          sqlResultSetMappings:
+            mappingCount:
+              name: mappingCount
+              columnResult:
+                count:
+                  name: count

vendor/doctrine/orm/docs/en/reference/partial-objects.rst

@@ -0,0 +1,90 @@
+Partial Objects
+===============
+
+A partial object is an object whose state is not fully initialized
+after being reconstituted from the database and that is
+disconnected from the rest of its data. The following section will
+describe why partial objects are problematic and what the approach
+of Doctrine2 to this problem is.
+
+.. note::
+
+    The partial object problem in general does not apply to
+    methods or queries where you do not retrieve the query result as
+    objects. Examples are: ``Query#getArrayResult()``,
+    ``Query#getScalarResult()``, ``Query#getSingleScalarResult()``,
+    etc.
+
+.. warning::
+
+    Use of partial objects is tricky. Fields that are not retrieved
+    from the database will not be updated by the UnitOfWork even if they
+    get changed in your objects. You can only promote a partial object
+    to a fully-loaded object by calling ``EntityManager#refresh()``
+    or a DQL query with the refresh flag.
+
+
+What is the problem?
+--------------------
+
+In short, partial objects are problematic because they are usually
+objects with broken invariants. As such, code that uses these
+partial objects tends to be very fragile and either needs to "know"
+which fields or methods can be safely accessed or add checks around
+every field access or method invocation. The same holds true for
+the internals, i.e. the method implementations, of such objects.
+You usually simply assume the state you need in the method is
+available, after all you properly constructed this object before
+you pushed it into the database, right? These blind assumptions can
+quickly lead to null reference errors when working with such
+partial objects.
+
+It gets worse with the scenario of an optional association (0..1 to
+1). When the associated field is NULL, you don't know whether this
+object does not have an associated object or whether it was simply
+not loaded when the owning object was loaded from the database.
+
+These are reasons why many ORMs do not allow partial objects at all
+and instead you always have to load an object with all its fields
+(associations being proxied). One secure way to allow partial
+objects is if the programming language/platform allows the ORM tool
+to hook deeply into the object and instrument it in such a way that
+individual fields (not only associations) can be loaded lazily on
+first access. This is possible in Java, for example, through
+bytecode instrumentation. In PHP though this is not possible, so
+there is no way to have "secure" partial objects in an ORM with
+transparent persistence.
+
+Doctrine, by default, does not allow partial objects. That means,
+any query that only selects partial object data and wants to
+retrieve the result as objects (i.e. ``Query#getResult()``) will
+raise an exception telling you that partial objects are dangerous.
+If you want to force a query to return you partial objects,
+possibly as a performance tweak, you can use the ``partial``
+keyword as follows:
+
+.. code-block:: php
+
+    <?php
+    $q = $em->createQuery("select partial u.{id,name} from MyApp\Domain\User u");
+
+You can also get a partial reference instead of a proxy reference by
+calling:
+
+.. code-block:: php
+
+    <?php
+    $reference = $em->getPartialReference('MyApp\Domain\User', 1);
+
+Partial references are objects with only the identifiers set as they
+are passed to the second argument of the ``getPartialReference()`` method.
+All other fields are null.
+
+When should I force partial objects?
+------------------------------------
+
+Mainly for optimization purposes, but be careful of premature
+optimization as partial objects lead to potentially more fragile
+code.
+
+

vendor/doctrine/orm/docs/en/reference/php-mapping.rst

@@ -0,0 +1,325 @@
+PHP Mapping
+===========
+
+Doctrine 2 also allows you to provide the ORM metadata in the form
+of plain PHP code using the ``ClassMetadata`` API. You can write
+the code in PHP files or inside of a static function named
+``loadMetadata($class)`` on the entity class itself.
+
+PHP Files
+---------
+
+If you wish to write your mapping information inside PHP files that
+are named after the entity and included to populate the metadata
+for an entity you can do so by using the ``PHPDriver``:
+
+.. code-block:: php
+
+    <?php
+    $driver = new PHPDriver('/path/to/php/mapping/files');
+    $em->getConfiguration()->setMetadataDriverImpl($driver);
+
+Now imagine we had an entity named ``Entities\User`` and we wanted
+to write a mapping file for it using the above configured
+``PHPDriver`` instance:
+
+.. code-block:: php
+
+    <?php
+    namespace Entities;
+
+    class User
+    {
+        private $id;
+        private $username;
+    }
+
+To write the mapping information you just need to create a file
+named ``Entities.User.php`` inside of the
+``/path/to/php/mapping/files`` folder:
+
+.. code-block:: php
+
+    <?php
+    // /path/to/php/mapping/files/Entities.User.php
+
+    $metadata->mapField(array(
+       'id' => true,
+       'fieldName' => 'id',
+       'type' => 'integer'
+    ));
+
+    $metadata->mapField(array(
+       'fieldName' => 'username',
+       'type' => 'string',
+       'options' => array(
+           'fixed' => true,
+           'comment' => "User's login name"
+       )
+    ));
+
+    $metadata->mapField(array(
+       'fieldName' => 'login_count',
+       'type' => 'integer',
+       'nullable' => false,
+       'options' => array(
+           'unsigned' => true,
+           'default' => 0
+       )
+    ));
+
+Now we can easily retrieve the populated ``ClassMetadata`` instance
+where the ``PHPDriver`` includes the file and the
+``ClassMetadataFactory`` caches it for later retrieval:
+
+.. code-block:: php
+
+    <?php
+    $class = $em->getClassMetadata('Entities\User');
+    // or
+    $class = $em->getMetadataFactory()->getMetadataFor('Entities\User');
+
+Static Function
+---------------
+
+In addition to the PHP files you can also specify your mapping
+information inside of a static function defined on the entity class
+itself. This is useful for cases where you want to keep your entity
+and mapping information together but don't want to use annotations.
+For this you just need to use the ``StaticPHPDriver``:
+
+.. code-block:: php
+
+    <?php
+    $driver = new StaticPHPDriver('/path/to/entities');
+    $em->getConfiguration()->setMetadataDriverImpl($driver);
+
+Now you just need to define a static function named
+``loadMetadata($metadata)`` on your entity:
+
+.. code-block:: php
+
+    <?php
+    namespace Entities;
+
+    use Doctrine\ORM\Mapping\ClassMetadata;
+
+    class User
+    {
+        // ...
+
+        public static function loadMetadata(ClassMetadata $metadata)
+        {
+            $metadata->mapField(array(
+               'id' => true,
+               'fieldName' => 'id',
+               'type' => 'integer'
+            ));
+
+            $metadata->mapField(array(
+               'fieldName' => 'username',
+               'type' => 'string'
+            ));
+        }
+    }
+
+ClassMetadataBuilder
+--------------------
+
+To ease the use of the ClassMetadata API (which is very raw) there is a ``ClassMetadataBuilder`` that you can use.
+
+.. code-block:: php
+
+    <?php
+    namespace Entities;
+
+    use Doctrine\ORM\Mapping\ClassMetadata;
+    use Doctrine\ORM\Mapping\Builder\ClassMetadataBuilder;
+
+    class User
+    {
+        // ...
+
+        public static function loadMetadata(ClassMetadata $metadata)
+        {
+            $builder = new ClassMetadataBuilder($metadata);
+            $builder->createField('id', 'integer')->isPrimaryKey()->generatedValue()->build();
+            $builder->addField('username', 'string');
+        }
+    }
+
+The API of the ClassMetadataBuilder has the following methods with a fluent interface:
+
+-   ``addField($name, $type, array $mapping)``
+-   ``setMappedSuperclass()``
+-   ``setReadOnly()``
+-   ``setCustomRepositoryClass($className)``
+-   ``setTable($name)``
+-   ``addIndex(array $columns, $indexName)``
+-   ``addUniqueConstraint(array $columns, $constraintName)``
+-   ``addNamedQuery($name, $dqlQuery)``
+-   ``setJoinedTableInheritance()``
+-   ``setSingleTableInheritance()``
+-   ``setDiscriminatorColumn($name, $type = 'string', $length = 255)``
+-   ``addDiscriminatorMapClass($name, $class)``
+-   ``setChangeTrackingPolicyDeferredExplicit()``
+-   ``setChangeTrackingPolicyNotify()``
+-   ``addLifecycleEvent($methodName, $event)``
+-   ``addManyToOne($name, $targetEntity, $inversedBy = null)``
+-   ``addInverseOneToOne($name, $targetEntity, $mappedBy)``
+-   ``addOwningOneToOne($name, $targetEntity, $inversedBy = null)``
+-   ``addOwningManyToMany($name, $targetEntity, $inversedBy = null)``
+-   ``addInverseManyToMany($name, $targetEntity, $mappedBy)``
+-   ``addOneToMany($name, $targetEntity, $mappedBy)``
+
+It also has several methods that create builders (which are necessary for advanced mappings):
+
+-   ``createField($name, $type)`` returns a ``FieldBuilder`` instance
+-   ``createManyToOne($name, $targetEntity)`` returns an ``AssociationBuilder`` instance
+-   ``createOneToOne($name, $targetEntity)`` returns an ``AssociationBuilder`` instance
+-   ``createManyToMany($name, $targetEntity)`` returns an ``ManyToManyAssociationBuilder`` instance
+-   ``createOneToMany($name, $targetEntity)`` returns an ``OneToManyAssociationBuilder`` instance
+
+ClassMetadataInfo API
+---------------------
+
+The ``ClassMetadataInfo`` class is the base data object for storing
+the mapping metadata for a single entity. It contains all the
+getters and setters you need populate and retrieve information for
+an entity.
+
+General Setters
+~~~~~~~~~~~~~~~
+
+
+-  ``setTableName($tableName)``
+-  ``setPrimaryTable(array $primaryTableDefinition)``
+-  ``setCustomRepositoryClass($repositoryClassName)``
+-  ``setIdGeneratorType($generatorType)``
+-  ``setIdGenerator($generator)``
+-  ``setSequenceGeneratorDefinition(array $definition)``
+-  ``setChangeTrackingPolicy($policy)``
+-  ``setIdentifier(array $identifier)``
+
+Inheritance Setters
+~~~~~~~~~~~~~~~~~~~
+
+
+-  ``setInheritanceType($type)``
+-  ``setSubclasses(array $subclasses)``
+-  ``setParentClasses(array $classNames)``
+-  ``setDiscriminatorColumn($columnDef)``
+-  ``setDiscriminatorMap(array $map)``
+
+Field Mapping Setters
+~~~~~~~~~~~~~~~~~~~~~
+
+
+-  ``mapField(array $mapping)``
+-  ``mapOneToOne(array $mapping)``
+-  ``mapOneToMany(array $mapping)``
+-  ``mapManyToOne(array $mapping)``
+-  ``mapManyToMany(array $mapping)``
+
+Lifecycle Callback Setters
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+-  ``addLifecycleCallback($callback, $event)``
+-  ``setLifecycleCallbacks(array $callbacks)``
+
+Versioning Setters
+~~~~~~~~~~~~~~~~~~
+
+
+-  ``setVersionMapping(array &$mapping)``
+-  ``setVersioned($bool)``
+-  ``setVersionField()``
+
+General Getters
+~~~~~~~~~~~~~~~
+
+
+-  ``getTableName()``
+-  ``getSchemaName()``
+-  ``getTemporaryIdTableName()``
+
+Identifier Getters
+~~~~~~~~~~~~~~~~~~
+
+
+-  ``getIdentifierColumnNames()``
+-  ``usesIdGenerator()``
+-  ``isIdentifier($fieldName)``
+-  ``isIdGeneratorIdentity()``
+-  ``isIdGeneratorSequence()``
+-  ``isIdGeneratorTable()``
+-  ``isIdentifierNatural()``
+-  ``getIdentifierFieldNames()``
+-  ``getSingleIdentifierFieldName()``
+-  ``getSingleIdentifierColumnName()``
+
+Inheritance Getters
+~~~~~~~~~~~~~~~~~~~
+
+
+-  ``isInheritanceTypeNone()``
+-  ``isInheritanceTypeJoined()``
+-  ``isInheritanceTypeSingleTable()``
+-  ``isInheritanceTypeTablePerClass()``
+-  ``isInheritedField($fieldName)``
+-  ``isInheritedAssociation($fieldName)``
+
+Change Tracking Getters
+~~~~~~~~~~~~~~~~~~~~~~~
+
+
+-  ``isChangeTrackingDeferredExplicit()``
+-  ``isChangeTrackingDeferredImplicit()``
+-  ``isChangeTrackingNotify()``
+
+Field & Association Getters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+-  ``isUniqueField($fieldName)``
+-  ``isNullable($fieldName)``
+-  ``getColumnName($fieldName)``
+-  ``getFieldMapping($fieldName)``
+-  ``getAssociationMapping($fieldName)``
+-  ``getAssociationMappings()``
+-  ``getFieldName($columnName)``
+-  ``hasField($fieldName)``
+-  ``getColumnNames(array $fieldNames = null)``
+-  ``getTypeOfField($fieldName)``
+-  ``getTypeOfColumn($columnName)``
+-  ``hasAssociation($fieldName)``
+-  ``isSingleValuedAssociation($fieldName)``
+-  ``isCollectionValuedAssociation($fieldName)``
+
+Lifecycle Callback Getters
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+-  ``hasLifecycleCallbacks($lifecycleEvent)``
+-  ``getLifecycleCallbacks($event)``
+
+ClassMetadata API
+-----------------
+
+The ``ClassMetadata`` class extends ``ClassMetadataInfo`` and adds
+the runtime functionality required by Doctrine. It adds a few extra
+methods related to runtime reflection for working with the entities
+themselves.
+
+
+-  ``getReflectionClass()``
+-  ``getReflectionProperties()``
+-  ``getReflectionProperty($name)``
+-  ``getSingleIdReflectionProperty()``
+-  ``getIdentifierValues($entity)``
+-  ``setIdentifierValues($entity, $id)``
+-  ``setFieldValue($entity, $field, $value)``
+-  ``getFieldValue($entity, $field)``
+
+

vendor/doctrine/orm/docs/en/reference/query-builder.rst

@@ -0,0 +1,598 @@
+The QueryBuilder
+================
+
+A ``QueryBuilder`` provides an API that is designed for
+conditionally constructing a DQL query in several steps.
+
+It provides a set of classes and methods that is able to
+programmatically build queries, and also provides a fluent API.
+This means that you can change between one methodology to the other
+as you want, or just pick a preferred one.
+
+.. note::
+
+    The ``QueryBuilder`` is not an abstraction of DQL, but merely a tool to dynamically build it.
+    You should still use plain DQL when you can, as it is simpler and more readable.
+    More about this in the :doc:`FAQ <faq>`_.
+
+Constructing a new QueryBuilder object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The same way you build a normal Query, you build a ``QueryBuilder``
+object. Here is an example of how to build a ``QueryBuilder``
+object:
+
+.. code-block:: php
+
+    <?php
+    // $em instanceof EntityManager
+
+    // example1: creating a QueryBuilder instance
+    $qb = $em->createQueryBuilder();
+
+An instance of QueryBuilder has several informative methods.  One
+good example is to inspect what type of object the
+``QueryBuilder`` is.
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+
+    // example2: retrieving type of QueryBuilder
+    echo $qb->getType(); // Prints: 0
+
+There're currently 3 possible return values for ``getType()``:
+
+
+-  ``QueryBuilder::SELECT``, which returns value 0
+-  ``QueryBuilder::DELETE``, returning value 1
+-  ``QueryBuilder::UPDATE``, which returns value 2
+
+It is possible to retrieve the associated ``EntityManager`` of the
+current ``QueryBuilder``, its DQL and also a ``Query`` object when
+you finish building your DQL.
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+
+    // example3: retrieve the associated EntityManager
+    $em = $qb->getEntityManager();
+
+    // example4: retrieve the DQL string of what was defined in QueryBuilder
+    $dql = $qb->getDql();
+
+    // example5: retrieve the associated Query object with the processed DQL
+    $q = $qb->getQuery();
+
+Internally, ``QueryBuilder`` works with a DQL cache to increase
+performance. Any changes that may affect the generated DQL actually
+modifies the state of ``QueryBuilder`` to a stage we call
+STATE\_DIRTY. One ``QueryBuilder`` can be in two different states:
+
+
+-  ``QueryBuilder::STATE_CLEAN``, which means DQL haven't been
+   altered since last retrieval or nothing were added since its
+   instantiation
+-  ``QueryBuilder::STATE_DIRTY``, means DQL query must (and will)
+   be processed on next retrieval
+
+Working with QueryBuilder
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+High level API methods
+^^^^^^^^^^^^^^^^^^^^^^
+
+The most straightforward way to build a dynamic query with the ``QueryBuilder`` is by taking
+advantage of Helper methods. For all base code, there is a set of
+useful methods to simplify a programmer's life. To illustrate how
+to work with them, here is the same example 6 re-written using
+``QueryBuilder`` helper methods:
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+
+    $qb->select('u')
+       ->from('User', 'u')
+       ->where('u.id = ?1')
+       ->orderBy('u.name', 'ASC');
+
+``QueryBuilder`` helper methods are considered the standard way to
+use the ``QueryBuilder``. The ``$qb->expr()->*`` methods can help you
+build conditional expressions dynamically. Here is a converted example 8 to
+suggested way to build queries with dynamic conditions:
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+
+    $qb->select(array('u')) // string 'u' is converted to array internally
+       ->from('User', 'u')
+       ->where($qb->expr()->orX(
+           $qb->expr()->eq('u.id', '?1'),
+           $qb->expr()->like('u.nickname', '?2')
+       ))
+       ->orderBy('u.surname', 'ASC');
+
+Here is a complete list of helper methods available in ``QueryBuilder``:
+
+.. code-block:: php
+
+    <?php
+    class QueryBuilder
+    {
+        // Example - $qb->select('u')
+        // Example - $qb->select(array('u', 'p'))
+        // Example - $qb->select($qb->expr()->select('u', 'p'))
+        public function select($select = null);
+
+        // addSelect does not override previous calls to select
+        //
+        // Example - $qb->select('u');
+        //              ->addSelect('p.area_code');
+        public function addSelect($select = null);
+
+        // Example - $qb->delete('User', 'u')
+        public function delete($delete = null, $alias = null);
+
+        // Example - $qb->update('Group', 'g')
+        public function update($update = null, $alias = null);
+
+        // Example - $qb->set('u.firstName', $qb->expr()->literal('Arnold'))
+        // Example - $qb->set('u.numChilds', 'u.numChilds + ?1')
+        // Example - $qb->set('u.numChilds', $qb->expr()->sum('u.numChilds', '?1'))
+        public function set($key, $value);
+
+        // Example - $qb->from('Phonenumber', 'p')
+        // Example - $qb->from('Phonenumber', 'p', 'p.id')
+        public function from($from, $alias, $indexBy = null);
+
+        // Example - $qb->join('u.Group', 'g', Expr\Join::WITH, $qb->expr()->eq('u.status_id', '?1'))
+        // Example - $qb->join('u.Group', 'g', 'WITH', 'u.status = ?1')
+        // Example - $qb->join('u.Group', 'g', 'WITH', 'u.status = ?1', 'g.id')
+        public function join($join, $alias, $conditionType = null, $condition = null, $indexBy = null);
+
+        // Example - $qb->innerJoin('u.Group', 'g', Expr\Join::WITH, $qb->expr()->eq('u.status_id', '?1'))
+        // Example - $qb->innerJoin('u.Group', 'g', 'WITH', 'u.status = ?1')
+        // Example - $qb->innerJoin('u.Group', 'g', 'WITH', 'u.status = ?1', 'g.id')
+        public function innerJoin($join, $alias, $conditionType = null, $condition = null, $indexBy = null);
+
+        // Example - $qb->leftJoin('u.Phonenumbers', 'p', Expr\Join::WITH, $qb->expr()->eq('p.area_code', 55))
+        // Example - $qb->leftJoin('u.Phonenumbers', 'p', 'WITH', 'p.area_code = 55')
+        // Example - $qb->leftJoin('u.Phonenumbers', 'p', 'WITH', 'p.area_code = 55', 'p.id')
+        public function leftJoin($join, $alias, $conditionType = null, $condition = null, $indexBy = null);
+
+        // NOTE: ->where() overrides all previously set conditions
+        //
+        // Example - $qb->where('u.firstName = ?1', $qb->expr()->eq('u.surname', '?2'))
+        // Example - $qb->where($qb->expr()->andX($qb->expr()->eq('u.firstName', '?1'), $qb->expr()->eq('u.surname', '?2')))
+        // Example - $qb->where('u.firstName = ?1 AND u.surname = ?2')
+        public function where($where);
+
+        // NOTE: ->andWhere() can be used directly, without any ->where() before
+        //
+        // Example - $qb->andWhere($qb->expr()->orX($qb->expr()->lte('u.age', 40), 'u.numChild = 0'))
+        public function andWhere($where);
+
+        // Example - $qb->orWhere($qb->expr()->between('u.id', 1, 10));
+        public function orWhere($where);
+
+        // NOTE: -> groupBy() overrides all previously set grouping conditions
+        //
+        // Example - $qb->groupBy('u.id')
+        public function groupBy($groupBy);
+
+        // Example - $qb->addGroupBy('g.name')
+        public function addGroupBy($groupBy);
+
+        // NOTE: -> having() overrides all previously set having conditions
+        //
+        // Example - $qb->having('u.salary >= ?1')
+        // Example - $qb->having($qb->expr()->gte('u.salary', '?1'))
+        public function having($having);
+
+        // Example - $qb->andHaving($qb->expr()->gt($qb->expr()->count('u.numChild'), 0))
+        public function andHaving($having);
+
+        // Example - $qb->orHaving($qb->expr()->lte('g.managerLevel', '100'))
+        public function orHaving($having);
+
+        // NOTE: -> orderBy() overrides all previously set ordering conditions
+        //
+        // Example - $qb->orderBy('u.surname', 'DESC')
+        public function orderBy($sort, $order = null);
+
+        // Example - $qb->addOrderBy('u.firstName')
+        public function addOrderBy($sort, $order = null); // Default $order = 'ASC'
+    }
+
+Binding parameters to your query
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Doctrine supports dynamic binding of parameters to your query,
+similar to preparing queries. You can use both strings and numbers
+as placeholders, although both have a slightly different syntax.
+Additionally, you must make your choice: Mixing both styles is not
+allowed. Binding parameters can simply be achieved as follows:
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+
+    $qb->select('u')
+       ->from('User', 'u')
+       ->where('u.id = ?1')
+       ->orderBy('u.name', 'ASC')
+       ->setParameter(1, 100); // Sets ?1 to 100, and thus we will fetch a user with u.id = 100
+
+You are not forced to enumerate your placeholders as the
+alternative syntax is available:
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+
+    $qb->select('u')
+       ->from('User', 'u')
+       ->where('u.id = :identifier')
+       ->orderBy('u.name', 'ASC')
+       ->setParameter('identifier', 100); // Sets :identifier to 100, and thus we will fetch a user with u.id = 100
+
+Note that numeric placeholders start with a ? followed by a number
+while the named placeholders start with a : followed by a string.
+
+Calling ``setParameter()`` automatically infers which type you are setting as
+value. This works for integers, arrays of strings/integers, DateTime instances
+and for managed entities. If you want to set a type explicitly you can call
+the third argument to ``setParameter()`` explicitly. It accepts either a PDO
+type or a DBAL Type name for conversion.
+
+.. note::
+
+    Even though passing DateTime instance is allowed, it impacts performance 
+    as by default there is an attempt to load metadata for object, and if it's not found, 
+    type is inferred from the original value.
+    
+.. code-block:: php
+
+    <?php
+    
+    use Doctrine\DBAL\Types\Types;
+    
+    // prevents attempt to load metadata for date time class, improving performance
+    $qb->setParameter('date', new \DateTimeImmutable(), Types::DATE_IMMUTABLE)
+
+If you've got several parameters to bind to your query, you can
+also use setParameters() instead of setParameter() with the
+following syntax:
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+
+    // Query here...
+    $qb->setParameters(array(1 => 'value for ?1', 2 => 'value for ?2'));
+
+Getting already bound parameters is easy - simply use the above
+mentioned syntax with "getParameter()" or "getParameters()":
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+
+    // See example above
+    $params = $qb->getParameters();
+    // $params instanceof \Doctrine\Common\Collections\ArrayCollection
+
+    // Equivalent to
+    $param = $qb->getParameter(1);
+    // $param instanceof \Doctrine\ORM\Query\Parameter
+
+Note: If you try to get a parameter that was not bound yet,
+getParameter() simply returns NULL.
+
+The API of a Query Parameter is:
+
+.. code-block:: php
+
+    namespace Doctrine\ORM\Query;
+
+    class Parameter
+    {
+        public function getName();
+        public function getValue();
+        public function getType();
+        public function setValue($value, $type = null);
+    }
+
+Limiting the Result
+^^^^^^^^^^^^^^^^^^^
+
+To limit a result the query builder has some methods in common with
+the Query object which can be retrieved from ``EntityManager#createQuery()``.
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+    $offset = (int)$_GET['offset'];
+    $limit = (int)$_GET['limit'];
+
+    $qb->add('select', 'u')
+       ->add('from', 'User u')
+       ->add('orderBy', 'u.name ASC')
+       ->setFirstResult( $offset )
+       ->setMaxResults( $limit );
+
+Executing a Query
+^^^^^^^^^^^^^^^^^
+
+The QueryBuilder is a builder object only -  it has no means of actually
+executing the Query. Additionally a set of parameters such as query hints
+cannot be set on the QueryBuilder itself. This is why you always have to convert
+a querybuilder instance into a Query object:
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+    $query = $qb->getQuery();
+
+    // Set additional Query options
+    $query->setQueryHint('foo', 'bar');
+    $query->useResultCache('my_cache_id');
+
+    // Execute Query
+    $result = $query->getResult();
+    $single = $query->getSingleResult();
+    $array = $query->getArrayResult();
+    $scalar = $query->getScalarResult();
+    $singleScalar = $query->getSingleScalarResult();
+
+The Expr class
+^^^^^^^^^^^^^^
+
+To workaround some of the issues that ``add()`` method may cause,
+Doctrine created a class that can be considered as a helper for
+building expressions. This class is called ``Expr``, which provides a
+set of useful methods to help build expressions:
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+
+    // example8: QueryBuilder port of:
+    // "SELECT u FROM User u WHERE u.id = ? OR u.nickname LIKE ? ORDER BY u.name ASC" using Expr class
+    $qb->add('select', new Expr\Select(array('u')))
+       ->add('from', new Expr\From('User', 'u'))
+       ->add('where', $qb->expr()->orX(
+           $qb->expr()->eq('u.id', '?1'),
+           $qb->expr()->like('u.nickname', '?2')
+       ))
+       ->add('orderBy', new Expr\OrderBy('u.name', 'ASC'));
+
+Although it still sounds complex, the ability to programmatically
+create conditions are the main feature of ``Expr``. Here it is a
+complete list of supported helper methods available:
+
+.. code-block:: php
+
+    <?php
+    class Expr
+    {
+        /** Conditional objects **/
+
+        // Example - $qb->expr()->andX($cond1 [, $condN])->add(...)->...
+        public function andX($x = null); // Returns Expr\AndX instance
+
+        // Example - $qb->expr()->orX($cond1 [, $condN])->add(...)->...
+        public function orX($x = null); // Returns Expr\OrX instance
+
+
+        /** Comparison objects **/
+
+        // Example - $qb->expr()->eq('u.id', '?1') => u.id = ?1
+        public function eq($x, $y); // Returns Expr\Comparison instance
+
+        // Example - $qb->expr()->neq('u.id', '?1') => u.id <> ?1
+        public function neq($x, $y); // Returns Expr\Comparison instance
+
+        // Example - $qb->expr()->lt('u.id', '?1') => u.id < ?1
+        public function lt($x, $y); // Returns Expr\Comparison instance
+
+        // Example - $qb->expr()->lte('u.id', '?1') => u.id <= ?1
+        public function lte($x, $y); // Returns Expr\Comparison instance
+
+        // Example - $qb->expr()->gt('u.id', '?1') => u.id > ?1
+        public function gt($x, $y); // Returns Expr\Comparison instance
+
+        // Example - $qb->expr()->gte('u.id', '?1') => u.id >= ?1
+        public function gte($x, $y); // Returns Expr\Comparison instance
+
+        // Example - $qb->expr()->isNull('u.id') => u.id IS NULL
+        public function isNull($x); // Returns string
+
+        // Example - $qb->expr()->isNotNull('u.id') => u.id IS NOT NULL
+        public function isNotNull($x); // Returns string
+
+
+        /** Arithmetic objects **/
+
+        // Example - $qb->expr()->prod('u.id', '2') => u.id * 2
+        public function prod($x, $y); // Returns Expr\Math instance
+
+        // Example - $qb->expr()->diff('u.id', '2') => u.id - 2
+        public function diff($x, $y); // Returns Expr\Math instance
+
+        // Example - $qb->expr()->sum('u.id', '2') => u.id + 2
+        public function sum($x, $y); // Returns Expr\Math instance
+
+        // Example - $qb->expr()->quot('u.id', '2') => u.id / 2
+        public function quot($x, $y); // Returns Expr\Math instance
+
+
+        /** Pseudo-function objects **/
+
+        // Example - $qb->expr()->exists($qb2->getDql())
+        public function exists($subquery); // Returns Expr\Func instance
+
+        // Example - $qb->expr()->all($qb2->getDql())
+        public function all($subquery); // Returns Expr\Func instance
+
+        // Example - $qb->expr()->some($qb2->getDql())
+        public function some($subquery); // Returns Expr\Func instance
+
+        // Example - $qb->expr()->any($qb2->getDql())
+        public function any($subquery); // Returns Expr\Func instance
+
+        // Example - $qb->expr()->not($qb->expr()->eq('u.id', '?1'))
+        public function not($restriction); // Returns Expr\Func instance
+
+        // Example - $qb->expr()->in('u.id', array(1, 2, 3))
+        // Make sure that you do NOT use something similar to $qb->expr()->in('value', array('stringvalue')) as this will cause Doctrine to throw an Exception.
+        // Instead, use $qb->expr()->in('value', array('?1')) and bind your parameter to ?1 (see section above)
+        public function in($x, $y); // Returns Expr\Func instance
+
+        // Example - $qb->expr()->notIn('u.id', '2')
+        public function notIn($x, $y); // Returns Expr\Func instance
+
+        // Example - $qb->expr()->like('u.firstname', $qb->expr()->literal('Gui%'))
+        public function like($x, $y); // Returns Expr\Comparison instance
+
+        // Example - $qb->expr()->notLike('u.firstname', $qb->expr()->literal('Gui%'))
+        public function notLike($x, $y); // Returns Expr\Comparison instance
+
+        // Example - $qb->expr()->between('u.id', '1', '10')
+        public function between($val, $x, $y); // Returns Expr\Func
+
+
+        /** Function objects **/
+
+        // Example - $qb->expr()->trim('u.firstname')
+        public function trim($x); // Returns Expr\Func
+
+        // Example - $qb->expr()->concat('u.firstname', $qb->expr()->concat($qb->expr()->literal(' '), 'u.lastname'))
+        public function concat($x, $y); // Returns Expr\Func
+
+        // Example - $qb->expr()->substring('u.firstname', 0, 1)
+        public function substring($x, $from, $len); // Returns Expr\Func
+
+        // Example - $qb->expr()->lower('u.firstname')
+        public function lower($x); // Returns Expr\Func
+
+        // Example - $qb->expr()->upper('u.firstname')
+        public function upper($x); // Returns Expr\Func
+
+        // Example - $qb->expr()->length('u.firstname')
+        public function length($x); // Returns Expr\Func
+
+        // Example - $qb->expr()->avg('u.age')
+        public function avg($x); // Returns Expr\Func
+
+        // Example - $qb->expr()->max('u.age')
+        public function max($x); // Returns Expr\Func
+
+        // Example - $qb->expr()->min('u.age')
+        public function min($x); // Returns Expr\Func
+
+        // Example - $qb->expr()->abs('u.currentBalance')
+        public function abs($x); // Returns Expr\Func
+
+        // Example - $qb->expr()->sqrt('u.currentBalance')
+        public function sqrt($x); // Returns Expr\Func
+
+        // Example - $qb->expr()->count('u.firstname')
+        public function count($x); // Returns Expr\Func
+
+        // Example - $qb->expr()->countDistinct('u.surname')
+        public function countDistinct($x); // Returns Expr\Func
+    }
+
+Adding a Criteria to a Query
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also add a :ref:`filtering-collections` to a QueryBuilder by
+using ``addCriteria``:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\Common\Collections\Criteria;
+    // ...
+
+    $criteria = Criteria::create()
+        ->orderBy(['firstName', 'ASC']);
+
+    // $qb instanceof QueryBuilder
+    $qb->addCriteria($criteria);
+    // then execute your query like normal
+
+Low Level API
+^^^^^^^^^^^^^
+
+Now we will describe the low level method of creating queries.
+It may be useful to work at this level for optimization purposes,
+but most of the time it is preferred to work at a higher level of
+abstraction.
+
+All helper methods in ``QueryBuilder`` actually rely on a single
+one: ``add()``. This method is responsible of building every piece
+of DQL. It takes 3 parameters: ``$dqlPartName``, ``$dqlPart`` and
+``$append`` (default=false)
+
+
+-  ``$dqlPartName``: Where the ``$dqlPart`` should be placed.
+   Possible values: select, from, where, groupBy, having, orderBy
+-  ``$dqlPart``: What should be placed in ``$dqlPartName``. Accepts
+   a string or any instance of ``Doctrine\ORM\Query\Expr\*``
+-  ``$append``: Optional flag (default=false) if the ``$dqlPart``
+   should override all previously defined items in ``$dqlPartName`` or
+   not (no effect on the ``where`` and ``having`` DQL query parts,
+   which always override all previously defined items)
+
+-
+
+.. code-block:: php
+
+    <?php
+    // $qb instanceof QueryBuilder
+
+    // example6: how to define:
+    // "SELECT u FROM User u WHERE u.id = ? ORDER BY u.name ASC"
+    // using QueryBuilder string support
+    $qb->add('select', 'u')
+       ->add('from', 'User u')
+       ->add('where', 'u.id = ?1')
+       ->add('orderBy', 'u.name ASC');
+
+Expr\* classes
+^^^^^^^^^^^^^^
+
+When you call ``add()`` with string, it internally evaluates to an
+instance of ``Doctrine\ORM\Query\Expr\Expr\*`` class. Here is the
+same query of example 6 written using
+``Doctrine\ORM\Query\Expr\Expr\*`` classes:
+
+.. code-block:: php
+
+   <?php
+   // $qb instanceof QueryBuilder
+
+   // example7: how to define:
+   // "SELECT u FROM User u WHERE u.id = ? ORDER BY u.name ASC"
+   // using QueryBuilder using Expr\* instances
+   $qb->add('select', new Expr\Select(array('u')))
+      ->add('from', new Expr\From('User', 'u'))
+      ->add('where', new Expr\Comparison('u.id', '=', '?1'))
+      ->add('orderBy', new Expr\OrderBy('u.name', 'ASC'));

vendor/doctrine/orm/docs/en/reference/second-level-cache.rst

@@ -0,0 +1,736 @@
+The Second Level Cache
+======================
+
+.. note::
+
+    The second level cache functionality is marked as experimental for now. It
+    is a very complex feature and we cannot guarantee yet that it works stable
+    in all cases.
+
+The Second Level Cache is designed to reduce the amount of necessary database access.
+It sits between your application and the database to avoid the number of database hits as much as possible.
+
+When turned on, entities will be first searched in cache and if they are not found,
+a database query will be fired and then the entity result will be stored in a cache provider.
+
+There are some flavors of caching available, but is better to cache read-only data.
+
+Be aware that caches are not aware of changes made to the persistent store by another application.
+They can, however, be configured to regularly expire cached data.
+
+
+Caching Regions
+---------------
+
+Second level cache does not store instances of an entity, instead it caches only entity identifier and values.
+Each entity class, collection association and query has its region, where values of each instance are stored.
+
+Caching Regions are specific region into the cache provider that might store entities, collection or queries.
+Each cache region resides in a specific cache namespace and has its own lifetime configuration.
+
+Notice that when caching collection and queries only identifiers are stored.
+The entity values will be stored in its own region
+
+Something like below for an entity region :
+
+.. code-block:: php
+
+    <?php
+    [
+      'region_name:entity_1_hash' => ['id'=> 1, 'name' => 'FooBar', 'associationName'=>null],
+      'region_name:entity_2_hash' => ['id'=> 2, 'name' => 'Foo', 'associationName'=>['id'=>11]],
+      'region_name:entity_3_hash' => ['id'=> 3, 'name' => 'Bar', 'associationName'=>['id'=>22]]
+    ];
+
+
+If the entity holds a collection that also needs to be cached.
+An collection region could look something like :
+
+.. code-block:: php
+
+    <?php
+    [
+      'region_name:entity_1_coll_assoc_name_hash' => ['ownerId'=> 1, 'list' => [1, 2, 3]],
+      'region_name:entity_2_coll_assoc_name_hash' => ['ownerId'=> 2, 'list' => [2, 3]],
+      'region_name:entity_3_coll_assoc_name_hash' => ['ownerId'=> 3, 'list' => [2, 4]]
+    ];
+
+A query region might be something like :
+
+.. code-block:: php
+
+    <?php
+    [
+      'region_name:query_1_hash' => ['list' => [1, 2, 3]],
+      'region_name:query_2_hash' => ['list' => [2, 3]],
+      'region_name:query_3_hash' => ['list' => [2, 4]]
+    ];
+
+
+.. note::
+
+    The following data structures represents now the cache will looks like, this is not actual cached data.
+
+
+.. _reference-second-level-cache-regions:
+
+Cache Regions
+-------------
+
+``Doctrine\ORM\Cache\Region\DefaultRegion`` is the default implementation.
+ A simplest cache region compatible with all doctrine-cache drivers but does not support locking.
+``Doctrine\ORM\Cache\Region`` and ``Doctrine\ORM\Cache\ConcurrentRegion``
+define contracts that should be implemented by a cache provider.
+
+It allows you to provide your own cache implementation that might take advantage of specific cache driver.
+
+If you want to support locking for ``READ_WRITE`` strategies you should implement ``ConcurrentRegion``; ``CacheRegion`` otherwise.
+
+
+Cache region
+~~~~~~~~~~~~
+
+``Doctrine\ORM\Cache\Region`` defines a contract for accessing a particular
+cache region.
+
+`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/Region.html>`_.
+
+Concurrent cache region
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A ``Doctrine\ORM\Cache\ConcurrentRegion`` is designed to store concurrently managed data region.
+By default, Doctrine provides a very simple implementation based on file locks ``Doctrine\ORM\Cache\Region\FileLockRegion``.
+
+If you want to use an ``READ_WRITE`` cache, you should consider providing your own cache region.
+
+``Doctrine\ORM\Cache\ConcurrentRegion`` defines a contract for concurrently managed data region.
+
+`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/ConcurrentRegion.html>`_.
+
+Timestamp region
+~~~~~~~~~~~~~~~~
+
+``Doctrine\ORM\Cache\TimestampRegion``
+
+Tracks the timestamps of the most recent updates to particular entity.
+
+`See API Doc <http://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/TimestampRegion.html>`_.
+
+.. _reference-second-level-cache-mode:
+
+Caching mode
+------------
+
+* ``READ_ONLY`` (DEFAULT)
+
+  * Can do reads, inserts and deletes, cannot perform updates or employ any locks.
+  * Useful for data that is read frequently but never updated.
+  * Best performer.
+  * It is Simple.
+
+* ``NONSTRICT_READ_WRITE``
+
+  * Read Write Cache doesn’t employ any locks but can do reads, inserts, updates and deletes.
+  * Good if the application needs to update data rarely.
+    
+
+* ``READ_WRITE``
+
+  * Read Write cache employs locks before update/delete.
+  * Use if data needs to be updated.
+  * Slowest strategy.
+  * To use it a the cache region implementation must support locking.
+
+
+Built-in cached persisters
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Cached persisters are responsible to access cache regions.
+
+    +-----------------------+-------------------------------------------------------------------------------------------+
+    | Cache Usage           | Persister                                                                                 |
+    +=======================+===========================================================================================+
+    | READ_ONLY             | Doctrine\\ORM\\Cache\\Persister\\Entity\\ReadOnlyCachedEntityPersister                    |
+    +-----------------------+-------------------------------------------------------------------------------------------+
+    | READ_WRITE            | Doctrine\\ORM\\Cache\\Persister\\Entity\\ReadWriteCachedEntityPersister                   |
+    +-----------------------+-------------------------------------------------------------------------------------------+
+    | NONSTRICT_READ_WRITE  | Doctrine\\ORM\\Cache\\Persister\\Entity\\NonStrictReadWriteCachedEntityPersister          |
+    +-----------------------+-------------------------------------------------------------------------------------------+
+    | READ_ONLY             | Doctrine\\ORM\\Cache\\Persister\\Collection\\ReadOnlyCachedCollectionPersister            |
+    +-----------------------+-------------------------------------------------------------------------------------------+
+    | READ_WRITE            | Doctrine\\ORM\\Cache\\Persister\\Collection\\ReadWriteCachedCollectionPersister           |
+    +-----------------------+-------------------------------------------------------------------------------------------+
+    | NONSTRICT_READ_WRITE  | Doctrine\\ORM\\Cache\\Persister\\Collection\\NonStrictReadWriteCachedCollectionPersister  |
+    +-----------------------+-------------------------------------------------------------------------------------------+
+
+Configuration
+-------------
+Doctrine allows you to specify configurations and some points of extension for the second-level-cache
+
+
+Enable Second Level Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable the second-level-cache, you should provide a cache factory.
+``\Doctrine\ORM\Cache\DefaultCacheFactory`` is the default implementation.
+
+.. code-block:: php
+
+    <?php
+    /* @var $config \Doctrine\ORM\Cache\RegionsConfiguration */
+    /* @var $cache \Doctrine\Common\Cache\Cache */
+
+    $factory = new \Doctrine\ORM\Cache\DefaultCacheFactory($config, $cache);
+
+    // Enable second-level-cache
+    $config->setSecondLevelCacheEnabled();
+
+    // Cache factory
+    $config->getSecondLevelCacheConfiguration()
+        ->setCacheFactory($factory);
+
+
+Cache Factory
+~~~~~~~~~~~~~
+
+Cache Factory is the main point of extension.
+
+It allows you to provide a specific implementation of the following components :
+
+``QueryCache``
+    stores and retrieves query cache results.
+``CachedEntityPersister``
+    stores and retrieves entity results.
+``CachedCollectionPersister``
+    stores and retrieves query results.
+``EntityHydrator``
+    transforms entities into a cache entries and cache entries into entities
+``CollectionHydrator``
+    transforms collections into cache entries and cache entries into collections
+
+`See API Doc <http://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/DefaultCacheFactory.html>`_.
+
+Region Lifetime
+~~~~~~~~~~~~~~~
+
+To specify a default lifetime for all regions or specify a different lifetime for a specific region.
+
+.. code-block:: php
+
+    <?php
+    /* @var $config \Doctrine\ORM\Configuration */
+    /* @var $cacheConfig \Doctrine\ORM\Cache\CacheConfiguration */
+    $cacheConfig  =  $config->getSecondLevelCacheConfiguration();
+    $regionConfig =  $cacheConfig->getRegionsConfiguration();
+
+    // Cache Region lifetime
+    $regionConfig->setLifetime('my_entity_region', 3600);   // Time to live for a specific region (in seconds)
+    $regionConfig->setDefaultLifetime(7200);                // Default time to live (in seconds)
+
+
+Cache Log
+~~~~~~~~~
+By providing a cache logger you should be able to get information about all cache operations such as hits, misses and puts.
+
+``\Doctrine\ORM\Cache\Logging\StatisticsCacheLogger`` is a built-in implementation that provides basic statistics.
+
+ .. code-block:: php
+
+    <?php
+    /* @var $config \Doctrine\ORM\Configuration */
+    $logger = new \Doctrine\ORM\Cache\Logging\StatisticsCacheLogger();
+
+    // Cache logger
+    $config->setSecondLevelCacheEnabled(true);
+    $config->getSecondLevelCacheConfiguration()
+        ->setCacheLogger($logger);
+
+
+    // Collect cache statistics
+
+    // Get the number of entries successfully retrieved from a specific region.
+    $logger->getRegionHitCount('my_entity_region');
+
+    // Get the number of cached entries *not* found in a specific region.
+    $logger->getRegionMissCount('my_entity_region');
+
+    // Get the number of cacheable entries put in cache.
+    $logger->getRegionPutCount('my_entity_region');
+
+    // Get the total number of put in all regions.
+    $logger->getPutCount();
+
+    // Get the total number of entries successfully retrieved from all regions.
+    $logger->getHitCount();
+
+    // Get the total number of cached entries *not* found in all regions.
+    $logger->getMissCount();
+
+If you want to get more information you should implement
+``\Doctrine\ORM\Cache\Logging\CacheLogger`` and collect
+all the information you want.
+
+`See API Doc <http://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/Logging/CacheLogger.html>`_.
+
+
+Entity cache definition
+-----------------------
+* Entity cache configuration allows you to define the caching strategy and region for an entity.
+
+  * ``usage`` specifies the caching strategy: ``READ_ONLY``,
+``NONSTRICT_READ_WRITE``, ``READ_WRITE``.
+See :ref:`reference-second-level-cache-mode`.
+  * ``region`` is an optional value that specifies the name of the second
+level cache region.
+
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        /**
+         * @Entity
+         * @Cache(usage="READ_ONLY", region="my_entity_region")
+         */
+        class Country
+        {
+            /**
+             * @Id
+             * @GeneratedValue
+             * @Column(type="integer")
+             */
+            protected $id;
+
+            /**
+             * @Column(unique=true)
+             */
+            protected $name;
+
+            // other properties and methods
+        }
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="utf-8"?>
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+          <entity name="Country">
+            <cache usage="READ_ONLY" region="my_entity_region" />
+            <id name="id" type="integer" column="id">
+              <generator strategy="IDENTITY"/>
+            </id>
+            <field name="name" type="string" column="name"/>
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        Country:
+          type: entity
+          cache:
+            usage : READ_ONLY
+            region : my_entity_region
+          id:
+            id:
+              type: integer
+              id: true
+              generator:
+                strategy: IDENTITY
+          fields:
+            name:
+              type: string
+
+
+Association cache definition
+----------------------------
+The most common use case is to cache entities. But we can also cache relationships.
+It caches the primary keys of association and cache each element will be cached into its region.
+
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        /**
+         * @Entity
+         * @Cache("NONSTRICT_READ_WRITE")
+         */
+        class State
+        {
+            /**
+             * @Id
+             * @GeneratedValue
+             * @Column(type="integer")
+             */
+            protected $id;
+
+            /**
+             * @Column(unique=true)
+             */
+            protected $name;
+
+            /**
+             * @Cache("NONSTRICT_READ_WRITE")
+             * @ManyToOne(targetEntity="Country")
+             * @JoinColumn(name="country_id", referencedColumnName="id")
+             */
+            protected $country;
+
+            /**
+             * @Cache("NONSTRICT_READ_WRITE")
+             * @OneToMany(targetEntity="City", mappedBy="state")
+             */
+            protected $cities;
+
+            // other properties and methods
+        }
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="utf-8"?>
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+          <entity name="State">
+
+            <cache usage="NONSTRICT_READ_WRITE" />
+
+            <id name="id" type="integer" column="id">
+              <generator strategy="IDENTITY"/>
+            </id>
+
+            <field name="name" type="string" column="name"/>
+            
+            <many-to-one field="country" target-entity="Country">
+              <cache usage="NONSTRICT_READ_WRITE" />
+
+              <join-columns>
+                <join-column name="country_id" referenced-column-name="id"/>
+              </join-columns>
+            </many-to-one>
+
+            <one-to-many field="cities" target-entity="City" mapped-by="state">
+              <cache usage="NONSTRICT_READ_WRITE"/>
+            </one-to-many>
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        State:
+          type: entity
+          cache:
+            usage : NONSTRICT_READ_WRITE
+          id:
+            id:
+              type: integer
+              id: true
+              generator:
+                strategy: IDENTITY
+          fields:
+            name:
+              type: string
+
+          manyToOne:
+            state:
+              targetEntity: Country
+              joinColumns:
+                country_id:
+                  referencedColumnName: id
+              cache:
+                usage : NONSTRICT_READ_WRITE
+
+          oneToMany:
+            cities:
+              targetEntity:City
+              mappedBy: state
+              cache:
+                usage : NONSTRICT_READ_WRITE
+
+
+> Note: for this to work, the target entity must also be marked as cacheable.
+
+Cache usage
+~~~~~~~~~~~
+
+Basic entity cache
+
+.. code-block:: php
+
+    <?php
+    $em->persist(new Country($name));
+    $em->flush();                         // Hit database to insert the row and put into cache
+
+    $em->clear();                         // Clear entity manager
+
+    $country1  = $em->find('Country', 1); // Retrieve item from cache
+
+    $country->setName("New Name");
+    $em->persist($country);
+    $em->flush();                         // Hit database to update the row and update cache
+
+    $em->clear();                         // Clear entity manager
+
+    $country2  = $em->find('Country', 1); // Retrieve item from cache
+                                          // Notice that $country1 and $country2 are not the same instance.
+
+
+Association cache
+
+.. code-block:: php
+
+    <?php
+    // Hit database to insert the row and put into cache
+    $em->persist(new State($name, $country));
+    $em->flush();
+
+    // Clear entity manager
+    $em->clear();
+
+    // Retrieve item from cache
+    $state = $em->find('State', 1);
+
+    // Hit database to update the row and update cache entry
+    $state->setName("New Name");
+    $em->persist($state);
+    $em->flush();
+
+    // Create a new collection item
+    $city = new City($name, $state);
+    $state->addCity($city);
+
+    // Hit database to insert new collection item,
+    // put entity and collection cache into cache.
+    $em->persist($city);
+    $em->persist($state);
+    $em->flush();
+
+    // Clear entity manager
+    $em->clear();
+
+    // Retrieve item from cache
+    $state = $em->find('State', 1);
+
+    // Retrieve association from cache
+    $country = $state->getCountry();
+
+    // Retrieve collection from cache
+    $cities = $state->getCities();
+
+    echo $country->getName();
+    echo $state->getName();
+
+    // Retrieve each collection item from cache
+    foreach ($cities as $city) {
+        echo $city->getName();
+    }
+
+.. note::
+
+    Notice that all entities should be marked as cacheable.
+
+Using the query cache
+---------------------
+
+The second level cache stores the entities, associations and collections.
+The query cache stores the results of the query but as identifiers, entity values are actually stored in the 2nd level cache.
+
+.. note::
+
+    Query cache should always be used in conjunction with the second-level-cache for those entities which should be cached.
+
+.. code-block:: php
+
+    <?php
+    /* @var $em \Doctrine\ORM\EntityManager */
+
+    // Execute database query, store query cache and entity cache
+    $result1 = $em->createQuery('SELECT c FROM Country c ORDER BY c.name')
+        ->setCacheable(true)
+        ->getResult();
+
+    $em->clear()
+
+    // Check if query result is valid and load entities from cache
+    $result2 = $em->createQuery('SELECT c FROM Country c ORDER BY c.name')
+        ->setCacheable(true)
+        ->getResult();
+
+Cache mode
+~~~~~~~~~~
+
+The Cache Mode controls how a particular query interacts with the second-level cache:
+
+* ``Cache::MODE_GET`` - May read items from the cache, but will not add items.
+* ``Cache::MODE_PUT`` - Will never read items from the cache, but will add items to the cache as it reads them from the database.
+* ``Cache::MODE_NORMAL`` - May read items from the cache, and add items to the cache.
+* ``Cache::MODE_REFRESH`` - The query will never read items from the cache, but will refresh items to the cache as it reads them from the database.
+
+.. code-block:: php
+
+    <?php
+    /* @var $em \Doctrine\ORM\EntityManager */
+    // Will refresh the query cache and all entities the cache as it reads from the database.
+    $result1 = $em->createQuery('SELECT c FROM Country c ORDER BY c.name')
+        ->setCacheMode(Cache::MODE_GET)
+        ->setCacheable(true)
+        ->getResult();
+
+.. note::
+
+    The the default query cache mode is ```Cache::MODE_NORMAL```
+
+DELETE / UPDATE queries
+~~~~~~~~~~~~~~~~~~~~~~~
+
+DQL UPDATE / DELETE statements are ported directly into a database and bypass
+the second-level cache.
+Entities that are already cached will NOT be invalidated.
+However the cached data could be evicted using the cache API or an special query hint.
+
+
+Execute the ``UPDATE`` and invalidate ``all cache entries`` using ``Query::HINT_CACHE_EVICT``
+
+.. code-block:: php
+
+    <?php
+    // Execute and invalidate
+    $this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
+        ->setHint(Query::HINT_CACHE_EVICT, true)
+        ->execute();
+
+
+Execute the ``UPDATE`` and invalidate ``all cache entries`` using the cache API
+
+.. code-block:: php
+
+    <?php
+    // Execute
+    $this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
+        ->execute();
+    // Invoke Cache API
+    $em->getCache()->evictEntityRegion('Entity\Country');
+
+
+Execute the ``UPDATE`` and invalidate ``a specific cache entry`` using the cache API
+
+.. code-block:: php
+
+    <?php
+    // Execute
+    $this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
+        ->execute();
+    // Invoke Cache API
+    $em->getCache()->evictEntity('Entity\Country', 1);
+
+Using the repository query cache
+--------------------------------
+
+As well as ``Query Cache`` all persister queries store only identifier values for an individual query.
+All persisters use a single timestamp cache region to keep track of the last update for each persister,
+When a query is loaded from cache, the timestamp region is checked for the last update for that persister.
+Using the last update timestamps as part of the query key invalidate the cache key when an update occurs.
+
+.. code-block:: php
+
+    <?php
+    // load from database and store cache query key hashing the query + parameters + last timestamp cache region..
+    $entities   = $em->getRepository('Entity\Country')->findAll();
+
+    // load from query and entities from cache..
+    $entities   = $em->getRepository('Entity\Country')->findAll();
+
+    // update the timestamp cache region for Country
+    $em->persist(new Country('zombieland'));
+    $em->flush();
+    $em->clear();
+
+    // Reload from database.
+    // At this point the query cache key is no longer valid, the select goes straight to the database
+    $entities   = $em->getRepository('Entity\Country')->findAll();
+
+Cache API
+---------
+
+Caches are not aware of changes made by another application.
+However, you can use the cache API to check / invalidate cache entries.
+
+.. code-block:: php
+
+    <?php
+    /* @var $cache \Doctrine\ORM\Cache */
+    $cache = $em->getCache();
+
+    $cache->containsEntity('Entity\State', 1)      // Check if the cache exists
+    $cache->evictEntity('Entity\State', 1);        // Remove an entity from cache
+    $cache->evictEntityRegion('Entity\State');     // Remove all entities from cache
+
+    $cache->containsCollection('Entity\State', 'cities', 1);   // Check if the cache exists
+    $cache->evictCollection('Entity\State', 'cities', 1);      // Remove an entity collection from cache
+    $cache->evictCollectionRegion('Entity\State', 'cities');   // Remove all collections from cache
+
+Limitations
+-----------
+
+Composite primary key
+~~~~~~~~~~~~~~~~~~~~~
+
+Composite primary key are supported by second level cache,
+however when one of the keys is an association the cached entity should always be retrieved using the association identifier.
+For performance reasons the cache API does not extract from composite primary key.
+
+.. code-block:: php
+
+    <?php
+    /**
+     * @Entity
+     */
+    class Reference
+    {
+        /**
+         * @Id
+         * @ManyToOne(targetEntity="Article", inversedBy="references")
+         * @JoinColumn(name="source_id", referencedColumnName="article_id")
+         */
+        private $source;
+
+        /**
+         * @Id
+         * @ManyToOne(targetEntity="Article")
+         * @JoinColumn(name="target_id", referencedColumnName="article_id")
+         */
+        private $target;
+    }
+
+    // Supported
+    /* @var $article Article */
+    $article = $em->find('Article', 1);
+
+    // Supported
+    /* @var $article Article */
+    $article = $em->find('Article', $article);
+
+    // Supported
+    $id        = array('source' => 1, 'target' => 2);
+    $reference = $em->find('Reference', $id);
+
+    // NOT Supported
+    $id        = array('source' => new Article(1), 'target' => new Article(2));
+    $reference = $em->find('Reference', $id);
+
+Distributed environments
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some cache driver are not meant to be used in a distributed environment.
+Load-balancer for distributing workloads across multiple computing resources
+should be used in conjunction with distributed caching system such as memcached, redis, riak ...
+
+Caches should be used with care when using a load-balancer if you don't share the cache.
+While using APC or any file based cache update occurred in a specific machine would not reflect to the cache in other machines.
+
+
+Paginator
+~~~~~~~~~
+
+Count queries generated by ``Doctrine\ORM\Tools\Pagination\Paginator`` are not cached by second-level cache.
+Although entities and query result are cached, count queries will hit the
+database every time.

vendor/doctrine/orm/docs/en/reference/security.rst

@@ -0,0 +1,151 @@
+Security
+========
+
+The Doctrine library is operating very close to your database and as such needs
+to handle and make assumptions about SQL injection vulnerabilities.
+
+It is vital that you understand how Doctrine approaches security, because
+we cannot protect you from SQL injection.
+
+Please also read the documentation chapter on Security in Doctrine DBAL. This
+page only handles Security issues in the ORM.
+
+- `DBAL Security Page <http://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/security.html>`
+
+If you find a Security bug in Doctrine, please report it on Jira and change the
+Security Level to "Security Issues". It will be visible to Doctrine Core
+developers and you only.
+
+User input and Doctrine ORM
+---------------------------
+
+The ORM is much better at protecting against SQL injection than the DBAL alone.
+You can consider the following APIs to be safe from SQL injection:
+
+- ``\Doctrine\ORM\EntityManager#find()`` and ``getReference()``.
+- All values on Objects inserted and updated through ``Doctrine\ORM\EntityManager#persist()``
+- All find methods on ``Doctrine\ORM\EntityRepository``.
+- User Input set to DQL Queries or QueryBuilder methods through
+    - ``setParameter()`` or variants
+    - ``setMaxResults()``
+    - ``setFirstResult()``
+- Queries through the Criteria API on ``Doctrine\ORM\PersistentCollection`` and
+  ``Doctrine\ORM\EntityRepository``.
+
+You are **NOT** safe from SQL injection when using user input with:
+
+- Expression API of ``Doctrine\ORM\QueryBuilder``
+- Concatenating user input into DQL SELECT, UPDATE or DELETE statements or
+  Native SQL.
+
+This means SQL injections can only occur with Doctrine ORM when working with
+Query Objects of any kind. The safe rule is to always use prepared statement
+parameters for user objects when using a Query object.
+
+.. warning::
+
+    Insecure code follows, don't copy paste this.
+
+The following example shows insecure DQL usage:
+
+.. code-block:: php
+
+    <?php
+
+    // INSECURE
+    $dql = "SELECT u
+              FROM MyProject\Entity\User u
+             WHERE u.status = '" .  $_GET['status'] . "'
+         ORDER BY " . $_GET['orderField'] . " ASC";
+
+For Doctrine there is absolutely no way to find out which parts of ``$dql`` are
+from user input and which are not, even if we have our own parsing process
+this is technically impossible. The correct way is:
+
+.. code-block:: php
+
+    <?php
+
+    $orderFieldWhitelist = array('email', 'username');
+    $orderField = "email";
+
+    if (in_array($_GET['orderField'], $orderFieldWhitelist)) {
+        $orderField = $_GET['orderField'];
+    }
+
+    $dql = "SELECT u
+              FROM MyProject\Entity\User u
+             WHERE u.status = ?1
+         ORDER BY u." . $orderField . " ASC";
+
+    $query = $entityManager->createQuery($dql);
+    $query->setParameter(1, $_GET['status']);
+
+
+Preventing Mass Assignment Vulnerabilities
+------------------------------------------
+
+ORMs are very convenient for CRUD applications and Doctrine is no exception.
+However CRUD apps are often vulnerable to mass assignment security problems
+when implemented naively.
+
+Doctrine is not vulnerable to this problem out of the box, but you can easily
+make your entities vulnerable to mass assignment when you add methods of
+the kind ``updateFromArray()`` or ``updateFromJson()`` to them. A vulnerable
+entity might look like this:
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Entity
+     */
+    class InsecureEntity
+    {
+        /** @Id @Column(type="integer") @GeneratedValue */
+        private $id;
+        /** @Column */
+        private $email;
+        /** @Column(type="boolean") */
+        private $isAdmin;
+
+        public function fromArray(array $userInput)
+        {
+            foreach ($userInput as $key => $value) {
+                $this->$key = $value;
+            }
+        }
+    }
+
+Now the possiblity of mass-asignment exists on this entity and can
+be exploited by attackers to set the "isAdmin" flag to true on any
+object when you pass the whole request data to this method like:
+
+.. code-block:: php
+
+    <?php
+    $entity = new InsecureEntity();
+    $entity->fromArray($_POST);
+
+    $entityManager->persist($entity);
+    $entityManager->flush();
+
+You can spot this problem in this very simple example easily. However
+in combination with frameworks and form libraries it might not be
+so obvious when this issue arises. Be careful to avoid this
+kind of mistake.
+
+How to fix this problem? You should always have a whitelist
+of allowed key to set via mass assignment functions.
+
+.. code-block:: php
+
+    public function fromArray(array $userInput, $allowedFields = array())
+    {
+        foreach ($userInput as $key => $value) {
+            if (in_array($key, $allowedFields)) {
+                $this->$key = $value;
+            }
+        }
+    }

vendor/doctrine/orm/docs/en/reference/tools.rst

@@ -0,0 +1,520 @@
+Tools
+=====
+
+Doctrine Console
+----------------
+
+The Doctrine Console is a Command Line Interface tool for simplifying common
+administration tasks during the development of a project that uses Doctrine 2.
+
+Take a look at the :doc:`Installation and Configuration <configuration>`
+chapter for more information how to setup the console command.
+
+Display Help Information
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Type ``php vendor/bin/doctrine`` on the command line and you should see an
+overview of the available commands or use the --help flag to get
+information on the available commands. If you want to know more
+about the use of generate entities for example, you can call:
+
+.. code-block:: php
+
+    $> php vendor/bin/doctrine orm:generate-entities --help
+
+
+Configuration
+~~~~~~~~~~~~~
+
+Whenever the ``doctrine`` command line tool is invoked, it can
+access all Commands that were registered by developer. There is no
+auto-detection mechanism at work. The Doctrine binary
+already registers all the commands that currently ship with
+Doctrine DBAL and ORM. If you want to use additional commands you
+have to register them yourself.
+
+All the commands of the Doctrine Console require access to the ``EntityManager``
+or ``DBAL`` Connection. You have to inject them into the console application
+using so called Helper-Sets. This requires either the ``db``
+or the ``em`` helpers to be defined in order to work correctly.
+
+Whenever you invoke the Doctrine binary the current folder is searched for a
+``cli-config.php`` file. This file contains the project specific configuration:
+
+.. code-block:: php
+
+    <?php
+    $helperSet = new \Symfony\Component\Console\Helper\HelperSet(array(
+        'db' => new \Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper($conn)
+    ));
+    $cli->setHelperSet($helperSet);
+
+When dealing with the ORM package, the EntityManagerHelper is
+required:
+
+.. code-block:: php
+
+    <?php
+    $helperSet = new \Symfony\Component\Console\Helper\HelperSet(array(
+        'em' => new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($em)
+    ));
+    $cli->setHelperSet($helperSet);
+
+The HelperSet instance has to be generated in a separate file (i.e.
+``cli-config.php``) that contains typical Doctrine bootstrap code
+and predefines the needed HelperSet attributes mentioned above. A
+sample ``cli-config.php`` file looks as follows:
+
+.. code-block:: php
+
+    <?php
+    // cli-config.php
+    require_once 'my_bootstrap.php';
+
+    // Any way to access the EntityManager from  your application
+    $em = GetMyEntityManager();
+    
+    $helperSet = new \Symfony\Component\Console\Helper\HelperSet(array(
+        'db' => new \Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper($em->getConnection()),
+        'em' => new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($em)
+    ));
+
+It is important to define a correct HelperSet that Doctrine binary
+script will ultimately use. The Doctrine Binary will automatically
+find the first instance of HelperSet in the global variable
+namespace and use this.
+
+.. note:: 
+
+    You have to adjust this snippet for your specific application or framework
+    and use their facilities to access the Doctrine EntityManager and
+    Connection Resources.
+
+Command Overview
+~~~~~~~~~~~~~~~~
+
+The following Commands are currently available:
+
+
+-  ``help`` Displays help for a command (?)
+-  ``list`` Lists commands
+-  ``dbal:import`` Import SQL file(s) directly to Database.
+-  ``dbal:run-sql`` Executes arbitrary SQL directly from the
+   command line.
+-  ``orm:clear-cache:metadata`` Clear all metadata cache of the
+   various cache drivers.
+-  ``orm:clear-cache:query`` Clear all query cache of the various
+   cache drivers.
+-  ``orm:clear-cache:result`` Clear result cache of the various
+   cache drivers.
+-  ``orm:convert-d1-schema`` Converts Doctrine 1.X schema into a
+   Doctrine 2.X schema.
+-  ``orm:convert-mapping`` Convert mapping information between
+   supported formats.
+-  ``orm:ensure-production-settings`` Verify that Doctrine is
+   properly configured for a production environment.
+-  ``orm:generate-entities`` Generate entity classes and method
+   stubs from your mapping information.
+-  ``orm:generate-proxies`` Generates proxy classes for entity
+   classes.
+-  ``orm:generate-repositories`` Generate repository classes from
+   your mapping information.
+-  ``orm:run-dql`` Executes arbitrary DQL directly from the command
+   line.
+-  ``orm:schema-tool:create`` Processes the schema and either
+   create it directly on EntityManager Storage Connection or generate
+   the SQL output.
+-  ``orm:schema-tool:drop`` Processes the schema and either drop
+   the database schema of EntityManager Storage Connection or generate
+   the SQL output.
+-  ``orm:schema-tool:update`` Processes the schema and either
+   update the database schema of EntityManager Storage Connection or
+   generate the SQL output.
+
+For these commands are also available aliases:
+
+
+-  ``orm:convert:d1-schema`` is alias for ``orm:convert-d1-schema``.
+-  ``orm:convert:mapping`` is alias for ``orm:convert-mapping``.
+-  ``orm:generate:entities`` is alias for ``orm:generate-entities``.
+-  ``orm:generate:proxies`` is alias for ``orm:generate-proxies``.
+-  ``orm:generate:repositories`` is alias for ``orm:generate-repositories``.
+
+.. note::
+
+    Console also supports auto completion, for example, instead of
+    ``orm:clear-cache:query`` you can use just ``o:c:q``.
+
+Database Schema Generation
+--------------------------
+
+.. note::
+
+    SchemaTool can do harm to your database. It will drop or alter
+    tables, indexes, sequences and such. Please use this tool with
+    caution in development and not on a production server. It is meant
+    for helping you develop your Database Schema, but NOT with
+    migrating schema from A to B in production. A safe approach would
+    be generating the SQL on development server and saving it into SQL
+    Migration files that are executed manually on the production
+    server.
+
+    SchemaTool assumes your Doctrine Project uses the given database on
+    its own. Update and Drop commands will mess with other tables if
+    they are not related to the current project that is using Doctrine.
+    Please be careful!
+
+
+To generate your database schema from your Doctrine mapping files
+you can use the ``SchemaTool`` class or the ``schema-tool`` Console
+Command.
+
+When using the SchemaTool class directly, create your schema using
+the ``createSchema()`` method. First create an instance of the
+``SchemaTool`` and pass it an instance of the ``EntityManager``
+that you want to use to create the schema. This method receives an
+array of ``ClassMetadataInfo`` instances.
+
+.. code-block:: php
+
+    <?php
+    $tool = new \Doctrine\ORM\Tools\SchemaTool($em);
+    $classes = array(
+      $em->getClassMetadata('Entities\User'),
+      $em->getClassMetadata('Entities\Profile')
+    );
+    $tool->createSchema($classes);
+
+To drop the schema you can use the ``dropSchema()`` method.
+
+.. code-block:: php
+
+    <?php
+    $tool->dropSchema($classes);
+
+This drops all the tables that are currently used by your metadata
+model. When you are changing your metadata a lot during development
+you might want to drop the complete database instead of only the
+tables of the current model to clean up with orphaned tables.
+
+.. code-block:: php
+
+    <?php
+    $tool->dropSchema($classes, \Doctrine\ORM\Tools\SchemaTool::DROP_DATABASE);
+
+You can also use database introspection to update your schema
+easily with the ``updateSchema()`` method. It will compare your
+existing database schema to the passed array of
+``ClassMetadataInfo`` instances.
+
+.. code-block:: php
+
+    <?php
+    $tool->updateSchema($classes);
+
+If you want to use this functionality from the command line you can
+use the ``schema-tool`` command.
+
+To create the schema use the ``create`` command:
+
+.. code-block:: php
+
+    $ php doctrine orm:schema-tool:create
+
+To drop the schema use the ``drop`` command:
+
+.. code-block:: php
+
+    $ php doctrine orm:schema-tool:drop
+
+If you want to drop and then recreate the schema then use both
+options:
+
+.. code-block:: php
+
+    $ php doctrine orm:schema-tool:drop
+    $ php doctrine orm:schema-tool:create
+
+As you would think, if you want to update your schema use the
+``update`` command:
+
+.. code-block:: php
+
+    $ php doctrine orm:schema-tool:update
+
+All of the above commands also accept a ``--dump-sql`` option that
+will output the SQL for the ran operation.
+
+.. code-block:: php
+
+    $ php doctrine orm:schema-tool:create --dump-sql
+
+Before using the orm:schema-tool commands, remember to configure
+your cli-config.php properly.
+
+Entity Generation
+-----------------
+
+Generate entity classes and method stubs from your mapping information.
+
+.. code-block:: php
+
+    $ php doctrine orm:generate-entities
+    $ php doctrine orm:generate-entities --update-entities
+    $ php doctrine orm:generate-entities --regenerate-entities
+
+This command is not suited for constant usage. It is a little helper and does
+not support all the mapping edge cases very well. You still have to put work
+in your entities after using this command.
+
+It is possible to use the EntityGenerator on code that you have already written. It will
+not be lost. The EntityGenerator will only append new code to your
+file and will not delete the old code. However this approach may still be prone
+to error and we suggest you use code repositories such as GIT or SVN to make
+backups of your code.
+
+It makes sense to generate the entity code if you are using entities as Data
+Access Objects only and don't put much additional logic on them. If you are
+however putting much more logic on the entities you should refrain from using
+the entity-generator and code your entities manually.
+
+.. note::
+
+    Even if you specified Inheritance options in your
+    XML or YAML Mapping files the generator cannot generate the base and
+    child classes for you correctly, because it doesn't know which
+    class is supposed to extend which. You have to adjust the entity
+    code manually for inheritance to work!
+
+
+Convert Mapping Information
+---------------------------
+
+Convert mapping information between supported formats.
+
+This is an **execute one-time** command. It should not be necessary for
+you to call this method multiple times, especially when using the ``--from-database``
+flag.
+
+Converting an existing database schema into mapping files only solves about 70-80%
+of the necessary mapping information. Additionally the detection from an existing
+database cannot detect inverse associations, inheritance types,
+entities with foreign keys as primary keys and many of the
+semantical operations on associations such as cascade.
+
+.. note::
+
+    There is no need to convert YAML or XML mapping files to annotations
+    every time you make changes. All mapping drivers are first class citizens
+    in Doctrine 2 and can be used as runtime mapping for the ORM. See the
+    docs on XML and YAML Mapping for an example how to register this metadata
+    drivers as primary mapping source.
+
+To convert some mapping information between the various supported
+formats you can use the ``ClassMetadataExporter`` to get exporter
+instances for the different formats:
+
+.. code-block:: php
+
+    <?php
+    $cme = new \Doctrine\ORM\Tools\Export\ClassMetadataExporter();
+
+Once you have a instance you can use it to get an exporter. For
+example, the yml exporter:
+
+.. code-block:: php
+
+    <?php
+    $exporter = $cme->getExporter('yml', '/path/to/export/yml');
+
+Now you can export some ``ClassMetadata`` instances:
+
+.. code-block:: php
+
+    <?php
+    $classes = array(
+      $em->getClassMetadata('Entities\User'),
+      $em->getClassMetadata('Entities\Profile')
+    );
+    $exporter->setMetadata($classes);
+    $exporter->export();
+
+This functionality is also available from the command line to
+convert your loaded mapping information to another format. The
+``orm:convert-mapping`` command accepts two arguments, the type to
+convert to and the path to generate it:
+
+.. code-block:: php
+
+    $ php doctrine orm:convert-mapping xml /path/to/mapping-path-converted-to-xml
+
+Reverse Engineering
+-------------------
+
+You can use the ``DatabaseDriver`` to reverse engineer a database
+to an array of ``ClassMetadataInfo`` instances and generate YAML,
+XML, etc. from them.
+
+.. note::
+
+    Reverse Engineering is a **one-time** process that can get you started with a project.
+    Converting an existing database schema into mapping files only detects about 70-80%
+    of the necessary mapping information. Additionally the detection from an existing
+    database cannot detect inverse associations, inheritance types,
+    entities with foreign keys as primary keys and many of the
+    semantical operations on associations such as cascade.
+
+First you need to retrieve the metadata instances with the
+``DatabaseDriver``:
+
+.. code-block:: php
+
+    <?php
+    $em->getConfiguration()->setMetadataDriverImpl(
+        new \Doctrine\ORM\Mapping\Driver\DatabaseDriver(
+            $em->getConnection()->getSchemaManager()
+        )
+    );
+    
+    $cmf = new \Doctrine\ORM\Tools\DisconnectedClassMetadataFactory();
+    $cmf->setEntityManager($em);
+    $metadata = $cmf->getAllMetadata();
+
+Now you can get an exporter instance and export the loaded metadata
+to yml:
+
+.. code-block:: php
+
+    <?php
+    $cme = new \Doctrine\ORM\Tools\Export\ClassMetadataExporter();
+    $exporter = $cme->getExporter('yml', '/path/to/export/yml');
+    $exporter->setMetadata($metadata);
+    $exporter->export();
+
+You can also reverse engineer a database using the
+``orm:convert-mapping`` command:
+
+.. code-block:: php
+
+    $ php doctrine orm:convert-mapping --from-database yml /path/to/mapping-path-converted-to-yml
+
+.. note::
+
+    Reverse Engineering is not always working perfectly
+    depending on special cases. It will only detect Many-To-One
+    relations (even if they are One-To-One) and will try to create
+    entities from Many-To-Many tables. It also has problems with naming
+    of foreign keys that have multiple column names. Any Reverse
+    Engineered Database-Schema needs considerable manual work to become
+    a useful domain model.
+
+
+Runtime vs Development Mapping Validation
+-----------------------------------------
+
+For performance reasons Doctrine 2 has to skip some of the
+necessary validation of metadata mappings. You have to execute
+this validation in your development workflow to verify the
+associations are correctly defined.
+
+You can either use the Doctrine Command Line Tool:
+
+.. code-block:: php
+
+    doctrine orm:validate-schema
+
+Or you can trigger the validation manually:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Tools\SchemaValidator;
+
+    $validator = new SchemaValidator($entityManager);
+    $errors = $validator->validateMapping();
+
+    if (count($errors) > 0) {
+        // Lots of errors!
+        echo implode("\n\n", $errors);
+    }
+
+If the mapping is invalid the errors array contains a positive
+number of elements with error messages.
+
+.. warning::
+
+    One mapping option that is not validated is the use of the referenced column name.
+    It has to point to the equivalent primary key otherwise Doctrine will not work.
+
+.. note::
+
+    One common error is to use a backlash in front of the
+    fully-qualified class-name. Whenever a FQCN is represented inside a
+    string (such as in your mapping definitions) you have to drop the
+    prefix backslash. PHP does this with ``get_class()`` or Reflection
+    methods for backwards compatibility reasons.
+
+
+Adding own commands
+-------------------
+
+You can also add your own commands on-top of the Doctrine supported
+tools if you are using a manually built console script.
+
+To include a new command on Doctrine Console, you need to do modify the
+``doctrine.php`` file a little:
+
+.. code-block:: php
+
+    <?php
+    // doctrine.php
+    use Symfony\Component\Console\Application;
+
+    // as before ...
+
+    // replace the ConsoleRunner::run() statement with:
+    $cli = new Application('Doctrine Command Line Interface', \Doctrine\ORM\Version::VERSION);
+    $cli->setCatchExceptions(true);
+    $cli->setHelperSet($helperSet);
+
+    // Register All Doctrine Commands
+    ConsoleRunner::addCommands($cli);
+
+    // Register your own command
+    $cli->addCommand(new \MyProject\Tools\Console\Commands\MyCustomCommand);
+
+    // Runs console application
+    $cli->run();
+
+Additionally, include multiple commands (and overriding previously
+defined ones) is possible through the command:
+
+.. code-block:: php
+
+    <?php
+
+    $cli->addCommands(array(
+        new \MyProject\Tools\Console\Commands\MyCustomCommand(),
+        new \MyProject\Tools\Console\Commands\SomethingCommand(),
+        new \MyProject\Tools\Console\Commands\AnotherCommand(),
+        new \MyProject\Tools\Console\Commands\OneMoreCommand(),
+    ));
+
+
+Re-use console application
+--------------------------
+
+You are also able to retrieve and re-use the default console application.
+Just call ``ConsoleRunner::createApplication(...)`` with an appropriate
+HelperSet, like it is described in the configuration section.
+
+.. code-block:: php
+
+    <?php
+
+    // Retrieve default console application
+    $cli = ConsoleRunner::createApplication($helperSet);
+
+    // Runs console application
+    $cli->run();
+

vendor/doctrine/orm/docs/en/reference/transactions-and-concurrency.rst

@@ -0,0 +1,409 @@
+Transactions and Concurrency
+============================
+
+.. _transactions-and-concurrency_transaction-demarcation:
+
+Transaction Demarcation
+-----------------------
+
+Transaction demarcation is the task of defining your transaction
+boundaries. Proper transaction demarcation is very important
+because if not done properly it can negatively affect the
+performance of your application. Many databases and database
+abstraction layers like PDO by default operate in auto-commit mode,
+which means that every single SQL statement is wrapped in a small
+transaction. Without any explicit transaction demarcation from your
+side, this quickly results in poor performance because transactions
+are not cheap.
+
+For the most part, Doctrine 2 already takes care of proper
+transaction demarcation for you: All the write operations
+(INSERT/UPDATE/DELETE) are queued until ``EntityManager#flush()``
+is invoked which wraps all of these changes in a single
+transaction.
+
+However, Doctrine 2 also allows (and encourages) you to take over
+and control transaction demarcation yourself.
+
+These are two ways to deal with transactions when using the
+Doctrine ORM and are now described in more detail.
+
+.. _transactions-and-concurrency_approach-implicitly:
+
+Approach 1: Implicitly
+~~~~~~~~~~~~~~~~~~~~~~
+
+The first approach is to use the implicit transaction handling
+provided by the Doctrine ORM EntityManager. Given the following
+code snippet, without any explicit transaction demarcation:
+
+.. code-block:: php
+
+    <?php
+    // $em instanceof EntityManager
+    $user = new User;
+    $user->setName('George');
+    $em->persist($user);
+    $em->flush();
+
+Since we do not do any custom transaction demarcation in the above
+code, ``EntityManager#flush()`` will begin and commit/rollback a
+transaction. This behavior is made possible by the aggregation of
+the DML operations by the Doctrine ORM and is sufficient if all the
+data manipulation that is part of a unit of work happens through
+the domain model and thus the ORM.
+
+.. _transactions-and-concurrency_approach-explicitly:
+
+Approach 2: Explicitly
+~~~~~~~~~~~~~~~~~~~~~~
+
+The explicit alternative is to use the ``Doctrine\DBAL\Connection``
+API directly to control the transaction boundaries. The code then
+looks like this:
+
+.. code-block:: php
+
+    <?php
+    // $em instanceof EntityManager
+    $em->getConnection()->beginTransaction(); // suspend auto-commit
+    try {
+        //... do some work
+        $user = new User;
+        $user->setName('George');
+        $em->persist($user);
+        $em->flush();
+        $em->getConnection()->commit();
+    } catch (Exception $e) {
+        $em->getConnection()->rollBack();
+        throw $e;
+    }
+
+Explicit transaction demarcation is required when you want to
+include custom DBAL operations in a unit of work or when you want
+to make use of some methods of the ``EntityManager`` API that
+require an active transaction. Such methods will throw a
+``TransactionRequiredException`` to inform you of that
+requirement.
+
+A more convenient alternative for explicit transaction demarcation is the use
+of provided control abstractions in the form of
+``Connection#transactional($func)`` and ``EntityManager#transactional($func)``.
+When used, these control abstractions ensure that you never forget to rollback
+the transaction, in addition to the obvious code reduction. An example that is
+functionally equivalent to the previously shown code looks as follows:
+
+.. code-block:: php
+
+    <?php
+    // $em instanceof EntityManager
+    $em->transactional(function($em) {
+        //... do some work
+        $user = new User;
+        $user->setName('George');
+        $em->persist($user);
+    });
+
+.. warning::
+
+    For historical reasons, ``EntityManager#transactional($func)`` will return
+    ``true`` whenever the return value of ``$func`` is loosely false.
+    Some examples of this include ``array()``, ``"0"``, ``""``, ``0``, and
+    ``null``.
+
+The difference between ``Connection#transactional($func)`` and
+``EntityManager#transactional($func)`` is that the latter
+abstraction flushes the ``EntityManager`` prior to transaction
+commit and rolls back the transaction when an
+exception occurs.
+
+.. _transactions-and-concurrency_exception-handling:
+
+Exception Handling
+~~~~~~~~~~~~~~~~~~
+
+When using implicit transaction demarcation and an exception occurs
+during ``EntityManager#flush()``, the transaction is automatically
+rolled back and the ``EntityManager`` closed.
+
+When using explicit transaction demarcation and an exception
+occurs, the transaction should be rolled back immediately and the
+``EntityManager`` closed by invoking ``EntityManager#close()`` and
+subsequently discarded, as demonstrated in the example above. This
+can be handled elegantly by the control abstractions shown earlier.
+Note that when catching ``Exception`` you should generally re-throw
+the exception. If you intend to recover from some exceptions, catch
+them explicitly in earlier catch blocks (but do not forget to
+rollback the transaction and close the ``EntityManager`` there as
+well). All other best practices of exception handling apply
+similarly (i.e. either log or re-throw, not both, etc.).
+
+As a result of this procedure, all previously managed or removed
+instances of the ``EntityManager`` become detached. The state of
+the detached objects will be the state at the point at which the
+transaction was rolled back. The state of the objects is in no way
+rolled back and thus the objects are now out of synch with the
+database. The application can continue to use the detached objects,
+knowing that their state is potentially no longer accurate.
+
+If you intend to start another unit of work after an exception has
+occurred you should do that with a new ``EntityManager``.
+
+.. _transactions-and-concurrency_locking-support:
+
+Locking Support
+---------------
+
+Doctrine 2 offers support for Pessimistic- and Optimistic-locking
+strategies natively. This allows to take very fine-grained control
+over what kind of locking is required for your Entities in your
+application.
+
+.. _transactions-and-concurrency_optimistic-locking:
+
+Optimistic Locking
+~~~~~~~~~~~~~~~~~~
+
+Database transactions are fine for concurrency control during a
+single request. However, a database transaction should not span
+across requests, the so-called "user think time". Therefore a
+long-running "business transaction" that spans multiple requests
+needs to involve several database transactions. Thus, database
+transactions alone can no longer control concurrency during such a
+long-running business transaction. Concurrency control becomes the
+partial responsibility of the application itself.
+
+Doctrine has integrated support for automatic optimistic locking
+via a version field. In this approach any entity that should be
+protected against concurrent modifications during long-running
+business transactions gets a version field that is either a simple
+number (mapping type: integer) or a timestamp (mapping type:
+datetime). When changes to such an entity are persisted at the end
+of a long-running conversation the version of the entity is
+compared to the version in the database and if they don't match, an
+``OptimisticLockException`` is thrown, indicating that the entity
+has been modified by someone else already.
+
+You designate a version field in an entity as follows. In this
+example we'll use an integer.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        class User
+        {
+            // ...
+            /** @Version @Column(type="integer") */
+            private $version;
+            // ...
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="User">
+            <field name="version" type="integer" version="true" />
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          fields:
+            version:
+              type: integer
+              version: true
+
+Alternatively a datetime type can be used (which maps to a SQL
+timestamp or datetime):
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        class User
+        {
+            // ...
+            /** @Version @Column(type="datetime") */
+            private $version;
+            // ...
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="User">
+            <field name="version" type="datetime" version="true" />
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          fields:
+            version:
+              type: datetime
+              version: true
+
+Version numbers (not timestamps) should however be preferred as
+they can not potentially conflict in a highly concurrent
+environment, unlike timestamps where this is a possibility,
+depending on the resolution of the timestamp on the particular
+database platform.
+
+When a version conflict is encountered during
+``EntityManager#flush()``, an ``OptimisticLockException`` is thrown
+and the active transaction rolled back (or marked for rollback).
+This exception can be caught and handled. Potential responses to an
+OptimisticLockException are to present the conflict to the user or
+to refresh or reload objects in a new transaction and then retrying
+the transaction.
+
+With PHP promoting a share-nothing architecture, the time between
+showing an update form and actually modifying the entity can in the
+worst scenario be as long as your applications session timeout. If
+changes happen to the entity in that time frame you want to know
+directly when retrieving the entity that you will hit an optimistic
+locking exception:
+
+You can always verify the version of an entity during a request
+either when calling ``EntityManager#find()``:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\DBAL\LockMode;
+    use Doctrine\ORM\OptimisticLockException;
+    
+    $theEntityId = 1;
+    $expectedVersion = 184;
+    
+    try {
+        $entity = $em->find('User', $theEntityId, LockMode::OPTIMISTIC, $expectedVersion);
+    
+        // do the work
+    
+        $em->flush();
+    } catch(OptimisticLockException $e) {
+        echo "Sorry, but someone else has already changed this entity. Please apply the changes again!";
+    }
+
+Or you can use ``EntityManager#lock()`` to find out:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\DBAL\LockMode;
+    use Doctrine\ORM\OptimisticLockException;
+    
+    $theEntityId = 1;
+    $expectedVersion = 184;
+    
+    $entity = $em->find('User', $theEntityId);
+    
+    try {
+        // assert version
+        $em->lock($entity, LockMode::OPTIMISTIC, $expectedVersion);
+    
+    } catch(OptimisticLockException $e) {
+        echo "Sorry, but someone else has already changed this entity. Please apply the changes again!";
+    }
+
+Important Implementation Notes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can easily get the optimistic locking workflow wrong if you
+compare the wrong versions. Say you have Alice and Bob editing a
+hypothetical blog post:
+
+-  Alice reads the headline of the blog post being "Foo", at
+   optimistic lock version 1 (GET Request)
+-  Bob reads the headline of the blog post being "Foo", at
+   optimistic lock version 1 (GET Request)
+-  Bob updates the headline to "Bar", upgrading the optimistic lock
+   version to 2 (POST Request of a Form)
+-  Alice updates the headline to "Baz", ... (POST Request of a
+   Form)
+
+Now at the last stage of this scenario the blog post has to be read
+again from the database before Alice's headline can be applied. At
+this point you will want to check if the blog post is still at
+version 1 (which it is not in this scenario).
+
+Using optimistic locking correctly, you *have* to add the version
+as an additional hidden field (or into the SESSION for more
+safety). Otherwise you cannot verify the version is still the one
+being originally read from the database when Alice performed her
+GET request for the blog post. If this happens you might see lost
+updates you wanted to prevent with Optimistic Locking.
+
+See the example code, The form (GET Request):
+
+.. code-block:: php
+
+    <?php
+    $post = $em->find('BlogPost', 123456);
+    
+    echo '<input type="hidden" name="id" value="' . $post->getId() . '" />';
+    echo '<input type="hidden" name="version" value="' . $post->getCurrentVersion() . '" />';
+
+And the change headline action (POST Request):
+
+.. code-block:: php
+
+    <?php
+    $postId = (int)$_GET['id'];
+    $postVersion = (int)$_GET['version'];
+    
+    $post = $em->find('BlogPost', $postId, \Doctrine\DBAL\LockMode::OPTIMISTIC, $postVersion);
+
+.. _transactions-and-concurrency_pessimistic-locking:
+
+Pessimistic Locking
+~~~~~~~~~~~~~~~~~~~
+
+Doctrine 2 supports Pessimistic Locking at the database level. No
+attempt is being made to implement pessimistic locking inside
+Doctrine, rather vendor-specific and ANSI-SQL commands are used to
+acquire row-level locks. Every Entity can be part of a pessimistic
+lock, there is no special metadata required to use this feature.
+
+However for Pessimistic Locking to work you have to disable the
+Auto-Commit Mode of your Database and start a transaction around
+your pessimistic lock use-case using the "Approach 2: Explicit
+Transaction Demarcation" described above. Doctrine 2 will throw an
+Exception if you attempt to acquire an pessimistic lock and no
+transaction is running.
+
+Doctrine 2 currently supports two pessimistic lock modes:
+
+
+-  Pessimistic Write
+   (``Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE``), locks the
+   underlying database rows for concurrent Read and Write Operations.
+-  Pessimistic Read (``Doctrine\DBAL\LockMode::PESSIMISTIC_READ``),
+   locks other concurrent requests that attempt to update or lock rows
+   in write mode.
+
+You can use pessimistic locks in three different scenarios:
+
+
+1. Using
+   ``EntityManager#find($className, $id, \Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE)``
+   or
+   ``EntityManager#find($className, $id, \Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``
+2. Using
+   ``EntityManager#lock($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE)``
+   or
+   ``EntityManager#lock($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``
+3. Using
+   ``Query#setLockMode(\Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE)``
+   or
+   ``Query#setLockMode(\Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``
+
+

vendor/doctrine/orm/docs/en/reference/unitofwork-associations.rst

@@ -0,0 +1,60 @@
+Association Updates: Owning Side and Inverse Side
+=================================================
+
+When mapping bidirectional associations it is important to
+understand the concept of the owning and inverse sides. The
+following general rules apply:
+
+-  Relationships may be bidirectional or unidirectional.
+-  A bidirectional relationship has both an owning side and an inverse side
+-  A unidirectional relationship only has an owning side.
+-  Doctrine will **only** check the owning side of an association for changes.
+
+Bidirectional Associations
+--------------------------
+
+The following rules apply to **bidirectional** associations:
+
+- The inverse side has to have the ``mappedBy`` attribute of the OneToOne,
+  OneToMany, or ManyToMany mapping declaration. The mappedBy
+  attribute contains the name of the association-field on the owning side.
+- The owning side has to have the ``inversedBy`` attribute of the
+  OneToOne, ManyToOne, or ManyToMany mapping declaration. 
+  The inversedBy attribute contains the name of the association-field
+  on the inverse-side.
+- ManyToOne is always the owning side of a bidirectional association.
+- OneToMany is always the inverse side of a bidirectional association.
+- The owning side of a OneToOne association is the entity with the table
+  containing the foreign key.
+- You can pick the owning side of a many-to-many association yourself.
+
+Important concepts
+------------------
+
+**Doctrine will only check the owning side of an association for changes.**
+
+To fully understand this, remember how bidirectional associations
+are maintained in the object world. There are 2 references on each
+side of the association and these 2 references both represent the
+same association but can change independently of one another. Of
+course, in a correct application the semantics of the bidirectional
+association are properly maintained by the application developer
+(that's their responsibility). Doctrine needs to know which of these
+two in-memory references is the one that should be persisted and
+which not. This is what the owning/inverse concept is mainly used
+for.
+
+**Changes made only to the inverse side of an association are ignored. Make sure to update both sides of a bidirectional association (or at least the owning side, from Doctrine's point of view)**
+
+The owning side of a bidirectional association is the side Doctrine
+"looks at" when determining the state of the association, and
+consequently whether there is anything to do to update the
+association in the database.
+
+.. note::
+
+    "Owning side" and "inverse side" are technical concepts of
+    the ORM technology, not concepts of your domain model. What you
+    consider as the owning side in your domain model can be different
+    from what the owning side is for Doctrine. These are unrelated.
+

vendor/doctrine/orm/docs/en/reference/unitofwork.rst

@@ -0,0 +1,201 @@
+Doctrine Internals explained
+============================
+
+Object relational mapping is a complex topic and sufficiently understanding how Doctrine works internally helps you use its full power.
+
+How Doctrine keeps track of Objects
+-----------------------------------
+
+Doctrine uses the Identity Map pattern to track objects. Whenever you fetch an
+object from the database, Doctrine will keep a reference to this object inside
+its UnitOfWork. The array holding all the entity references is two-levels deep
+and has the keys "root entity name" and "id". Since Doctrine allows composite
+keys the id is a sorted, serialized version of all the key columns.
+
+This allows Doctrine room for optimizations. If you call the EntityManager and
+ask for an entity with a specific ID twice, it will return the same instance:
+
+.. code-block:: php
+
+    public function testIdentityMap()
+    {
+        $objectA = $this->entityManager->find('EntityName', 1);
+        $objectB = $this->entityManager->find('EntityName', 1);
+
+        $this->assertSame($objectA, $objectB)
+    }
+
+Only one SELECT query will be fired against the database here. In the second
+``EntityManager#find()`` call Doctrine will check the identity map first and
+doesn't need to make that database roundtrip.
+
+Even if you get a proxy object first then fetch the object by the same id you
+will still end up with the same reference:
+
+.. code-block:: php
+
+    public function testIdentityMapReference()
+    {
+        $objectA = $this->entityManager->getReference('EntityName', 1);
+        // check for proxyinterface
+        $this->assertInstanceOf('Doctrine\ORM\Proxy\Proxy', $objectA);
+
+        $objectB = $this->entityManager->find('EntityName', 1);
+
+        $this->assertSame($objectA, $objectB)
+    }
+
+The identity map being indexed by primary keys only allows shortcuts when you
+ask for objects by primary key. Assume you have the following ``persons``
+table:
+
+::
+
+    id | name
+    -------------
+    1  | Benjamin
+    2  | Bud
+
+Take the following example where two
+consecutive calls are made against a repository to fetch an entity by a set of
+criteria:
+
+.. code-block:: php
+
+    public function testIdentityMapRepositoryFindBy()
+    {
+        $repository = $this->entityManager->getRepository('Person');
+        $objectA = $repository->findOneBy(array('name' => 'Benjamin'));
+        $objectB = $repository->findOneBy(array('name' => 'Benjamin'));
+
+        $this->assertSame($objectA, $objectB);
+    }
+
+This query will still return the same references and `$objectA` and `$objectB`
+are indeed referencing the same object. However when checking your SQL logs you
+will realize that two queries have been executed against the database. Doctrine
+only knows objects by id, so a query for different criteria has to go to the
+database, even if it was executed just before.
+
+But instead of creating a second Person object Doctrine first gets the primary
+key from the row and check if it already has an object inside the UnitOfWork
+with that primary key. In our example it finds an object and decides to return
+this instead of creating a new one.
+
+The identity map has a second use-case. When you call ``EntityManager#flush``
+Doctrine will ask the identity map for all objects that are currently managed.
+This means you don't have to call ``EntityManager#persist`` over and over again
+to pass known objects to the EntityManager. This is a NO-OP for known entities,
+but leads to much code written that is confusing to other developers.
+
+The following code WILL update your database with the changes made to the
+``Person`` object, even if you did not call ``EntityManager#persist``:
+
+.. code-block:: php
+
+    <?php
+    $user = $entityManager->find("Person", 1);
+    $user->setName("Guilherme");
+    $entityManager->flush();
+
+How Doctrine Detects Changes
+----------------------------
+
+Doctrine is a data-mapper that tries to achieve persistence-ignorance (PI).
+This means you map php objects into a relational database that don't
+necessarily know about the database at all. A natural question would now be,
+"how does Doctrine even detect objects have changed?". 
+
+For this Doctrine keeps a second map inside the UnitOfWork. Whenever you fetch
+an object from the database Doctrine will keep a copy of all the properties and
+associations inside the UnitOfWork. Because variables in the PHP language are
+subject to "copy-on-write" the memory usage of a PHP request that only reads
+objects from the database is the same as if Doctrine did not keep this variable
+copy. Only if you start changing variables PHP will create new variables internally
+that consume new memory.
+
+Now whenever you call ``EntityManager#flush`` Doctrine will iterate over the
+Identity Map and for each object compares the original property and association
+values with the values that are currently set on the object. If changes are
+detected then the object is queued for a SQL UPDATE operation. Only the fields
+that actually changed are updated.
+
+This process has an obvious performance impact. The larger the size of the
+UnitOfWork is, the longer this computation takes. There are several ways to
+optimize the performance of the Flush Operation:
+
+- Mark entities as read only. These entities can only be inserted or removed,
+  but are never updated. They are omitted in the changeset calculation.
+- Temporarily mark entities as read only. If you have a very large UnitOfWork
+  but know that a large set of entities has not changed, just mark them as read
+  only with ``$entityManager->getUnitOfWork()->markReadOnly($entity)``.
+- Flush only a single entity with ``$entityManager->flush($entity)``.
+- Use :doc:`Change Tracking Policies <change-tracking-policies>` to use more
+  explicit strategies of notifying the UnitOfWork what objects/properties
+  changed.
+
+
+Query Internals
+---------------
+
+The different ORM Layers
+------------------------
+
+Doctrine ships with a set of layers with different responsibilities. This
+section gives a short explanation of each layer.
+
+Hydration
+~~~~~~~~~
+
+Responsible for creating a final result from a raw database statement and a
+result-set mapping object. The developer can choose which kind of result they
+wish to be hydrated. Default result-types include:
+
+- SQL to Entities
+- SQL to structured Arrays
+- SQL to simple scalar result arrays
+- SQL to a single result variable
+
+Hydration to entities and arrays is one of the most complex parts of Doctrine
+algorithm-wise. It can build results with for example:
+
+- Single table selects
+- Joins with n:1 or 1:n cardinality, grouping belonging to the same parent.
+- Mixed results of objects and scalar values
+- Hydration of results by a given scalar value as key.
+
+Persisters
+~~~~~~~~~~
+
+tbr
+
+UnitOfWork
+~~~~~~~~~~
+
+tbr
+
+ResultSetMapping
+~~~~~~~~~~~~~~~~
+
+tbr
+
+DQL Parser
+~~~~~~~~~~
+
+tbr
+
+SQLWalker
+~~~~~~~~~
+
+tbr
+
+EntityManager
+~~~~~~~~~~~~~
+
+tbr
+
+ClassMetadataFactory
+~~~~~~~~~~~~~~~~~~~~
+
+tbr
+

vendor/doctrine/orm/docs/en/reference/working-with-associations.rst

@@ -0,0 +1,728 @@
+Working with Associations
+=========================
+
+Associations between entities are represented just like in regular
+object-oriented PHP code using references to other objects or
+collections of objects.
+
+Changes to associations in your code are not synchronized to the
+database directly, only when calling ``EntityManager#flush()``.
+
+There are other concepts you should know about when working
+with associations in Doctrine:
+
+-  If an entity is removed from a collection, the association is
+   removed, not the entity itself. A collection of entities always
+   only represents the association to the containing entities, not the
+   entity itself.
+-  When a bidirectional association is updated, Doctrine only checks
+   on one of both sides for these changes. This is called the :doc:`owning side <unitofwork-associations>`
+   of the association.
+-  A property with a reference to many entities has to be instances of the
+   ``Doctrine\Common\Collections\Collection`` interface.
+
+Association Example Entities
+----------------------------
+
+We will use a simple comment system with Users and Comments as
+entities to show examples of association management. See the PHP
+docblocks of each association in the following example for
+information about its type and if it's the owning or inverse side.
+
+.. code-block:: php
+
+    <?php
+    /** @Entity */
+    class User
+    {
+        /** @Id @GeneratedValue @Column(type="string") */
+        private $id;
+    
+        /**
+         * Bidirectional - Many users have Many favorite comments (OWNING SIDE)
+         *
+         * @ManyToMany(targetEntity="Comment", inversedBy="userFavorites")
+         * @JoinTable(name="user_favorite_comments")
+         */
+        private $favorites;
+    
+        /**
+         * Unidirectional - Many users have marked many comments as read
+         *
+         * @ManyToMany(targetEntity="Comment")
+         * @JoinTable(name="user_read_comments")
+         */
+        private $commentsRead;
+    
+        /**
+         * Bidirectional - One-To-Many (INVERSE SIDE)
+         *
+         * @OneToMany(targetEntity="Comment", mappedBy="author")
+         */
+        private $commentsAuthored;
+    
+        /**
+         * Unidirectional - Many-To-One
+         *
+         * @ManyToOne(targetEntity="Comment")
+         */
+        private $firstComment;
+    }
+    
+    /** @Entity */
+    class Comment
+    {
+        /** @Id @GeneratedValue @Column(type="string") */
+        private $id;
+    
+        /**
+         * Bidirectional - Many comments are favorited by many users (INVERSE SIDE)
+         *
+         * @ManyToMany(targetEntity="User", mappedBy="favorites")
+         */
+        private $userFavorites;
+    
+        /**
+         * Bidirectional - Many Comments are authored by one user (OWNING SIDE)
+         *
+         * @ManyToOne(targetEntity="User", inversedBy="commentsAuthored")
+         */
+         private $author;
+    }
+
+This two entities generate the following MySQL Schema (Foreign Key
+definitions omitted):
+
+.. code-block:: sql
+
+    CREATE TABLE User (
+        id VARCHAR(255) NOT NULL,
+        firstComment_id VARCHAR(255) DEFAULT NULL,
+        PRIMARY KEY(id)
+    ) ENGINE = InnoDB;
+    
+    CREATE TABLE Comment (
+        id VARCHAR(255) NOT NULL,
+        author_id VARCHAR(255) DEFAULT NULL,
+        PRIMARY KEY(id)
+    ) ENGINE = InnoDB;
+    
+    CREATE TABLE user_favorite_comments (
+        user_id VARCHAR(255) NOT NULL,
+        favorite_comment_id VARCHAR(255) NOT NULL,
+        PRIMARY KEY(user_id, favorite_comment_id)
+    ) ENGINE = InnoDB;
+    
+    CREATE TABLE user_read_comments (
+        user_id VARCHAR(255) NOT NULL,
+        comment_id VARCHAR(255) NOT NULL,
+        PRIMARY KEY(user_id, comment_id)
+    ) ENGINE = InnoDB;
+
+Establishing Associations
+-------------------------
+
+Establishing an association between two entities is
+straight-forward. Here are some examples for the unidirectional
+relations of the ``User``:
+
+.. code-block:: php
+
+    <?php
+    class User
+    {
+        // ...
+        public function getReadComments() {
+             return $this->commentsRead;
+        }
+    
+        public function setFirstComment(Comment $c) {
+            $this->firstComment = $c;
+        }
+    }
+
+The interaction code would then look like in the following snippet
+(``$em`` here is an instance of the EntityManager):
+
+.. code-block:: php
+
+    <?php
+    $user = $em->find('User', $userId);
+    
+    // unidirectional many to many
+    $comment = $em->find('Comment', $readCommentId);
+    $user->getReadComments()->add($comment);
+    
+    $em->flush();
+    
+    // unidirectional many to one
+    $myFirstComment = new Comment();
+    $user->setFirstComment($myFirstComment);
+    
+    $em->persist($myFirstComment);
+    $em->flush();
+
+In the case of bi-directional associations you have to update the
+fields on both sides:
+
+.. code-block:: php
+
+    <?php
+    class User
+    {
+        // ..
+    
+        public function getAuthoredComments() {
+            return $this->commentsAuthored;
+        }
+    
+        public function getFavoriteComments() {
+            return $this->favorites;
+        }
+    }
+    
+    class Comment
+    {
+        // ...
+    
+        public function getUserFavorites() {
+            return $this->userFavorites;
+        }
+    
+        public function setAuthor(User $author = null) {
+            $this->author = $author;
+        }
+    }
+    
+    // Many-to-Many
+    $user->getFavorites()->add($favoriteComment);
+    $favoriteComment->getUserFavorites()->add($user);
+    
+    $em->flush();
+    
+    // Many-To-One / One-To-Many Bidirectional
+    $newComment = new Comment();
+    $user->getAuthoredComments()->add($newComment);
+    $newComment->setAuthor($user);
+    
+    $em->persist($newComment);
+    $em->flush();
+
+Notice how always both sides of the bidirectional association are
+updated. The previous unidirectional associations were simpler to
+handle.
+
+Removing Associations
+---------------------
+
+Removing an association between two entities is similarly
+straight-forward. There are two strategies to do so, by key and by
+element. Here are some examples:
+
+.. code-block:: php
+
+    <?php
+    // Remove by Elements
+    $user->getComments()->removeElement($comment);
+    $comment->setAuthor(null);
+    
+    $user->getFavorites()->removeElement($comment);
+    $comment->getUserFavorites()->removeElement($user);
+    
+    // Remove by Key
+    $user->getComments()->remove($ithComment);
+    $comment->setAuthor(null);
+
+You need to call ``$em->flush()`` to make persist these changes in
+the database permanently.
+
+Notice how both sides of the bidirectional association are always
+updated. Unidirectional associations are consequently simpler to
+handle.
+
+Also note that if you use type-hinting in your methods, you will 
+have to specify a nullable type, i.e. ``setAddress(?Address $address)``,
+otherwise ``setAddress(null)`` will fail to remove the association.
+Another way to deal with this is to provide a special method, like
+``removeAddress()``. This can also provide better encapsulation as
+it hides the internal meaning of not having an address.
+
+When working with collections, keep in mind that a Collection is
+essentially an ordered map (just like a PHP array). That is why the
+``remove`` operation accepts an index/key. ``removeElement`` is a
+separate method that has O(n) complexity using ``array_search``,
+where n is the size of the map.
+
+.. note::
+
+    Since Doctrine always only looks at the owning side of a
+    bidirectional association for updates, it is not necessary for
+    write operations that an inverse collection of a bidirectional
+    one-to-many or many-to-many association is updated. This knowledge
+    can often be used to improve performance by avoiding the loading of
+    the inverse collection.
+
+
+You can also clear the contents of a whole collection using the
+``Collections::clear()`` method. You should be aware that using
+this method can lead to a straight and optimized database delete or
+update call during the flush operation that is not aware of
+entities that have been re-added to the collection.
+
+Say you clear a collection of tags by calling
+``$post->getTags()->clear();`` and then call
+``$post->getTags()->add($tag)``. This will not recognize the tag having 
+already been added previously and will consequently issue two separate database 
+calls.
+
+Association Management Methods
+------------------------------
+
+It is generally a good idea to encapsulate proper association
+management inside the entity classes. This makes it easier to use
+the class correctly and can encapsulate details about how the
+association is maintained.
+
+The following code shows updates to the previous User and Comment
+example that encapsulate much of the association management code:
+
+.. code-block:: php
+
+    <?php
+    class User
+    {
+        //...
+        public function markCommentRead(Comment $comment) {
+            // Collections implement ArrayAccess
+            $this->commentsRead[] = $comment;
+        }
+    
+        public function addComment(Comment $comment) {
+            if (count($this->commentsAuthored) == 0) {
+                $this->setFirstComment($comment);
+            }
+            $this->comments[] = $comment;
+            $comment->setAuthor($this);
+        }
+    
+        private function setFirstComment(Comment $c) {
+            $this->firstComment = $c;
+        }
+    
+        public function addFavorite(Comment $comment) {
+            $this->favorites->add($comment);
+            $comment->addUserFavorite($this);
+        }
+    
+        public function removeFavorite(Comment $comment) {
+            $this->favorites->removeElement($comment);
+            $comment->removeUserFavorite($this);
+        }
+    }
+    
+    class Comment
+    {
+        // ..
+    
+        public function addUserFavorite(User $user) {
+            $this->userFavorites[] = $user;
+        }
+    
+        public function removeUserFavorite(User $user) {
+            $this->userFavorites->removeElement($user);
+        }
+    }
+
+You will notice that ``addUserFavorite`` and ``removeUserFavorite``
+do not call ``addFavorite`` and ``removeFavorite``, thus the
+bidirectional association is strictly-speaking still incomplete.
+However if you would naively add the ``addFavorite`` in
+``addUserFavorite``, you end up with an infinite loop, so more work
+is needed. As you can see, proper bidirectional association
+management in plain OOP is a non-trivial task and encapsulating all
+the details inside the classes can be challenging.
+
+.. note::
+
+    If you want to make sure that your collections are perfectly
+    encapsulated you should not return them from a
+    ``getCollectionName()`` method directly, but call
+    ``$collection->toArray()``. This way a client programmer for the
+    entity cannot circumvent the logic you implement on your entity for
+    association management. For example:
+
+
+.. code-block:: php
+
+    <?php
+    class User {
+        public function getReadComments() {
+            return $this->commentsRead->toArray();
+        }
+    }
+
+This will however always initialize the collection, with all the
+performance penalties given the size. In some scenarios of large
+collections it might even be a good idea to completely hide the
+read access behind methods on the EntityRepository.
+
+There is no single, best way for association management. It greatly
+depends on the requirements of your concrete domain model as well
+as your preferences.
+
+Synchronizing Bidirectional Collections
+---------------------------------------
+
+In the case of Many-To-Many associations you as the developer have the 
+responsibility of keeping the collections on the owning and inverse side
+in sync when you apply changes to them. Doctrine can only
+guarantee a consistent state for the hydration, not for your client
+code.
+
+Using the User-Comment entities from above, a very simple example
+can show the possible caveats you can encounter:
+
+.. code-block:: php
+
+    <?php
+    $user->getFavorites()->add($favoriteComment);
+    // not calling $favoriteComment->getUserFavorites()->add($user);
+    
+    $user->getFavorites()->contains($favoriteComment); // TRUE
+    $favoriteComment->getUserFavorites()->contains($user); // FALSE
+
+There are two approaches to handle this problem in your code:
+
+
+1. Ignore updating the inverse side of bidirectional collections,
+   BUT never read from them in requests that changed their state. In
+   the next request Doctrine hydrates the consistent collection state
+   again.
+2. Always keep the bidirectional collections in sync through
+   association management methods. Reads of the Collections directly
+   after changes are consistent then.
+
+.. _transitive-persistence:
+
+Transitive persistence / Cascade Operations
+-------------------------------------------
+
+Doctrine 2 provides a mechanism for transitive persistence through cascading of certain operations.
+Each association to another entity or a collection of
+entities can be configured to automatically cascade the following operations to the associated entities:
+``persist``, ``remove``, ``merge``, ``detach``, ``refresh`` or ``all``.
+
+The main use case for ``cascade: persist`` is to avoid "exposing" associated entities to your PHP application.
+Continuing with the User-Comment example of this chapter, this is how the creation of a new user and a new
+comment might look like in your controller (without ``cascade: persist``):
+
+.. code-block:: php
+
+    <?php
+    $user = new User();
+    $myFirstComment = new Comment();
+    $user->addComment($myFirstComment);
+    
+    $em->persist($user);
+    $em->persist($myFirstComment); // required, if `cascade: persist` is not set
+    $em->flush();
+
+Note that the Comment entity is instantiated right here in the controller.
+To avoid this, ``cascade: persist`` allows you to "hide" the Comment entity from the controller,
+only accessing it through the User entity:
+
+.. code-block:: php
+
+    <?php
+    // User entity
+    class User
+    {
+        private $id;
+        private $comments;
+
+        public function __construct()
+        {
+            $this->id = User::new();
+            $this->comments = new ArrayCollection();
+        }
+
+        public function comment(string $text, DateTimeInterface $time) : void
+        {
+            $newComment = Comment::create($text, $time);
+            $newComment->setUser($this);
+            $this->comments->add($newComment);
+        }
+
+        // ...
+    }
+
+If you then set up the cascading to the ``User#commentsAuthored`` property...
+
+.. code-block:: php
+
+    <?php
+    class User
+    {
+        //...
+        /**
+         * Bidirectional - One-To-Many (INVERSE SIDE)
+         *
+         * @OneToMany(targetEntity="Comment", mappedBy="author", cascade={"persist", "remove"})
+         */
+        private $commentsAuthored;
+        //...
+    }
+
+...you can now create a user and an associated comment like this:
+
+.. code-block:: php
+
+    <?php
+    $user = new User();
+    $user->comment('Lorem ipsum', new DateTime());
+    
+    $em->persist($user);
+    $em->flush();
+
+.. note::
+
+    The idea of ``cascade: persist`` is not to save you any lines of code in the controller.
+    If you instantiate the comment object in the controller (i.e. don't set up the user entity as shown above),
+    even with ``cascade: persist`` you still have to call ``$myFirstComment->setUser($user);``.
+
+Thanks to ``cascade: remove``, you can easily delete a user and all linked comments without having to loop through them:
+
+.. code-block:: php
+
+    <?php
+    $user = $em->find('User', $deleteUserId);
+
+    $em->remove($user);
+    $em->flush();
+
+.. note::
+
+    Cascade operations are performed in memory. That means collections and related entities
+    are fetched into memory (even if they are marked as lazy) when
+    the cascade operation is about to be performed. This approach allows
+    entity lifecycle events to be performed for each of these operations.
+
+    However, pulling object graphs into memory on cascade can cause considerable performance
+    overhead, especially when the cascaded collections are large. Make sure
+    to weigh the benefits and downsides of each cascade operation that you define.
+
+    To rely on the database level cascade operations for the delete operation instead, you can
+    configure each join column with :doc:`the onDelete option <working-with-objects>`.
+
+Even though automatic cascading is convenient, it should be used
+with care. Do not blindly apply ``cascade=all`` to all associations as
+it will unnecessarily degrade the performance of your application.
+For each cascade operation that gets activated, Doctrine also
+applies that operation to the association, be it single or
+collection valued.
+
+Persistence by Reachability: Cascade Persist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are additional semantics that apply to the Cascade Persist
+operation. During each ``flush()`` operation Doctrine detects if there
+are new entities in any collection and three possible cases can
+happen:
+
+
+1. New entities in a collection marked as ``cascade: persist`` will be
+   directly persisted by Doctrine.
+2. New entities in a collection not marked as ``cascade: persist`` will
+   produce an Exception and rollback the ``flush()`` operation.
+3. Collections without new entities are skipped.
+
+This concept is called Persistence by Reachability: New entities
+that are found on already managed entities are automatically
+persisted as long as the association is defined as ``cascade: persist``.
+
+Orphan Removal
+--------------
+
+There is another concept of cascading that is relevant only when removing entities
+from collections. If an Entity of type ``A`` contains references to privately
+owned Entities ``B`` then if the reference from ``A`` to ``B`` is removed the
+entity ``B`` should also be removed, because it is not used anymore.
+
+OrphanRemoval works with one-to-one, one-to-many and many-to-many associations.
+
+.. note::
+
+    When using the ``orphanRemoval=true`` option Doctrine makes the assumption
+    that the entities are privately owned and will **NOT** be reused by other entities.
+    If you neglect this assumption your entities will get deleted by Doctrine even if
+    you assigned the orphaned entity to another one.
+
+As a better example consider an Addressbook application where you have Contacts, Addresses
+and StandingData:
+
+.. code-block:: php
+
+    <?php
+
+    namespace Addressbook;
+
+    use Doctrine\Common\Collections\ArrayCollection;
+
+    /**
+     * @Entity
+     */
+    class Contact
+    {
+        /** @Id @Column(type="integer") @GeneratedValue */
+        private $id;
+
+        /** @OneToOne(targetEntity="StandingData", orphanRemoval=true) */
+        private $standingData;
+
+        /** @OneToMany(targetEntity="Address", mappedBy="contact", orphanRemoval=true) */
+        private $addresses;
+
+        public function __construct()
+        {
+            $this->addresses = new ArrayCollection();
+        }
+
+        public function newStandingData(StandingData $sd)
+        {
+            $this->standingData = $sd;
+        }
+
+        public function removeAddress($pos)
+        {
+            unset($this->addresses[$pos]);
+        }
+    }
+
+Now two examples of what happens when you remove the references:
+
+.. code-block:: php
+
+    <?php
+
+    $contact = $em->find("Addressbook\Contact", $contactId);
+    $contact->newStandingData(new StandingData("Firstname", "Lastname", "Street"));
+    $contact->removeAddress(1);
+
+    $em->flush();
+
+In this case you have not only changed the ``Contact`` entity itself but 
+you have also removed the references for standing data and as well as one 
+address reference. When flush is called not only are the references removed 
+but both the old standing data and the one address entity are also deleted 
+from the database.
+
+.. _filtering-collections:
+
+Filtering Collections
+---------------------
+
+Collections have a filtering API that allows to slice parts of data from
+a collection. If the collection has not been loaded from the database yet,
+the filtering API can work on the SQL level to make optimized access to
+large collections.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\Common\Collections\Criteria;
+
+    $group          = $entityManager->find('Group', $groupId);
+    $userCollection = $group->getUsers();
+
+    $criteria = Criteria::create()
+        ->where(Criteria::expr()->eq("birthday", "1982-02-17"))
+        ->orderBy(array("username" => Criteria::ASC))
+        ->setFirstResult(0)
+        ->setMaxResults(20)
+    ;
+
+    $birthdayUsers = $userCollection->matching($criteria);
+
+.. tip::
+
+    You can move the access of slices of collections into dedicated methods of
+    an entity. For example ``Group#getTodaysBirthdayUsers()``.
+
+The Criteria has a limited matching language that works both on the
+SQL and on the PHP collection level. This means you can use collection matching
+interchangeably, independent of in-memory or sql-backed collections.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\Common\Collections;
+
+    class Criteria
+    {
+        /**
+         * @return Criteria
+         */
+        static public function create();
+        /**
+         * @param Expression $where
+         * @return Criteria
+         */
+        public function where(Expression $where);
+        /**
+         * @param Expression $where
+         * @return Criteria
+         */
+        public function andWhere(Expression $where);
+        /**
+         * @param Expression $where
+         * @return Criteria
+         */
+        public function orWhere(Expression $where);
+        /**
+         * @param array $orderings
+         * @return Criteria
+         */
+        public function orderBy(array $orderings);
+        /**
+         * @param int $firstResult
+         * @return Criteria
+         */
+        public function setFirstResult($firstResult);
+        /**
+         * @param int $maxResults
+         * @return Criteria
+         */
+        public function setMaxResults($maxResults);
+        public function getOrderings();
+        public function getWhereExpression();
+        public function getFirstResult();
+        public function getMaxResults();
+    }
+
+You can build expressions through the ExpressionBuilder. It has the following
+methods:
+
+* ``andX($arg1, $arg2, ...)``
+* ``orX($arg1, $arg2, ...)``
+* ``eq($field, $value)``
+* ``gt($field, $value)``
+* ``lt($field, $value)``
+* ``lte($field, $value)``
+* ``gte($field, $value)``
+* ``neq($field, $value)``
+* ``isNull($field)``
+* ``in($field, array $values)``
+* ``notIn($field, array $values)``
+* ``contains($field, $value)``
+* ``memberOf($value, $field)``
+* ``startsWith($field, $value)``
+* ``endsWith($field, $value)``
+
+
+.. note::
+
+    There is a limitation on the compatibility of Criteria comparisons.
+    You have to use scalar values only as the value in a comparison or
+    the behaviour between different backends is not the same.

vendor/doctrine/orm/docs/en/reference/working-with-objects.rst

@@ -0,0 +1,878 @@
+Working with Objects
+====================
+
+In this chapter we will help you understand the ``EntityManager``
+and the ``UnitOfWork``. A Unit of Work is similar to an
+object-level transaction. A new Unit of Work is implicitly started
+when an EntityManager is initially created or after
+``EntityManager#flush()`` has been invoked. A Unit of Work is
+committed (and a new one started) by invoking
+``EntityManager#flush()``.
+
+A Unit of Work can be manually closed by calling
+EntityManager#close(). Any changes to objects within this Unit of
+Work that have not yet been persisted are lost.
+
+.. note::
+
+    It is very important to understand that only
+    ``EntityManager#flush()`` ever causes write operations against the
+    database to be executed. Any other methods such as
+    ``EntityManager#persist($entity)`` or
+    ``EntityManager#remove($entity)`` only notify the UnitOfWork to
+    perform these operations during flush.
+
+    Not calling ``EntityManager#flush()`` will lead to all changes
+    during that request being lost.
+
+.. note::
+
+    Doctrine does NEVER touch the public API of methods in your entity 
+    classes (like getters and setters) nor the constructor method.
+    Instead, it uses reflection to get/set data from/to your entity objects.
+    When Doctrine fetches data from DB and saves it back,
+    any code put in your get/set methods won't be implicitly taken into account.
+
+Entities and the Identity Map
+-----------------------------
+
+Entities are objects with identity. Their identity has a conceptual
+meaning inside your domain. In a CMS application each article has a
+unique id. You can uniquely identify each article by that id.
+
+Take the following example, where you find an article with the
+headline "Hello World" with the ID 1234:
+
+.. code-block:: php
+
+    <?php
+    $article = $entityManager->find('CMS\Article', 1234);
+    $article->setHeadline('Hello World dude!');
+    
+    $article2 = $entityManager->find('CMS\Article', 1234);
+    echo $article2->getHeadline();
+
+In this case the Article is accessed from the entity manager twice,
+but modified in between. Doctrine 2 realizes this and will only
+ever give you access to one instance of the Article with ID 1234,
+no matter how often do you retrieve it from the EntityManager and
+even no matter what kind of Query method you are using (find,
+Repository Finder or DQL). This is called "Identity Map" pattern,
+which means Doctrine keeps a map of each entity and ids that have
+been retrieved per PHP request and keeps returning you the same
+instances.
+
+In the previous example the echo prints "Hello World dude!" to the
+screen. You can even verify that ``$article`` and ``$article2`` are
+indeed pointing to the same instance by running the following
+code:
+
+.. code-block:: php
+
+    <?php
+    if ($article === $article2) {
+        echo "Yes we are the same!";
+    }
+
+Sometimes you want to clear the identity map of an EntityManager to
+start over. We use this regularly in our unit-tests to enforce
+loading objects from the database again instead of serving them
+from the identity map. You can call ``EntityManager#clear()`` to
+achieve this result.
+
+Entity Object Graph Traversal
+-----------------------------
+
+Although Doctrine allows for a complete separation of your domain
+model (Entity classes) there will never be a situation where
+objects are "missing" when traversing associations. You can walk
+all the associations inside your entity models as deep as you
+want.
+
+Take the following example of a single ``Article`` entity fetched
+from newly opened EntityManager.
+
+.. code-block:: php
+
+    <?php
+    /** @Entity */
+    class Article
+    {
+        /** @Id @Column(type="integer") @GeneratedValue */
+        private $id;
+    
+        /** @Column(type="string") */
+        private $headline;
+    
+        /** @ManyToOne(targetEntity="User") */
+        private $author;
+    
+        /** @OneToMany(targetEntity="Comment", mappedBy="article") */
+        private $comments;
+    
+        public function __construct()
+        {
+            $this->comments = new ArrayCollection();
+        }
+    
+        public function getAuthor() { return $this->author; }
+        public function getComments() { return $this->comments; }
+    }
+    
+    $article = $em->find('Article', 1);
+
+This code only retrieves the ``Article`` instance with id 1 executing
+a single SELECT statement against the articles table in the database.
+You can still access the associated properties author and comments
+and the associated objects they contain.
+
+This works by utilizing the lazy loading pattern. Instead of
+passing you back a real Author instance and a collection of
+comments Doctrine will create proxy instances for you. Only if you
+access these proxies for the first time they will go through the
+EntityManager and load their state from the database.
+
+This lazy-loading process happens behind the scenes, hidden from
+your code. See the following code:
+
+.. code-block:: php
+
+    <?php
+    $article = $em->find('Article', 1);
+    
+    // accessing a method of the user instance triggers the lazy-load
+    echo "Author: " . $article->getAuthor()->getName() . "\n";
+    
+    // Lazy Loading Proxies pass instanceof tests:
+    if ($article->getAuthor() instanceof User) {
+        // a User Proxy is a generated "UserProxy" class
+    }
+    
+    // accessing the comments as an iterator triggers the lazy-load
+    // retrieving ALL the comments of this article from the database
+    // using a single SELECT statement
+    foreach ($article->getComments() as $comment) {
+        echo $comment->getText() . "\n\n";
+    }
+    
+    // Article::$comments passes instanceof tests for the Collection interface
+    // But it will NOT pass for the ArrayCollection interface
+    if ($article->getComments() instanceof \Doctrine\Common\Collections\Collection) {
+        echo "This will always be true!";
+    }
+
+A slice of the generated proxy classes code looks like the
+following piece of code. A real proxy class override ALL public
+methods along the lines of the ``getName()`` method shown below:
+
+.. code-block:: php
+
+    <?php
+    class UserProxy extends User implements Proxy
+    {
+        private function _load()
+        {
+            // lazy loading code
+        }
+    
+        public function getName()
+        {
+            $this->_load();
+            return parent::getName();
+        }
+        // .. other public methods of User
+    }
+
+.. warning::
+
+    Traversing the object graph for parts that are lazy-loaded will
+    easily trigger lots of SQL queries and will perform badly if used
+    to heavily. Make sure to use DQL to fetch-join all the parts of the
+    object-graph that you need as efficiently as possible.
+
+
+Persisting entities
+-------------------
+
+An entity can be made persistent by passing it to the
+``EntityManager#persist($entity)`` method. By applying the persist
+operation on some entity, that entity becomes MANAGED, which means
+that its persistence is from now on managed by an EntityManager. As
+a result the persistent state of such an entity will subsequently
+be properly synchronized with the database when
+``EntityManager#flush()`` is invoked.
+
+.. note::
+
+    Invoking the ``persist`` method on an entity does NOT
+    cause an immediate SQL INSERT to be issued on the database.
+    Doctrine applies a strategy called "transactional write-behind",
+    which means that it will delay most SQL commands until
+    ``EntityManager#flush()`` is invoked which will then issue all
+    necessary SQL statements to synchronize your objects with the
+    database in the most efficient way and a single, short transaction,
+    taking care of maintaining referential integrity.
+
+
+Example:
+
+.. code-block:: php
+
+    <?php
+    $user = new User;
+    $user->setName('Mr.Right');
+    $em->persist($user);
+    $em->flush();
+
+.. note::
+
+    Generated entity identifiers / primary keys are
+    guaranteed to be available after the next successful flush
+    operation that involves the entity in question. You can not rely on
+    a generated identifier to be available directly after invoking
+    ``persist``. The inverse is also true. You can not rely on a
+    generated identifier being not available after a failed flush
+    operation.
+
+
+The semantics of the persist operation, applied on an entity X, are
+as follows:
+
+
+-  If X is a new entity, it becomes managed. The entity X will be
+   entered into the database as a result of the flush operation.
+-  If X is a preexisting managed entity, it is ignored by the
+   persist operation. However, the persist operation is cascaded to
+   entities referenced by X, if the relationships from X to these
+   other entities are mapped with cascade=PERSIST or cascade=ALL (see
+   ":ref:`transitive-persistence`").
+-  If X is a removed entity, it becomes managed.
+-  If X is a detached entity, an exception will be thrown on
+   flush.
+
+.. caution::
+
+    Do not pass detached entities to the persist operation. The persist operation always
+    considers entities that are not yet known to the ``EntityManager`` as new entities
+    (refer to the ``STATE_NEW`` constant inside the ``UnitOfWork``).
+
+Removing entities
+-----------------
+
+An entity can be removed from persistent storage by passing it to
+the ``EntityManager#remove($entity)`` method. By applying the
+``remove`` operation on some entity, that entity becomes REMOVED,
+which means that its persistent state will be deleted once
+``EntityManager#flush()`` is invoked.
+
+.. note::
+
+    Just like ``persist``, invoking ``remove`` on an entity
+    does NOT cause an immediate SQL DELETE to be issued on the
+    database. The entity will be deleted on the next invocation of
+    ``EntityManager#flush()`` that involves that entity. This
+    means that entities scheduled for removal can still be queried
+    for and appear in query and collection results. See
+    the section on :ref:`Database and UnitOfWork Out-Of-Sync <workingobjects_database_uow_outofsync>`
+    for more information.
+    
+
+Example:
+
+.. code-block:: php
+
+    <?php
+    $em->remove($user);
+    $em->flush();
+
+The semantics of the remove operation, applied to an entity X are
+as follows:
+
+
+-  If X is a new entity, it is ignored by the remove operation.
+   However, the remove operation is cascaded to entities referenced by
+   X, if the relationship from X to these other entities is mapped
+   with cascade=REMOVE or cascade=ALL (see ":ref:`transitive-persistence`").
+-  If X is a managed entity, the remove operation causes it to
+   become removed. The remove operation is cascaded to entities
+   referenced by X, if the relationships from X to these other
+   entities is mapped with cascade=REMOVE or cascade=ALL (see
+   ":ref:`transitive-persistence`").
+-  If X is a detached entity, an InvalidArgumentException will be
+   thrown.
+-  If X is a removed entity, it is ignored by the remove operation.
+-  A removed entity X will be removed from the database as a result
+   of the flush operation.
+
+After an entity has been removed its in-memory state is the same as
+before the removal, except for generated identifiers.
+
+Removing an entity will also automatically delete any existing
+records in many-to-many join tables that link this entity. The
+action taken depends on the value of the ``@joinColumn`` mapping
+attribute "onDelete". Either Doctrine issues a dedicated ``DELETE``
+statement for records of each join table or it depends on the
+foreign key semantics of onDelete="CASCADE".
+
+Deleting an object with all its associated objects can be achieved
+in multiple ways with very different performance impacts.
+
+
+1. If an association is marked as ``CASCADE=REMOVE`` Doctrine 2
+   will fetch this association. If its a Single association it will
+   pass this entity to
+   ``EntityManager#remove()``. If the association is a collection, Doctrine will loop over all    its elements and pass them to``EntityManager#remove()``.
+   In both cases the cascade remove semantics are applied recursively.
+   For large object graphs this removal strategy can be very costly.
+2. Using a DQL ``DELETE`` statement allows you to delete multiple
+   entities of a type with a single command and without hydrating
+   these entities. This can be very efficient to delete large object
+   graphs from the database.
+3. Using foreign key semantics ``onDelete="CASCADE"`` can force the
+   database to remove all associated objects internally. This strategy
+   is a bit tricky to get right but can be very powerful and fast. You
+   should be aware however that using strategy 1 (``CASCADE=REMOVE``)
+   completely by-passes any foreign key ``onDelete=CASCADE`` option,
+   because Doctrine will fetch and remove all associated entities
+   explicitly nevertheless.
+
+.. note::
+
+    Calling ``remove`` on an entity will remove the object from the identiy
+    map and therefore detach it. Querying the same entity again, for example 
+    via a lazy loaded relation, will return a new object. 
+
+
+Detaching entities
+------------------
+
+An entity is detached from an EntityManager and thus no longer
+managed by invoking the ``EntityManager#detach($entity)`` method on
+it or by cascading the detach operation to it. Changes made to the
+detached entity, if any (including removal of the entity), will not
+be synchronized to the database after the entity has been
+detached.
+
+Doctrine will not hold on to any references to a detached entity.
+
+Example:
+
+.. code-block:: php
+
+    <?php
+    $em->detach($entity);
+
+The semantics of the detach operation, applied to an entity X are
+as follows:
+
+
+-  If X is a managed entity, the detach operation causes it to
+   become detached. The detach operation is cascaded to entities
+   referenced by X, if the relationships from X to these other
+   entities is mapped with cascade=DETACH or cascade=ALL (see
+   ":ref:`transitive-persistence`"). Entities which previously referenced X
+   will continue to reference X.
+-  If X is a new or detached entity, it is ignored by the detach
+   operation.
+-  If X is a removed entity, the detach operation is cascaded to
+   entities referenced by X, if the relationships from X to these
+   other entities is mapped with cascade=DETACH or cascade=ALL (see
+   ":ref:`transitive-persistence`"). Entities which previously referenced X
+   will continue to reference X.
+
+There are several situations in which an entity is detached
+automatically without invoking the ``detach`` method:
+
+
+-  When ``EntityManager#clear()`` is invoked, all entities that are
+   currently managed by the EntityManager instance become detached.
+-  When serializing an entity. The entity retrieved upon subsequent
+   unserialization will be detached (This is the case for all entities
+   that are serialized and stored in some cache, i.e. when using the
+   Query Result Cache).
+
+The ``detach`` operation is usually not as frequently needed and
+used as ``persist`` and ``remove``.
+
+Merging entities
+----------------
+
+Merging entities refers to the merging of (usually detached)
+entities into the context of an EntityManager so that they become
+managed again. To merge the state of an entity into an
+EntityManager use the ``EntityManager#merge($entity)`` method. The
+state of the passed entity will be merged into a managed copy of
+this entity and this copy will subsequently be returned.
+
+Example:
+
+.. code-block:: php
+
+    <?php
+    $detachedEntity = unserialize($serializedEntity); // some detached entity
+    $entity = $em->merge($detachedEntity);
+    // $entity now refers to the fully managed copy returned by the merge operation.
+    // The EntityManager $em now manages the persistence of $entity as usual.
+
+.. note::
+
+    When you want to serialize/unserialize entities you
+    have to make all entity properties protected, never private. The
+    reason for this is, if you serialize a class that was a proxy
+    instance before, the private variables won't be serialized and a
+    PHP Notice is thrown.
+
+
+The semantics of the merge operation, applied to an entity X, are
+as follows:
+
+
+-  If X is a detached entity, the state of X is copied onto a
+   pre-existing managed entity instance X' of the same identity.
+-  If X is a new entity instance, a new managed copy X' will be
+   created and the state of X is copied onto this managed instance.
+-  If X is a removed entity instance, an InvalidArgumentException
+   will be thrown.
+-  If X is a managed entity, it is ignored by the merge operation,
+   however, the merge operation is cascaded to entities referenced by
+   relationships from X if these relationships have been mapped with
+   the cascade element value MERGE or ALL (see ":ref:`transitive-persistence`").
+-  For all entities Y referenced by relationships from X having the
+   cascade element value MERGE or ALL, Y is merged recursively as Y'.
+   For all such Y referenced by X, X' is set to reference Y'. (Note
+   that if X is managed then X is the same object as X'.)
+-  If X is an entity merged to X', with a reference to another
+   entity Y, where cascade=MERGE or cascade=ALL is not specified, then
+   navigation of the same association from X' yields a reference to a
+   managed object Y' with the same persistent identity as Y.
+
+The ``merge`` operation will throw an ``OptimisticLockException``
+if the entity being merged uses optimistic locking through a
+version field and the versions of the entity being merged and the
+managed copy don't match. This usually means that the entity has
+been modified while being detached.
+
+The ``merge`` operation is usually not as frequently needed and
+used as ``persist`` and ``remove``. The most common scenario for
+the ``merge`` operation is to reattach entities to an EntityManager
+that come from some cache (and are therefore detached) and you want
+to modify and persist such an entity.
+
+.. warning::
+
+    If you need to perform multiple merges of entities that share certain subparts
+    of their object-graphs and cascade merge, then you have to call ``EntityManager#clear()`` between the
+    successive calls to ``EntityManager#merge()``. Otherwise you might end up with
+    multiple copies of the "same" object in the database, however with different ids.
+
+.. note::
+
+    If you load some detached entities from a cache and you do
+    not need to persist or delete them or otherwise make use of them
+    without the need for persistence services there is no need to use
+    ``merge``. I.e. you can simply pass detached objects from a cache
+    directly to the view.
+
+
+Synchronization with the Database
+---------------------------------
+
+The state of persistent entities is synchronized with the database
+on flush of an ``EntityManager`` which commits the underlying
+``UnitOfWork``. The synchronization involves writing any updates to
+persistent entities and their relationships to the database.
+Thereby bidirectional relationships are persisted based on the
+references held by the owning side of the relationship as explained
+in the Association Mapping chapter.
+
+When ``EntityManager#flush()`` is called, Doctrine inspects all
+managed, new and removed entities and will perform the following
+operations.
+
+.. _workingobjects_database_uow_outofsync:
+
+Effects of Database and UnitOfWork being Out-Of-Sync
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As soon as you begin to change the state of entities, call persist or remove the
+contents of the UnitOfWork and the database will drive out of sync. They can
+only be synchronized by calling ``EntityManager#flush()``. This section
+describes the effects of database and UnitOfWork being out of sync.
+
+-  Entities that are scheduled for removal can still be queried from the database.
+   They are returned from DQL and Repository queries and are visible in collections.
+-  Entities that are passed to ``EntityManager#persist`` do not turn up in query
+   results.
+-  Entities that have changed will not be overwritten with the state from the database.
+   This is because the identity map will detect the construction of an already existing
+   entity and assumes its the most up to date version.
+
+``EntityManager#flush()`` is never called implicitly by Doctrine. You always have to trigger it manually.
+
+Synchronizing New and Managed Entities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The flush operation applies to a managed entity with the following
+semantics:
+
+
+-  The entity itself is synchronized to the database using a SQL
+   UPDATE statement, only if at least one persistent field has
+   changed.
+-  No SQL updates are executed if the entity did not change.
+
+The flush operation applies to a new entity with the following
+semantics:
+
+
+-  The entity itself is synchronized to the database using a SQL
+   INSERT statement.
+
+For all (initialized) relationships of the new or managed entity
+the following semantics apply to each associated entity X:
+
+
+-  If X is new and persist operations are configured to cascade on
+   the relationship, X will be persisted.
+-  If X is new and no persist operations are configured to cascade
+   on the relationship, an exception will be thrown as this indicates
+   a programming error.
+-  If X is removed and persist operations are configured to cascade
+   on the relationship, an exception will be thrown as this indicates
+   a programming error (X would be re-persisted by the cascade).
+-  If X is detached and persist operations are configured to
+   cascade on the relationship, an exception will be thrown (This is
+   semantically the same as passing X to persist()).
+
+Synchronizing Removed Entities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The flush operation applies to a removed entity by deleting its
+persistent state from the database. No cascade options are relevant
+for removed entities on flush, the cascade remove option is already
+executed during ``EntityManager#remove($entity)``.
+
+The size of a Unit of Work
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The size of a Unit of Work mainly refers to the number of managed
+entities at a particular point in time.
+
+The cost of flushing
+~~~~~~~~~~~~~~~~~~~~
+
+How costly a flush operation is, mainly depends on two factors:
+
+
+-  The size of the EntityManager's current UnitOfWork.
+-  The configured change tracking policies
+
+You can get the size of a UnitOfWork as follows:
+
+.. code-block:: php
+
+    <?php
+    $uowSize = $em->getUnitOfWork()->size();
+
+The size represents the number of managed entities in the Unit of
+Work. This size affects the performance of flush() operations due
+to change tracking (see "Change Tracking Policies") and, of course,
+memory consumption, so you may want to check it from time to time
+during development.
+
+.. note::
+
+    Do not invoke ``flush`` after every change to an entity
+    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
+``EntityManager#getUnitOfWork()``. This will return the UnitOfWork
+instance the EntityManager is currently using.
+
+.. code-block:: php
+
+    <?php
+    $uow = $em->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.
+
+
+Entity State
+~~~~~~~~~~~~
+
+As outlined in the architecture overview an entity can be in one of
+four possible states: NEW, MANAGED, REMOVED, DETACHED. If you
+explicitly need to find out what the current state of an entity is
+in the context of a certain ``EntityManager`` you can ask the
+underlying ``UnitOfWork``:
+
+.. code-block:: php
+
+    <?php
+    switch ($em->getUnitOfWork()->getEntityState($entity)) {
+        case UnitOfWork::STATE_MANAGED:
+            ...
+        case UnitOfWork::STATE_REMOVED:
+            ...
+        case UnitOfWork::STATE_DETACHED:
+            ...
+        case UnitOfWork::STATE_NEW:
+            ...
+    }
+
+An entity is in MANAGED state if it is associated with an
+``EntityManager`` and it is not REMOVED.
+
+An entity is in REMOVED state after it has been passed to
+``EntityManager#remove()`` until the next flush operation of the
+same EntityManager. A REMOVED entity is still associated with an
+``EntityManager`` until the next flush operation.
+
+An entity is in DETACHED state if it has persistent state and
+identity but is currently not associated with an
+``EntityManager``.
+
+An entity is in NEW state if has no persistent state and identity
+and is not associated with an ``EntityManager`` (for example those
+just created via the "new" operator).
+
+Querying
+--------
+
+Doctrine 2 provides the following ways, in increasing level of
+power and flexibility, to query for persistent objects. You should
+always start with the simplest one that suits your needs.
+
+By Primary Key
+~~~~~~~~~~~~~~
+
+The most basic way to query for a persistent object is by its
+identifier / primary key using the
+``EntityManager#find($entityName, $id)`` method. Here is an
+example:
+
+.. code-block:: php
+
+    <?php
+    // $em instanceof EntityManager
+    $user = $em->find('MyProject\Domain\User', $id);
+
+The return value is either the found entity instance or null if no
+instance could be found with the given identifier.
+
+Essentially, ``EntityManager#find()`` is just a shortcut for the
+following:
+
+.. code-block:: php
+
+    <?php
+    // $em instanceof EntityManager
+    $user = $em->getRepository('MyProject\Domain\User')->find($id);
+
+``EntityManager#getRepository($entityName)`` returns a repository
+object which provides many ways to retrieve entities of the
+specified type. By default, the repository instance is of type
+``Doctrine\ORM\EntityRepository``. You can also use custom
+repository classes as shown later.
+
+By Simple Conditions
+~~~~~~~~~~~~~~~~~~~~
+
+To query for one or more entities based on several conditions that
+form a logical conjunction, use the ``findBy`` and ``findOneBy``
+methods on a repository as follows:
+
+.. code-block:: php
+
+    <?php
+    // $em instanceof EntityManager
+    
+    // All users that are 20 years old
+    $users = $em->getRepository('MyProject\Domain\User')->findBy(array('age' => 20));
+    
+    // All users that are 20 years old and have a surname of 'Miller'
+    $users = $em->getRepository('MyProject\Domain\User')->findBy(array('age' => 20, 'surname' => 'Miller'));
+    
+    // A single user by its nickname
+    $user = $em->getRepository('MyProject\Domain\User')->findOneBy(array('nickname' => 'romanb'));
+
+You can also load by owning side associations through the repository:
+
+.. code-block:: php
+
+    <?php
+    $number = $em->find('MyProject\Domain\Phonenumber', 1234);
+    $user = $em->getRepository('MyProject\Domain\User')->findOneBy(array('phone' => $number->getId()));
+
+The ``EntityRepository#findBy()`` method additionally accepts orderings, limit and offset as second to fourth parameters:
+
+.. code-block:: php
+
+    <?php
+    $tenUsers = $em->getRepository('MyProject\Domain\User')->findBy(array('age' => 20), array('name' => 'ASC'), 10, 0);
+
+If you pass an array of values Doctrine will convert the query into a WHERE field IN (..) query automatically:
+
+.. code-block:: php
+
+    <?php
+    $users = $em->getRepository('MyProject\Domain\User')->findBy(array('age' => array(20, 30, 40)));
+    // translates roughly to: SELECT * FROM users WHERE age IN (20, 30, 40)
+
+An EntityRepository also provides a mechanism for more concise
+calls through its use of ``__call``. Thus, the following two
+examples are equivalent:
+
+.. code-block:: php
+
+    <?php
+    // A single user by its nickname
+    $user = $em->getRepository('MyProject\Domain\User')->findOneBy(array('nickname' => 'romanb'));
+    
+    // A single user by its nickname (__call magic)
+    $user = $em->getRepository('MyProject\Domain\User')->findOneByNickname('romanb');
+
+Additionally, you can just count the result of the provided conditions when you don't really need the data:
+
+.. code-block:: php
+
+    <?php
+    // Check there is no user with nickname
+    $availableNickname = 0 === $em->getRepository('MyProject\Domain\User')->count(['nickname' => 'nonexistent']);
+
+By Criteria
+~~~~~~~~~~~
+
+.. versionadded:: 2.3
+
+The Repository implement the ``Doctrine\Common\Collections\Selectable``
+interface. That means you can build ``Doctrine\Common\Collections\Criteria``
+and pass them to the ``matching($criteria)`` method.
+
+See section `Filtering collections` of chapter :doc:`Working with Associations <working-with-associations>`
+
+By Eager Loading
+~~~~~~~~~~~~~~~~
+
+Whenever you query for an entity that has persistent associations
+and these associations are mapped as EAGER, they will automatically
+be loaded together with the entity being queried and is thus
+immediately available to your application.
+
+By Lazy Loading
+~~~~~~~~~~~~~~~
+
+Whenever you have a managed entity instance at hand, you can
+traverse and use any associations of that entity that are
+configured LAZY as if they were in-memory already. Doctrine will
+automatically load the associated objects on demand through the
+concept of lazy-loading.
+
+By DQL
+~~~~~~
+
+The most powerful and flexible method to query for persistent
+objects is the Doctrine Query Language, an object query language.
+DQL enables you to query for persistent objects in the language of
+objects. DQL understands classes, fields, inheritance and
+associations. DQL is syntactically very similar to the familiar SQL
+but *it is not SQL*.
+
+A DQL query is represented by an instance of the
+``Doctrine\ORM\Query`` class. You create a query using
+``EntityManager#createQuery($dql)``. Here is a simple example:
+
+.. code-block:: php
+
+    <?php
+    // $em instanceof EntityManager
+    
+    // All users with an age between 20 and 30 (inclusive).
+    $q = $em->createQuery("select u from MyDomain\Model\User u where u.age >= 20 and u.age <= 30");
+    $users = $q->getResult();
+
+Note that this query contains no knowledge about the relational
+schema, only about the object model. DQL supports positional as
+well as named parameters, many functions, (fetch) joins,
+aggregates, subqueries and much more. Detailed information about
+DQL and its syntax as well as the Doctrine class can be found in
+:doc:`the dedicated chapter <dql-doctrine-query-language>`.
+For programmatically building up queries based on conditions that
+are only known at runtime, Doctrine provides the special
+``Doctrine\ORM\QueryBuilder`` class. While this a powerful tool,
+it also brings more complexity to your code compared to plain DQL,
+so you should only use it when you need it. More information on
+constructing queries with a QueryBuilder can be found
+:doc:`in Query Builder chapter <query-builder>`.
+
+By Native Queries
+~~~~~~~~~~~~~~~~~
+
+As an alternative to DQL or as a fallback for special SQL
+statements native queries can be used. Native queries are built by
+using a hand-crafted SQL query and a ResultSetMapping that
+describes how the SQL result set should be transformed by Doctrine.
+More information about native queries can be found in
+:doc:`the dedicated chapter <native-sql>`.
+
+Custom Repositories
+~~~~~~~~~~~~~~~~~~~
+
+By default the EntityManager returns a default implementation of
+``Doctrine\ORM\EntityRepository`` when you call
+``EntityManager#getRepository($entityClass)``. You can overwrite
+this behaviour by specifying the class name of your own Entity
+Repository in the Annotation, XML or YAML metadata. In large
+applications that require lots of specialized DQL queries using a
+custom repository is one recommended way of grouping these queries
+in a central location.
+
+.. code-block:: php
+
+    <?php
+    namespace MyDomain\Model;
+    
+    use Doctrine\ORM\EntityRepository;
+    use Doctrine\ORM\Mapping as ORM;
+    
+    /**
+     * @ORM\Entity(repositoryClass="MyDomain\Model\UserRepository")
+     */
+    class User
+    {
+    
+    }
+    
+    class UserRepository extends EntityRepository
+    {
+        public function getAllAdminUsers()
+        {
+            return $this->_em->createQuery('SELECT u FROM MyDomain\Model\User u WHERE u.status = "admin"')
+                             ->getResult();
+        }
+    }
+
+You can access your repository now by calling:
+
+.. code-block:: php
+
+    <?php
+    // $em instanceof EntityManager
+    
+    $admins = $em->getRepository('MyDomain\Model\User')->getAllAdminUsers();
+
+

vendor/doctrine/orm/docs/en/reference/xml-mapping.rst

@@ -0,0 +1,782 @@
+XML Mapping
+===========
+
+The XML mapping driver enables you to provide the ORM metadata in
+form of XML documents.
+
+The XML driver is backed by an XML Schema document that describes
+the structure of a mapping document. The most recent version of the
+XML Schema document is available online at
+`https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd <https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd>`_.
+In order to point to the latest version of the document of a
+particular stable release branch, just append the release number,
+i.e.: doctrine-mapping-2.0.xsd The most convenient way to work with
+XML mapping files is to use an IDE/editor that can provide
+code-completion based on such an XML Schema document. The following
+is an outline of a XML mapping document with the proper xmlns/xsi
+setup for the latest code in trunk.
+
+.. code-block:: xml
+
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
+        ...
+
+    </doctrine-mapping>
+
+The XML mapping document of a class is loaded on-demand the first
+time it is requested and subsequently stored in the metadata cache.
+In order to work, this requires certain conventions:
+
+
+-  Each entity/mapped superclass must get its own dedicated XML
+   mapping document.
+-  The name of the mapping document must consist of the fully
+   qualified name of the class, where namespace separators are
+   replaced by dots (.). For example an Entity with the fully
+   qualified class-name "MyProject" would require a mapping file
+   "MyProject.Entities.User.dcm.xml" unless the extension is changed.
+-  All mapping documents should get the extension ".dcm.xml" to
+   identify it as a Doctrine mapping file. This is more of a
+   convention and you are not forced to do this. You can change the
+   file extension easily enough.
+
+.. code-block:: php
+
+    <?php
+    $driver->setFileExtension('.xml');
+
+It is recommended to put all XML mapping documents in a single
+folder but you can spread the documents over several folders if you
+want to. In order to tell the XmlDriver where to look for your
+mapping documents, supply an array of paths as the first argument
+of the constructor, like this:
+
+.. code-block:: php
+
+    <?php
+    $config = new \Doctrine\ORM\Configuration();
+    $driver = new \Doctrine\ORM\Mapping\Driver\XmlDriver(array('/path/to/files1', '/path/to/files2'));
+    $config->setMetadataDriverImpl($driver);
+
+.. warning::
+
+    Note that Doctrine ORM does not modify any settings for ``libxml``,
+    therefore, external XML entities may or may not be enabled or
+    configured correctly.
+    XML mappings are not XXE/XEE attack vectors since they are not
+    related with user input, but it is recommended that you do not
+    use external XML entities in your mapping files to avoid running
+    into unexpected behaviour.
+
+Simplified XML Driver
+~~~~~~~~~~~~~~~~~~~~~
+
+The Symfony project sponsored a driver that simplifies usage of the XML Driver.
+The changes between the original driver are:
+
+1. File Extension is .orm.xml
+2. Filenames are shortened, "MyProject\Entities\User" will become User.orm.xml
+3. You can add a global file and add multiple entities in this file.
+
+Configuration of this client works a little bit different:
+
+.. code-block:: php
+
+    <?php
+    $namespaces = array(
+        '/path/to/files1' => 'MyProject\Entities',
+        '/path/to/files2' => 'OtherProject\Entities'
+    );
+    $driver = new \Doctrine\ORM\Mapping\Driver\SimplifiedXmlDriver($namespaces);
+    $driver->setGlobalBasename('global'); // global.orm.xml
+
+Example
+-------
+
+As a quick start, here is a small example document that makes use
+of several common elements:
+
+.. code-block:: xml
+
+    // Doctrine.Tests.ORM.Mapping.User.dcm.xml
+    <?xml version="1.0" encoding="UTF-8"?>
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
+        <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
+
+            <indexes>
+                <index name="name_idx" columns="name"/>
+                <index columns="user_email"/>
+            </indexes>
+
+            <unique-constraints>
+                <unique-constraint columns="name,user_email" name="search_idx" />
+            </unique-constraints>
+
+            <lifecycle-callbacks>
+                <lifecycle-callback type="prePersist" method="doStuffOnPrePersist"/>
+                <lifecycle-callback type="prePersist" method="doOtherStuffOnPrePersistToo"/>
+                <lifecycle-callback type="postPersist" method="doStuffOnPostPersist"/>
+            </lifecycle-callbacks>
+
+            <id name="id" type="integer" column="id">
+                <generator strategy="AUTO"/>
+                <sequence-generator sequence-name="tablename_seq" allocation-size="100" initial-value="1" />
+            </id>
+
+            <field name="name" column="name" type="string" length="50" nullable="true" unique="true" />
+            <field name="email" column="user_email" type="string" column-definition="CHAR(32) NOT NULL" />
+
+            <one-to-one field="address" target-entity="Address" inversed-by="user">
+                <cascade><cascade-remove /></cascade>
+                <join-column name="address_id" referenced-column-name="id" on-delete="CASCADE" on-update="CASCADE"/>
+            </one-to-one>
+
+            <one-to-many field="phonenumbers" target-entity="Phonenumber" mapped-by="user">
+                <cascade>
+                    <cascade-persist/>
+                </cascade>
+                <order-by>
+                    <order-by-field name="number" direction="ASC" />
+                </order-by>
+            </one-to-many>
+
+            <many-to-many field="groups" target-entity="Group">
+                <cascade>
+                    <cascade-all/>
+                </cascade>
+                <join-table name="cms_users_groups">
+                    <join-columns>
+                        <join-column name="user_id" referenced-column-name="id" nullable="false" unique="false" />
+                    </join-columns>
+                    <inverse-join-columns>
+                        <join-column name="group_id" referenced-column-name="id" column-definition="INT NULL" />
+                    </inverse-join-columns>
+                </join-table>
+            </many-to-many>
+
+        </entity>
+
+    </doctrine-mapping>
+
+Be aware that class-names specified in the XML files should be
+fully qualified.
+
+XML-Element Reference
+---------------------
+
+The XML-Element reference explains all the tags and attributes that
+the Doctrine Mapping XSD Schema defines. You should read the
+Basic-, Association- and Inheritance Mapping chapters to understand
+what each of this definitions means in detail.
+
+Defining an Entity
+~~~~~~~~~~~~~~~~~~
+
+Each XML Mapping File contains the definition of one entity,
+specified as the ``<entity />`` element as a direct child of the
+``<doctrine-mapping />`` element:
+
+.. code-block:: xml
+
+    <doctrine-mapping>
+        <entity name="MyProject\User" table="cms_users" schema="schema_name" repository-class="MyProject\UserRepository">
+            <!-- definition here -->
+        </entity>
+    </doctrine-mapping>
+
+Required attributes:
+
+
+-  name - The fully qualified class-name of the entity.
+
+Optional attributes:
+
+
+-  **table** - The Table-Name to be used for this entity. Otherwise the
+   Unqualified Class-Name is used by default.
+-  **repository-class** - The fully qualified class-name of an
+   alternative ``Doctrine\ORM\EntityRepository`` implementation to be
+   used with this entity.
+-  **inheritance-type** - The type of inheritance, defaults to none. A
+   more detailed description follows in the
+   *Defining Inheritance Mappings* section.
+-  **read-only** - (>= 2.1) Specifies that this entity is marked as read only and not
+   considered for change-tracking. Entities of this type can be persisted
+   and removed though.
+-  **schema** - (>= 2.5) The schema the table lies in, for platforms that support schemas
+
+Defining Fields
+~~~~~~~~~~~~~~~
+
+Each entity class can contain zero to infinite fields that are
+managed by Doctrine. You can define them using the ``<field />``
+element as a children to the ``<entity />`` element. The field
+element is only used for primitive types that are not the ID of the
+entity. For the ID mapping you have to use the ``<id />`` element.
+
+.. code-block:: xml
+
+    <entity name="MyProject\User">
+
+        <field name="name" type="string" length="50" />
+        <field name="username" type="string" unique="true" />
+        <field name="age" type="integer" nullable="true" />
+        <field name="isActive" column="is_active" type="boolean" />
+        <field name="weight" type="decimal" scale="5" precision="2" />
+        <field name="login_count" type="integer" nullable="false">
+            <options>
+                <option name="comment">The number of times the user has logged in.</option>
+                <option name="default">0</option>
+            </options>
+        </field>
+    </entity>
+
+Required attributes:
+
+
+-  name - The name of the Property/Field on the given Entity PHP
+   class.
+
+Optional attributes:
+
+
+-  type - The ``Doctrine\DBAL\Types\Type`` name, defaults to
+   "string"
+-  column - Name of the column in the database, defaults to the
+   field name.
+-  length - The length of the given type, for use with strings
+   only.
+-  unique - Should this field contain a unique value across the
+   table? Defaults to false.
+-  nullable - Should this field allow NULL as a value? Defaults to
+   false.
+-  version - Should this field be used for optimistic locking? Only
+   works on fields with type integer or datetime.
+-  scale - Scale of a decimal type.
+-  precision - Precision of a decimal type.
+-  options - Array of additional options:
+
+   -  default - The default value to set for the column if no value
+      is supplied.
+   -  unsigned - Boolean value to determine if the column should
+      be capable of representing only non-negative integers
+      (applies only for integer column and might not be supported by
+      all vendors).
+   -  fixed - Boolean value to determine if the specified length of
+      a string column should be fixed or varying (applies only for
+      string/binary column and might not be supported by all vendors).
+   -  comment - The comment of the column in the schema (might not
+      be supported by all vendors).
+   -  customSchemaOptions - Array of additional schema options
+      which are mostly vendor specific.
+-  column-definition - Optional alternative SQL representation for
+   this column. This definition begin after the field-name and has to
+   specify the complete column definition. Using this feature will
+   turn this field dirty for Schema-Tool update commands at all
+   times.
+
+.. note::
+
+    For more detailed information on each attribute, please refer to
+    the DBAL ``Schema-Representation`` documentation.
+
+Defining Identity and Generator Strategies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An entity has to have at least one ``<id />`` element. For
+composite keys you can specify more than one id-element, however
+surrogate keys are recommended for use with Doctrine 2. The Id
+field allows to define properties of the identifier and allows a
+subset of the ``<field />`` element attributes:
+
+.. code-block:: xml
+
+    <entity name="MyProject\User">
+        <id name="id" type="integer" column="user_id" />
+    </entity>
+
+Required attributes:
+
+
+-  name - The name of the Property/Field on the given Entity PHP
+   class.
+-  type - The ``Doctrine\DBAL\Types\Type`` name, preferably
+   "string" or "integer".
+
+Optional attributes:
+
+
+-  column - Name of the column in the database, defaults to the
+   field name.
+
+Using the simplified definition above Doctrine will use no
+identifier strategy for this entity. That means you have to
+manually set the identifier before calling
+``EntityManager#persist($entity)``. This is the so called
+``NONE`` strategy.
+
+If you want to switch the identifier generation strategy you have
+to nest a ``<generator />`` element inside the id-element. This of
+course only works for surrogate keys. For composite keys you always
+have to use the ``NONE`` strategy.
+
+.. code-block:: xml
+
+    <entity name="MyProject\User">
+        <id name="id" type="integer" column="user_id">
+            <generator strategy="AUTO" />
+        </id>
+    </entity>
+
+The following values are allowed for the ``<generator />`` strategy
+attribute:
+
+
+-  AUTO - Automatic detection of the identifier strategy based on
+   the preferred solution of the database vendor.
+-  IDENTITY - Use of a IDENTIFY strategy such as Auto-Increment IDs
+   available to Doctrine AFTER the INSERT statement has been executed.
+-  SEQUENCE - Use of a database sequence to retrieve the
+   entity-ids. This is possible before the INSERT statement is
+   executed.
+
+If you are using the SEQUENCE strategy you can define an additional
+element to describe the sequence:
+
+.. code-block:: xml
+
+    <entity name="MyProject\User">
+        <id name="id" type="integer" column="user_id">
+            <generator strategy="SEQUENCE" />
+            <sequence-generator sequence-name="user_seq" allocation-size="5" initial-value="1" />
+        </id>
+    </entity>
+
+Required attributes for ``<sequence-generator />``:
+
+
+-  sequence-name - The name of the sequence
+
+Optional attributes for ``<sequence-generator />``:
+
+
+-  allocation-size - By how much steps should the sequence be
+   incremented when a value is retrieved. Defaults to 1
+-  initial-value - What should the initial value of the sequence
+   be.
+
+    **NOTE**
+
+    If you want to implement a cross-vendor compatible application you
+    have to specify and additionally define the <sequence-generator />
+    element, if Doctrine chooses the sequence strategy for a
+    platform.
+
+
+Defining a Mapped Superclass
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes you want to define a class that multiple entities inherit
+from, which itself is not an entity however. The chapter on
+*Inheritance Mapping* describes a Mapped Superclass in detail. You
+can define it in XML using the ``<mapped-superclass />`` tag.
+
+.. code-block:: xml
+
+    <doctrine-mapping>
+        <mapped-superclass name="MyProject\BaseClass">
+            <field name="created" type="datetime" />
+            <field name="updated" type="datetime" />
+        </mapped-superclass>
+    </doctrine-mapping>
+
+Required attributes:
+
+
+-  name - Class name of the mapped superclass.
+
+You can nest any number of ``<field />`` and unidirectional
+``<many-to-one />`` or ``<one-to-one />`` associations inside a
+mapped superclass.
+
+Defining Inheritance Mappings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are currently two inheritance persistence strategies that you
+can choose from when defining entities that inherit from each
+other. Single Table inheritance saves the fields of the complete
+inheritance hierarchy in a single table, joined table inheritance
+creates a table for each entity combining the fields using join
+conditions.
+
+You can specify the inheritance type in the ``<entity />`` element
+and then use the ``<discriminator-column />`` and
+``<discriminator-mapping />`` attributes.
+
+.. code-block:: xml
+
+    <entity name="MyProject\Animal" inheritance-type="JOINED">
+        <discriminator-column name="discr" type="string" />
+        <discriminator-map>
+            <discriminator-mapping value="cat" class="MyProject\Cat" />
+            <discriminator-mapping value="dog" class="MyProject\Dog" />
+            <discriminator-mapping value="mouse" class="MyProject\Mouse" />
+        </discriminator-map>
+    </entity>
+
+The allowed values for inheritance-type attribute are ``JOINED`` or
+``SINGLE_TABLE``.
+
+.. note::
+
+    All inheritance related definitions have to be defined on the root
+    entity of the hierarchy.
+
+
+Defining Lifecycle Callbacks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can define the lifecycle callback methods on your entities
+using the ``<lifecycle-callbacks />`` element:
+
+.. code-block:: xml
+
+    <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
+
+        <lifecycle-callbacks>
+            <lifecycle-callback type="prePersist" method="onPrePersist" />
+        </lifecycle-callbacks>
+    </entity>
+
+Defining One-To-One Relations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can define One-To-One Relations/Associations using the
+``<one-to-one />`` element. The required and optional attributes
+depend on the associations being on the inverse or owning side.
+
+For the inverse side the mapping is as simple as:
+
+.. code-block:: xml
+
+    <entity class="MyProject\User">
+        <one-to-one field="address" target-entity="Address" mapped-by="user" />
+    </entity>
+
+Required attributes for inverse One-To-One:
+
+
+-  field - Name of the property/field on the entity's PHP class.
+-  target-entity - Name of the entity associated entity class. If
+   this is not qualified the namespace of the current class is
+   prepended. *IMPORTANT:* No leading backslash!
+-  mapped-by - Name of the field on the owning side (here Address
+   entity) that contains the owning side association.
+
+For the owning side this mapping would look like:
+
+.. code-block:: xml
+
+    <entity class="MyProject\Address">
+        <one-to-one field="user" target-entity="User" inversed-by="address" />
+    </entity>
+
+Required attributes for owning One-to-One:
+
+
+-  field - Name of the property/field on the entity's PHP class.
+-  target-entity - Name of the entity associated entity class. If
+   this is not qualified the namespace of the current class is
+   prepended. *IMPORTANT:* No leading backslash!
+
+Optional attributes for owning One-to-One:
+
+
+-  inversed-by - If the association is bidirectional the
+   inversed-by attribute has to be specified with the name of the
+   field on the inverse entity that contains the back-reference.
+-  orphan-removal - If true, the inverse side entity is always
+   deleted when the owning side entity is. Defaults to false.
+-  fetch - Either LAZY or EAGER, defaults to LAZY. This attribute
+   makes only sense on the owning side, the inverse side *ALWAYS* has
+   to use the ``FETCH`` strategy.
+
+The definition for the owning side relies on a bunch of mapping
+defaults for the join column names. Without the nested
+``<join-column />`` element Doctrine assumes to foreign key to be
+called ``user_id`` on the Address Entities table. This is because
+the ``MyProject\Address`` entity is the owning side of this
+association, which means it contains the foreign key.
+
+The completed explicitly defined mapping is:
+
+.. code-block:: xml
+
+    <entity class="MyProject\Address">
+        <one-to-one field="user" target-entity="User" inversed-by="address">
+            <join-column name="user_id" referenced-column-name="id" />
+        </one-to-one>
+    </entity>
+
+Defining Many-To-One Associations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The many-to-one association is *ALWAYS* the owning side of any
+bidirectional association. This simplifies the mapping compared to
+the one-to-one case. The minimal mapping for this association looks
+like:
+
+.. code-block:: xml
+
+    <entity class="MyProject\Article">
+        <many-to-one field="author" target-entity="User" />
+    </entity>
+
+Required attributes:
+
+
+-  field - Name of the property/field on the entity's PHP class.
+-  target-entity - Name of the entity associated entity class. If
+   this is not qualified the namespace of the current class is
+   prepended. *IMPORTANT:* No leading backslash!
+
+Optional attributes:
+
+
+-  inversed-by - If the association is bidirectional the
+   inversed-by attribute has to be specified with the name of the
+   field on the inverse entity that contains the back-reference.
+-  orphan-removal - If true the entity on the inverse side is
+   always deleted when the owning side entity is and it is not
+   connected to any other owning side entity anymore. Defaults to
+   false.
+-  fetch - Either LAZY or EAGER, defaults to LAZY.
+
+This definition relies on a bunch of mapping defaults with regards
+to the naming of the join-column/foreign key. The explicitly
+defined mapping includes a ``<join-column />`` tag nested inside
+the many-to-one association tag:
+
+.. code-block:: xml
+
+    <entity class="MyProject\Article">
+        <many-to-one field="author" target-entity="User">
+            <join-column name="author_id" referenced-column-name="id" />
+        </many-to-one>
+    </entity>
+
+The join-column attribute ``name`` specifies the column name of the
+foreign key and the ``referenced-column-name`` attribute specifies
+the name of the primary key column on the User entity.
+
+Defining One-To-Many Associations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The one-to-many association is *ALWAYS* the inverse side of any
+association. There exists no such thing as a uni-directional
+one-to-many association, which means this association only ever
+exists for bi-directional associations.
+
+.. code-block:: xml
+
+    <entity class="MyProject\User">
+        <one-to-many field="phonenumbers" target-entity="Phonenumber" mapped-by="user" />
+    </entity>
+
+Required attributes:
+
+
+-  field - Name of the property/field on the entity's PHP class.
+-  target-entity - Name of the entity associated entity class. If
+   this is not qualified the namespace of the current class is
+   prepended. *IMPORTANT:* No leading backslash!
+-  mapped-by - Name of the field on the owning side (here
+   Phonenumber entity) that contains the owning side association.
+
+Optional attributes:
+
+
+-  fetch - Either LAZY, EXTRA_LAZY or EAGER, defaults to LAZY.
+-  index-by: Index the collection by a field on the target entity.
+
+Defining Many-To-Many Associations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From all the associations the many-to-many has the most complex
+definition. When you rely on the mapping defaults you can omit many
+definitions and rely on their implicit values.
+
+.. code-block:: xml
+
+    <entity class="MyProject\User">
+        <many-to-many field="groups" target-entity="Group" />
+    </entity>
+
+Required attributes:
+
+
+-  field - Name of the property/field on the entity's PHP class.
+-  target-entity - Name of the entity associated entity class. If
+   this is not qualified the namespace of the current class is
+   prepended. *IMPORTANT:* No leading backslash!
+
+Optional attributes:
+
+
+-  mapped-by - Name of the field on the owning side that contains
+   the owning side association if the defined many-to-many association
+   is on the inverse side.
+-  inversed-by - If the association is bidirectional the
+   inversed-by attribute has to be specified with the name of the
+   field on the inverse entity that contains the back-reference.
+-  fetch - Either LAZY, EXTRA_LAZY or EAGER, defaults to LAZY.
+-  index-by: Index the collection by a field on the target entity.
+
+The mapping defaults would lead to a join-table with the name
+"User\_Group" being created that contains two columns "user\_id"
+and "group\_id". The explicit definition of this mapping would be:
+
+.. code-block:: xml
+
+    <entity class="MyProject\User">
+        <many-to-many field="groups" target-entity="Group">
+            <join-table name="cms_users_groups">
+                <join-columns>
+                    <join-column name="user_id" referenced-column-name="id"/>
+                </join-columns>
+                <inverse-join-columns>
+                    <join-column name="group_id" referenced-column-name="id"/>
+                </inverse-join-columns>
+            </join-table>
+        </many-to-many>
+    </entity>
+
+Here both the ``<join-columns>`` and ``<inverse-join-columns>``
+tags are necessary to tell Doctrine for which side the specified
+join-columns apply. These are nested inside a ``<join-table />``
+attribute which allows to specify the table name of the
+many-to-many join-table.
+
+Cascade Element
+~~~~~~~~~~~~~~~
+
+Doctrine allows cascading of several UnitOfWork operations to
+related entities. You can specify the cascade operations in the
+``<cascade />`` element inside any of the association mapping
+tags.
+
+.. code-block:: xml
+
+    <entity class="MyProject\User">
+        <many-to-many field="groups" target-entity="Group">
+            <cascade>
+                <cascade-all/>
+            </cascade>
+        </many-to-many>
+    </entity>
+
+Besides ``<cascade-all />`` the following operations can be
+specified by their respective tags:
+
+
+-  ``<cascade-persist />``
+-  ``<cascade-merge />``
+-  ``<cascade-remove />``
+-  ``<cascade-refresh />``
+
+Join Column Element
+~~~~~~~~~~~~~~~~~~~
+
+In any explicitly defined association mapping you will need the
+``<join-column />`` tag. It defines how the foreign key and primary
+key names are called that are used for joining two entities.
+
+Required attributes:
+
+
+-  name - The column name of the foreign key.
+-  referenced-column-name - The column name of the associated
+   entities primary key
+
+Optional attributes:
+
+
+-  unique - If the join column should contain a UNIQUE constraint.
+   This makes sense for Many-To-Many join-columns only to simulate a
+   one-to-many unidirectional using a join-table.
+-  nullable - should the join column be nullable, defaults to true.
+-  on-delete - Foreign Key Cascade action to perform when entity is
+   deleted, defaults to NO ACTION/RESTRICT but can be set to
+   "CASCADE".
+
+Defining Order of To-Many Associations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can require one-to-many or many-to-many associations to be
+retrieved using an additional ``ORDER BY``.
+
+.. code-block:: xml
+
+    <entity class="MyProject\User">
+        <many-to-many field="groups" target-entity="Group">
+            <order-by>
+                <order-by-field name="name" direction="ASC" />
+            </order-by>
+        </many-to-many>
+    </entity>
+
+Defining Indexes or Unique Constraints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To define additional indexes or unique constraints on the entities
+table you can use the ``<indexes />`` and
+``<unique-constraints />`` elements:
+
+.. code-block:: xml
+
+    <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
+
+        <indexes>
+            <index name="name_idx" columns="name"/>
+            <index columns="user_email"/>
+        </indexes>
+
+        <unique-constraints>
+            <unique-constraint columns="name,user_email" name="search_idx" />
+        </unique-constraints>
+    </entity>
+
+You have to specify the column and not the entity-class field names
+in the index and unique-constraint definitions.
+
+Derived Entities ID syntax
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the primary key of an entity contains a foreign key to another entity we speak of a derived
+entity relationship. You can define this in XML with the "association-key" attribute in the ``<id>`` tag.
+
+.. code-block:: xml
+
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
+         <entity name="Application\Model\ArticleAttribute">
+            <id name="article" association-key="true" />
+            <id name="attribute" type="string" />
+
+            <field name="value" type="string" />
+
+            <many-to-one field="article" target-entity="Article" inversed-by="attributes" />
+         </entity>
+
+    </doctrine-mapping>

vendor/doctrine/orm/docs/en/reference/yaml-mapping.rst

@@ -0,0 +1,158 @@
+YAML Mapping
+============
+
+.. note::
+    The YAML driver is deprecated and will be removed in version 3.0.
+    It is strongly recommended to switch to one of the other mappings.
+
+The YAML mapping driver enables you to provide the ORM metadata in
+form of YAML documents.
+
+The YAML mapping document of a class is loaded on-demand the first
+time it is requested and subsequently stored in the metadata cache.
+In order to work, this requires certain conventions:
+
+
+-  Each entity/mapped superclass must get its own dedicated YAML
+   mapping document.
+-  The name of the mapping document must consist of the fully
+   qualified name of the class, where namespace separators are
+   replaced by dots (.).
+-  All mapping documents should get the extension ".dcm.yml" to
+   identify it as a Doctrine mapping file. This is more of a
+   convention and you are not forced to do this. You can change the
+   file extension easily enough.
+
+.. code-block:: php
+
+    <?php
+    $driver->setFileExtension('.yml');
+
+It is recommended to put all YAML mapping documents in a single
+folder but you can spread the documents over several folders if you
+want to. In order to tell the YamlDriver where to look for your
+mapping documents, supply an array of paths as the first argument
+of the constructor, like this:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\Driver\YamlDriver;
+
+    // $config instanceof Doctrine\ORM\Configuration
+    $driver = new YamlDriver(array('/path/to/files'));
+    $config->setMetadataDriverImpl($driver);
+
+Simplified YAML Driver
+~~~~~~~~~~~~~~~~~~~~~~
+
+The Symfony project sponsored a driver that simplifies usage of the YAML Driver.
+The changes between the original driver are:
+
+- File Extension is .orm.yml
+- Filenames are shortened, "MyProject\\Entities\\User" will become User.orm.yml
+- You can add a global file and add multiple entities in this file.
+
+Configuration of this client works a little bit different:
+
+.. code-block:: php
+
+    <?php
+    $namespaces = array(
+        '/path/to/files1' => 'MyProject\Entities',
+        '/path/to/files2' => 'OtherProject\Entities'
+    );
+    $driver = new \Doctrine\ORM\Mapping\Driver\SimplifiedYamlDriver($namespaces);
+    $driver->setGlobalBasename('global'); // global.orm.yml
+
+Example
+-------
+
+As a quick start, here is a small example document that makes use
+of several common elements:
+
+.. code-block:: yaml
+
+    # Doctrine.Tests.ORM.Mapping.User.dcm.yml
+    Doctrine\Tests\ORM\Mapping\User:
+      type: entity
+      repositoryClass: Doctrine\Tests\ORM\Mapping\UserRepository
+      table: cms_users
+      schema: schema_name # The schema the table lies in, for platforms that support schemas (Optional, >= 2.5)
+      readOnly: true
+      indexes:
+        name_index:
+          columns: [ name ]
+      id:
+        id:
+          type: integer
+          generator:
+            strategy: AUTO
+      fields:
+        name:
+          type: string
+          length: 50
+        email:
+          type: string
+          length: 32
+          column: user_email
+          unique: true
+          options:
+            fixed: true
+            comment: User's email address
+        loginCount:
+          type: integer
+          column: login_count
+          nullable: false
+          options:
+            unsigned: true
+            default: 0
+      oneToOne:
+        address:
+          targetEntity: Address
+          joinColumn:
+            name: address_id
+            referencedColumnName: id
+            onDelete: CASCADE
+      oneToMany:
+        phonenumbers:
+          targetEntity: Phonenumber
+          mappedBy: user
+          cascade: ["persist", "merge"]
+      manyToMany:
+        groups:
+          targetEntity: Group
+          joinTable:
+            name: cms_users_groups
+            joinColumns:
+              user_id:
+                referencedColumnName: id
+            inverseJoinColumns:
+              group_id:
+                referencedColumnName: id
+      lifecycleCallbacks:
+        prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersistToo ]
+        postPersist: [ doStuffOnPostPersist ]
+
+Be aware that class-names specified in the YAML files should be
+fully qualified.
+
+Reference
+~~~~~~~~~~~~~~~~~~~~~~
+
+Unique Constraints
+------------------
+
+It is possible to define unique constraints by the following declaration:
+
+.. code-block:: yaml
+
+    # ECommerceProduct.orm.yml
+    ECommerceProduct:
+      type: entity
+      fields:
+        # definition of some fields
+      uniqueConstraints:
+        search_idx:
+          columns: [ name, email ]
+