Remove trailing whitespaces (#8360)

Stylistically, it's not great to have them, but more importantly, the
latest symfony/yaml version has issues with trailing whitespaces.

.doctrine-project.json

@@ -0,0 +1,49 @@
+{
+    "active": true,
+    "name": "Object Relational Mapper",
+    "shortName": "ORM",
+    "slug": "orm",
+    "docsSlug": "doctrine-orm",
+    "versions": [
+        {
+            "name": "3.0",
+            "branchName": "master",
+            "slug": "latest",
+            "upcoming": true
+        },
+        {
+            "name": "2.8",
+            "branchName": "2.8.x",
+            "slug": "2.8",
+            "upcoming": true
+        },
+        {
+            "name": "2.7",
+            "branchName": "2.7",
+            "slug": "2.7",
+            "current": true,
+            "aliases": [
+                "current",
+                "stable"
+            ]
+        },
+        {
+            "name": "2.6",
+            "branchName": "2.6",
+            "slug": "2.6",
+            "maintained": false
+        },
+        {
+            "name": "2.5",
+            "branchName": "2.5",
+            "slug": "2.5",
+            "maintained": false
+        },
+        {
+            "name": "2.4",
+            "branchName": "2.4",
+            "slug": "2.4",
+            "maintained": false
+        }
+    ]
+}

.gitattributes

@@ -1,5 +1,6 @@
 /tests export-ignore
 /tools export-ignore
+/.github export-ignore
 .gitattributes export-ignore
 .gitignore export-ignore
 .gitmodules export-ignore
@@ -11,3 +12,6 @@ CONTRIBUTING.md export-ignore
 phpunit.xml.dist export-ignore
 run-all.sh export-ignore
 phpcs.xml.dist export-ignore
+phpbench.json export-ignore
+phpstan.neon export-ignore
+psalm.xml export-ignore

.github/workflows/coding-standard.yml

@@ -0,0 +1,46 @@
+name: Static Analysis
+
+on:
+  pull_request:
+
+jobs:
+  coding-standards:
+    name: "Coding Standards"
+    runs-on: "ubuntu-latest"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.4"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+        with:
+          fetch-depth: 10
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "${{ matrix.php-version }}"
+          tools: "cs2pr"
+
+      - name: "Cache dependencies installed with composer"
+        uses: "actions/cache@v1"
+        with:
+          path: "~/.composer/cache"
+          key: "php-${{ matrix.php-version }}-composer-locked-${{ hashFiles('composer.lock') }}"
+          restore-keys: "php-${{ matrix.php-version }}-composer-locked-"
+
+      - name: "Install dependencies with composer"
+        run: "composer update --no-interaction --no-progress --no-suggest"
+
+      - name: "Install git-phpcs"
+        run: "wget https://github.com/diff-sniffer/git/releases/download/0.3.2/git-phpcs.phar"
+
+      - name: "Fetch head branch"
+        run: "git remote set-branches --add origin $GITHUB_BASE_REF && git fetch origin $GITHUB_BASE_REF"
+
+      - name: "Run git-phpcs"
+        run: "php git-phpcs.phar origin/$GITHUB_BASE_REF...$GITHUB_SHA --report=checkstyle | cs2pr"

.github/workflows/continuous-integration.yml

@@ -0,0 +1,284 @@
+name: "Continuous Integration"
+
+on:
+  pull_request:
+  push:
+
+env:
+  fail-fast: true
+
+jobs:
+  phpunit-smoke-check:
+    name: "PHPUnit with SQLite"
+    runs-on: "ubuntu-20.04"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.2"
+          - "7.3"
+          - "7.4"
+        deps:
+          - "normal"
+        include:
+          - deps: "low"
+            php-version: "7.3"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+        with:
+          fetch-depth: 2
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "${{ matrix.php-version }}"
+          extensions: "pdo, pdo_sqlite"
+          coverage: "pcov"
+          ini-values: "zend.assertions=1"
+
+      - name: "Cache dependencies installed with composer"
+        uses: "actions/cache@v2"
+        with:
+          path: "~/.composer/cache"
+          key: "php-${{ matrix.php-version }}-composer-locked-${{ hashFiles('composer.lock') }}"
+          restore-keys: "php-${{ matrix.php-version }}-composer-locked-"
+
+      - name: "Install dependencies with composer"
+        run: "composer update --no-interaction --no-progress --no-suggest"
+        if: "${{ matrix.deps == 'normal' }}"
+
+      - name: "Install lowest possible dependencies with composer"
+        run: "composer update --no-interaction --no-progress --no-suggest --prefer-dist --prefer-lowest"
+        if: "${{ matrix.deps == 'low' }}"
+
+      - name: "Run PHPUnit"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/sqlite.xml --coverage-clover=coverage-no-cache.xml"
+        env:
+            ENABLE_SECOND_LEVEL_CACHE: 0
+
+      - name: "Run PHPUnit with Second Level Cache"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/sqlite.xml --exclude-group performance,non-cacheable,locking_functional --coverage-clover=coverage-cache.xml"
+        env:
+            ENABLE_SECOND_LEVEL_CACHE: 1
+
+      - name: "Upload coverage file"
+        uses: "actions/upload-artifact@v2"
+        with:
+          name: "phpunit-sqlite-${{ matrix.deps }}-${{ matrix.php-version }}-coverage"
+          path: "coverage*.xml"
+
+
+  phpunit-postgres:
+    name: "PHPUnit with PostgreSQL"
+    runs-on: "ubuntu-20.04"
+    needs: "phpunit-smoke-check"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.4"
+        postgres-version:
+          - "9.6"
+          - "13"
+
+    services:
+      postgres:
+        image: "postgres:${{ matrix.postgres-version }}"
+        env:
+          POSTGRES_PASSWORD: "postgres"
+
+        options: >-
+          --health-cmd "pg_isready"
+
+        ports:
+          - "5432:5432"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+        with:
+          fetch-depth: 2
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "${{ matrix.php-version }}"
+          coverage: "pcov"
+          ini-values: "zend.assertions=1"
+
+      - name: "Cache dependencies installed with composer"
+        uses: "actions/cache@v2"
+        with:
+          path: "~/.composer/cache"
+          key: "php-${{ matrix.php-version }}-composer-locked-${{ hashFiles('composer.lock') }}"
+          restore-keys: "php-${{ matrix.php-version }}-composer-locked-"
+
+      - name: "Install dependencies with composer"
+        run: "composer update --no-interaction --no-progress --no-suggest"
+
+      - name: "Run PHPUnit"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/pdo_pgsql.xml --coverage-clover=coverage.xml"
+
+      - name: "Upload coverage file"
+        uses: "actions/upload-artifact@v2"
+        with:
+          name: "${{ github.job }}-${{ matrix.postgres-version }}-${{ matrix.php-version }}-coverage"
+          path: "coverage.xml"
+
+
+  phpunit-mariadb:
+    name: "PHPUnit with MariaDB"
+    runs-on: "ubuntu-20.04"
+    needs: "phpunit-smoke-check"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.4"
+        mariadb-version:
+          - "10.5"
+        extension:
+          - "mysqli"
+          - "pdo_mysql"
+
+    services:
+      mariadb:
+        image: "mariadb:${{ matrix.mariadb-version }}"
+        env:
+          MYSQL_ALLOW_EMPTY_PASSWORD: yes
+          MYSQL_DATABASE: "doctrine_tests"
+
+        options: >-
+          --health-cmd "mysqladmin ping --silent"
+
+        ports:
+          - "3306:3306"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+        with:
+          fetch-depth: 2
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "${{ matrix.php-version }}"
+          coverage: "pcov"
+          ini-values: "zend.assertions=1"
+          extensions: "${{ matrix.extension }}"
+
+      - name: "Cache dependencies installed with composer"
+        uses: "actions/cache@v2"
+        with:
+          path: "~/.composer/cache"
+          key: "php-${{ matrix.php-version }}-composer-locked-${{ hashFiles('composer.lock') }}"
+          restore-keys: "php-${{ matrix.php-version }}-composer-locked-"
+
+      - name: "Install dependencies with composer"
+        run: "composer update --no-interaction --no-progress --no-suggest"
+
+      - name: "Run PHPUnit"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage.xml"
+
+      - name: "Upload coverage file"
+        uses: "actions/upload-artifact@v2"
+        with:
+          name: "${{ github.job }}-${{ matrix.mariadb-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-coverage"
+          path: "coverage.xml"
+
+
+  phpunit-mysql:
+    name: "PHPUnit with MySQL"
+    runs-on: "ubuntu-20.04"
+    needs: "phpunit-smoke-check"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.4"
+        mysql-version:
+          - "5.7"
+          - "8.0"
+        extension:
+          - "mysqli"
+          - "pdo_mysql"
+
+    services:
+      mysql:
+        image: "mysql:${{ matrix.mysql-version }}"
+
+        options: >-
+          --health-cmd "mysqladmin ping --silent"
+          -e MYSQL_ALLOW_EMPTY_PASSWORD=yes
+          -e MYSQL_DATABASE=doctrine_tests
+
+        ports:
+          - "3306:3306"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+        with:
+          fetch-depth: 2
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "${{ matrix.php-version }}"
+          coverage: "pcov"
+          ini-values: "zend.assertions=1"
+          extensions: "${{ matrix.extension }}"
+
+      - name: "Cache dependencies installed with composer"
+        uses: "actions/cache@v2"
+        with:
+          path: "~/.composer/cache"
+          key: "php-${{ matrix.php-version }}-composer-locked-${{ hashFiles('composer.lock') }}"
+          restore-keys: "php-${{ matrix.php-version }}-composer-locked-"
+
+      - name: "Install dependencies with composer"
+        run: "composer update --no-interaction --no-progress --no-suggest"
+
+      - name: "Run PHPUnit"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage-no-cache.xml"
+        env:
+            ENABLE_SECOND_LEVEL_CACHE: 0
+
+      - name: "Run PHPUnit with Second Level Cache"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --exclude-group performance,non-cacheable,locking_functional --coverage-clover=coverage-no-cache.xml"
+        env:
+            ENABLE_SECOND_LEVEL_CACHE: 1
+
+      - name: "Upload coverage files"
+        uses: "actions/upload-artifact@v2"
+        with:
+          name: "${{ github.job }}-${{ matrix.mysql-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-coverage"
+          path: "coverage*.xml"
+
+  upload_coverage:
+    name: "Upload coverage to Codecov"
+    runs-on: "ubuntu-20.04"
+    needs:
+      - "phpunit-smoke-check"
+      - "phpunit-postgres"
+      - "phpunit-mariadb"
+      - "phpunit-mysql"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+        with:
+          fetch-depth: 2
+
+      - name: "Download coverage files"
+        uses: "actions/download-artifact@v2"
+        with:
+          path: "reports"
+
+      - name: "Upload to Codecov"
+        uses: "codecov/codecov-action@v1"
+        with:
+          directory: reports

.github/workflows/release-on-milestone-closed.yml

@@ -0,0 +1,56 @@
+name: "Automatic Releases"
+
+on:
+  milestone:
+    types:
+      - "closed"
+
+jobs:
+  release:
+    name: "Git tag, release & create merge-up PR"
+    runs-on: "ubuntu-20.04"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+
+      - name: "Release"
+        uses: "laminas/automatic-releases@v1"
+        with:
+          command-name: "laminas:automatic-releases:release"
+        env:
+          "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }}
+          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
+          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
+          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}
+          "SHELL_VERBOSITY": "3"
+
+      - name: "Create Merge-Up Pull Request"
+        uses: "laminas/automatic-releases@v1"
+        with:
+          command-name: "laminas:automatic-releases:create-merge-up-pull-request"
+        env:
+          "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }}
+          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
+          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
+          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}
+
+      - name: "Create and/or Switch to new Release Branch"
+        uses: "laminas/automatic-releases@v1"
+        with:
+          command-name: "laminas:automatic-releases:switch-default-branch-to-next-minor"
+        env:
+          "GITHUB_TOKEN": ${{ secrets.ORGANIZATION_ADMIN_TOKEN }}
+          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
+          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
+          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}
+
+      - name: "Create new milestones"
+        uses: "laminas/automatic-releases@v1"
+        with:
+          command-name: "laminas:automatic-releases:create-milestones"
+        env:
+          "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }}
+          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
+          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
+          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}

.github/workflows/static-analysis.yml

@@ -0,0 +1,70 @@
+name: Static Analysis
+
+on:
+  pull_request:
+
+jobs:
+  static-analysis-phpstan:
+    name: "PHPStan"
+    runs-on: "ubuntu-latest"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.4"
+
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v2"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "${{ matrix.php-version }}"
+          tools: cs2pr
+
+      - name: "Cache dependencies installed with composer"
+        uses: "actions/cache@v1"
+        with:
+          path: "~/.composer/cache"
+          key: "php-${{ matrix.php-version }}-composer-locked-${{ hashFiles('composer.lock') }}"
+          restore-keys: "php-${{ matrix.php-version }}-composer-locked-"
+
+      - name: "Install dependencies with composer"
+        run: "composer update --no-progress --no-suggest --no-interaction --prefer-dist"
+
+      - name: "Run a static analysis with phpstan/phpstan"
+        run: "php vendor/bin/phpstan analyse --error-format=checkstyle | cs2pr"
+
+  static-analysis-psalm:
+    name: "Psalm"
+    runs-on: "ubuntu-latest"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.4"
+
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v2"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "${{ matrix.php-version }}"
+
+      - name: "Cache dependencies installed with composer"
+        uses: "actions/cache@v1"
+        with:
+          path: "~/.composer/cache"
+          key: "php-${{ matrix.php-version }}-composer-locked-${{ hashFiles('composer.lock') }}"
+          restore-keys: "php-${{ matrix.php-version }}-composer-locked-"
+
+      - name: "Install dependencies with composer"
+        run: "composer update --no-interaction --no-progress --no-suggest"
+
+      - name: "Run a static analysis with vimeo/psalm"
+        run: "vendor/bin/psalm --show-info=false --stats --output-format=github --threads=$(nproc)"

.gitignore

@@ -12,6 +12,7 @@ lib/Doctrine/DBAL
 .idea
 *.iml
 vendor/
-composer.lock
 /tests/Doctrine/Performance/history.db
 /.phpcs-cache
+composer.lock
+/.phpunit.result.cache

.scrutinizer.yml

@@ -1,34 +0,0 @@
-build:
-    nodes:
-        analysis:
-            environment:
-                php:
-                    version: 7.1
-            cache:
-                disabled: false
-                directories:
-                    - ~/.composer/cache
-
-            project_setup:
-                override: true
-            tests:
-                override:
-                    - php-scrutinizer-run
-
-before_commands:
-    - "composer install --no-dev --prefer-source"
-
-tools:
-    external_code_coverage:
-        timeout: 3600
-
-filter:
-    excluded_paths:
-        - docs
-        - tools
-
-build_failure_conditions:
-    - 'elements.rating(<= C).new.exists'                        # No new classes/methods with a rating of C or worse allowed
-    - 'issues.severity(>= MAJOR).new.exists'                    # New issues of major or higher severity
-    - 'project.metric_change("scrutinizer.test_coverage", < 0)' # Code Coverage decreased from previous inspection
-    - 'patches.label("Unused Use Statements").new.exists'       # No new unused imports patches allowed

.travis.yml

@@ -1,101 +0,0 @@
-dist: trusty
-sudo: false
-language: php
-
-php:
-  - 7.1
-  - 7.2
-  - nightly
-
-env:
-  - DB=sqlite
-  - DB=mysql
-  - DB=pgsql
-
-before_install:
-  - mv ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/xdebug.ini{,.disabled} || echo "xdebug not available"
-  - composer self-update
-
-install: travis_retry composer update --prefer-dist
-
-script:
-  - if [[ "$DB" == "mysql" || "$DB" == "mariadb" ]]; then mysql -e "CREATE SCHEMA doctrine_tests; GRANT ALL PRIVILEGES ON doctrine_tests.* to travis@'%'"; fi
-  - ENABLE_SECOND_LEVEL_CACHE=0 ./vendor/bin/phpunit -v -c tests/travis/$DB.travis.xml
-  - ENABLE_SECOND_LEVEL_CACHE=1 ./vendor/bin/phpunit -v -c tests/travis/$DB.travis.xml --exclude-group performance,non-cacheable,locking_functional
-
-jobs:
-  include:
-    - stage: Test
-      env: DB=mariadb
-      addons:
-        mariadb: 10.1
-
-    - stage: Test
-      env: DB=mysql MYSQL_VERSION=5.7
-      php: 7.1
-      before_script:
-        - ./tests/travis/install-mysql-$MYSQL_VERSION.sh
-      sudo: required
-
-    - stage: Test
-      env: DB=mysql MYSQL_VERSION=5.7
-      php: 7.2
-      before_script:
-        - ./tests/travis/install-mysql-$MYSQL_VERSION.sh
-      sudo: required
-
-    - stage: Test
-      env: DB=mysql MYSQL_VERSION=5.7
-      php: nightly
-      before_script:
-        - ./tests/travis/install-mysql-$MYSQL_VERSION.sh
-      sudo: required
-
-    - stage: Test
-      env: DB=sqlite DEPENDENCIES=low
-      install: travis_retry composer update --prefer-dist --prefer-lowest
-
-    - stage: Test
-      if: type = cron
-      env: DB=sqlite DEV_DEPENDENCIES
-      install:
-        - composer config minimum-stability dev
-        - travis_retry composer update --prefer-dist
-
-    - stage: Test
-      env: DB=sqlite COVERAGE
-      before_script:
-        - mv ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/xdebug.ini{.disabled,}
-        - if [[ ! $(php -m | grep -si xdebug) ]]; then echo "xdebug required for coverage"; exit 1; fi
-      script:
-        - ENABLE_SECOND_LEVEL_CACHE=0 ./vendor/bin/phpunit -v -c tests/travis/$DB.travis.xml --coverage-clover ./build/logs/clover.xml
-      after_script:
-        - wget https://scrutinizer-ci.com/ocular.phar
-        - php ocular.phar code-coverage:upload --format=php-clover build/logs/clover.xml
-
-    - stage: Code Quality
-      env: DB=none STATIC_ANALYSIS
-      install: travis_retry composer update --prefer-dist --prefer-stable
-      before_script:
-        - echo "extension=memcached.so" >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini
-        - echo "extension=redis.so" >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini
-        - travis_retry composer require --dev --prefer-dist --prefer-stable phpstan/phpstan:^0.9
-      script: vendor/bin/phpstan analyse -l 1 -c phpstan.neon lib
-
-    - stage: Code Quality
-      env: DB=none BENCHMARK
-      before_script: wget https://phpbench.github.io/phpbench/phpbench.phar https://phpbench.github.io/phpbench/phpbench.phar.pubkey
-      script: php phpbench.phar run -l dots --report=default
-
-    - stage: Code Quality
-      env: DB=none CODING_STANDARDS
-      php: nightly
-      script:
-        - ./vendor/bin/phpcs
-
-  allow_failures:
-    - php: nightly
-
-cache:
-  directories:
-    - $HOME/.composer/cache

CONTRIBUTING.md

@@ -44,12 +44,12 @@ Please try to add a test for your pull-request.
 You can run the unit-tests by calling ``vendor/bin/phpunit`` from the root of the project.
 It will run all the tests with an in memory SQLite database.
 
-In order to do that, you will need a fresh copy of doctrine2, and you
+In order to do that, you will need a fresh copy of the ORM, and you
 will have to run a composer installation in the project:
 
 ```sh
-git clone git@github.com:doctrine/doctrine2.git
-cd doctrine2
+git clone git@github.com:doctrine/orm.git
+cd orm
 curl -sS https://getcomposer.org/installer | php --
 ./composer.phar install
 ```
@@ -66,7 +66,7 @@ sqlite database.
 Tips for creating unit tests:
 
 1. If you put a test into the `Ticket` namespace as described above, put the testcase and all entities into the same class.
-   See `https://github.com/doctrine/doctrine2/tree/master/tests/Doctrine/Tests/ORM/Functional/Ticket/DDC2306Test.php` for an
+   See `https://github.com/doctrine/orm/tree/master/tests/Doctrine/Tests/ORM/Functional/Ticket/DDC2306Test.php` for an
    example.
 
 ## Travis

README.md

@@ -1,7 +1,7 @@
-| [Master][Master] | [2.5][2.5] |
+| [Master][Master] | [2.7][2.7] |
 |:----------------:|:----------:|
-| [![Build status][Master image]][Master] | [![Build status][2.5 image]][2.5] |
-| [![Coverage Status][Master coverage image]][Master coverage] | [![Coverage Status][2.5 coverage image]][2.5 coverage] |
+| [![Build status][Master image]][Master] | [![Build status][2.7 image]][2.7] |
+| [![Coverage Status][Master coverage image]][Master coverage] | [![Coverage Status][2.7 coverage image]][2.7 coverage] |
 
 Doctrine 2 is an object-relational mapper (ORM) for PHP 7.1+ that provides transparent persistence
 for PHP objects. It sits on top of a powerful database abstraction layer (DBAL). One of its key features
@@ -16,11 +16,11 @@ without requiring unnecessary code duplication.
 * [Documentation](http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/index.html)
 
 
-  [Master image]: https://img.shields.io/travis/doctrine/doctrine2/master.svg?style=flat-square
-  [Master]: https://travis-ci.org/doctrine/doctrine2
-  [Master coverage image]: https://img.shields.io/scrutinizer/coverage/g/doctrine/doctrine2/master.svg?style=flat-square
-  [Master coverage]: https://scrutinizer-ci.com/g/doctrine/doctrine2/?branch=master
-  [2.5 image]: https://img.shields.io/travis/doctrine/doctrine2/2.5.svg?style=flat-square
-  [2.5]: https://github.com/doctrine/doctrine2/tree/2.5
-  [2.5 coverage image]: https://img.shields.io/scrutinizer/coverage/g/doctrine/doctrine2/2.5.svg?style=flat-square
-  [2.5 coverage]: https://scrutinizer-ci.com/g/doctrine/doctrine2/?branch=2.5
+  [Master image]: https://img.shields.io/travis/doctrine/orm/master.svg?style=flat-square
+  [Master]: https://travis-ci.org/doctrine/orm
+  [Master coverage image]: https://codecov.io/gh/doctrine/orm/branch/master/graph/badge.svg
+  [Master coverage]: https://codecov.io/gh/doctrine/orm/branch/master
+  [2.7 image]: https://img.shields.io/travis/doctrine/orm/2.7.svg?style=flat-square
+  [2.7]: https://github.com/doctrine/orm/tree/2.7
+  [2.7 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.7/graph/badge.svg
+  [2.7 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.7

SECURITY.md

@@ -11,7 +11,7 @@ Please read the documentation chapter on Security in Doctrine DBAL and ORM to
 understand the assumptions we make.
 
 - [DBAL Security Page](https://github.com/doctrine/dbal/blob/master/docs/en/reference/security.rst)
-- [ORM Security Page](https://github.com/doctrine/doctrine2/blob/master/docs/en/reference/security.rst)
+- [ORM Security Page](https://github.com/doctrine/orm/blob/master/docs/en/reference/security.rst)
 
 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

UPGRADE.md

@@ -1,5 +1,154 @@
+# Upgrade to 2.7
+
+## Added `Doctrine\ORM\AbstractQuery#enableResultCache()` and `Doctrine\ORM\AbstractQuery#disableResultCache()` methods	
+
+Method `Doctrine\ORM\AbstractQuery#useResultCache()` which could be used for both enabling and disabling the cache
+(depending on passed flag) was split into two.	
+
+## Minor BC BREAK: paginator output walkers aren't be called anymore on sub-queries for queries without max results  
+
+To optimize DB interaction, `Doctrine\ORM\Tools\Pagination\Paginator` no longer fetches identifiers to be able to
+perform the pagination with join collections when max results isn't set in the query.
+
+## Minor BC BREAK: tables filtered with `schema_filter` are no longer created
+
+When generating schema diffs, if a source table is filtered out by a `schema_filter` expression, then a `CREATE TABLE` was
+always generated, even if the table already existed. This has been changed in this release and the table will no longer
+be created.
+
+## Deprecated number unaware `Doctrine\ORM\Mapping\UnderscoreNamingStrategy`
+
+In the last patch of the `v2.6.x` series, we fixed a bug that was not converting names properly when they had numbers
+(e.g.: `base64Encoded` was wrongly converted to `base64encoded` instead of `base64_encoded`).
+
+In order to not break BC we've introduced a way to enable the fixed behavior using a boolean constructor argument. This
+argument will be removed in 3.0 and the default behavior will be the fixed one.
+
+## Deprecated: `Doctrine\ORM\AbstractQuery#useResultCache()`	
+
+Method `Doctrine\ORM\AbstractQuery#useResultCache()` is deprecated because it is split into `enableResultCache()`
+and `disableResultCache()`. It will be removed in 3.0.
+
+## Deprecated code generators and related console commands
+ 
+These console commands have been deprecated:
+
+ * `orm:convert-mapping`
+ * `orm:generate:entities`
+ * `orm:generate-repositories`
+
+These classes have been deprecated:
+
+ * `Doctrine\ORM\Tools\EntityGenerator`
+ * `Doctrine\ORM\Tools\EntityRepositoryGenerator`
+
+Whole Doctrine\ORM\Tools\Export namespace with all its members have been deprecated as well.
+
+## Deprecated `Doctrine\ORM\Proxy\Proxy` marker interface
+
+Proxy objects in Doctrine ORM 3.0 will no longer implement `Doctrine\ORM\Proxy\Proxy` nor
+`Doctrine\Persistence\Proxy`: instead, they implement
+`ProxyManager\Proxy\GhostObjectInterface`.
+
+These related classes have been deprecated:
+
+ * `Doctrine\ORM\Proxy\ProxyFactory`
+ * `Doctrine\ORM\Proxy\Autoloader` - we suggest using the composer autoloader instead
+ 
+These methods have been deprecated:
+
+ * `Doctrine\ORM\Configuration#getAutoGenerateProxyClasses()`
+ * `Doctrine\ORM\Configuration#getProxyDir()`
+ * `Doctrine\ORM\Configuration#getProxyNamespace()`
+
+## Deprecated `Doctrine\ORM\Version`
+
+The `Doctrine\ORM\Version` class is now deprecated and will be removed in Doctrine ORM 3.0:
+please refrain from checking the ORM version at runtime or use
+[ocramius/package-versions](https://github.com/Ocramius/PackageVersions/).
+
+## Deprecated `EntityManager#merge()` and `EntityManager#detach()` methods
+
+Merge and detach semantics were a poor fit for the PHP "share-nothing" architecture.
+In addition to that, merging/detaching caused multiple issues with data integrity
+in the managed entity graph, which was constantly spawning more edge-case bugs/scenarios.
+
+The following API methods were therefore deprecated:
+
+* `EntityManager#merge()`
+* `EntityManager#detach()`
+* `UnitOfWork#merge()`
+* `UnitOfWork#detach()`
+
+Users are encouraged to migrate `EntityManager#detach()` calls to `EntityManager#clear()`.
+
+In order to maintain performance on batch processing jobs, it is endorsed to enable
+the second level cache (http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/second-level-cache.html)
+on entities that are frequently reused across multiple `EntityManager#clear()` calls.
+
+An alternative to `EntityManager#merge()` will not be provided by ORM 3.0, since the merging
+semantics should be part of the business domain rather than the persistence domain of an
+application. If your application relies heavily on CRUD-alike interactions and/or `PATCH`
+restful operations, you should look at alternatives such as [JMSSerializer](https://github.com/schmittjoh/serializer).
+
+## Extending `EntityManager` is deprecated
+
+Final keyword will be added to the `EntityManager::class` in Doctrine ORM 3.0 in order to ensure that EntityManager
+ is not used as valid extension point. Valid extension point should be EntityManagerInterface.
+
+## Deprecated `EntityManager#clear($entityName)`
+
+If your code relies on clearing a single entity type via `EntityManager#clear($entityName)`,
+the signature has been changed to `EntityManager#clear()`.
+
+The main reason is that partial clears caused multiple issues with data integrity
+in the managed entity graph, which was constantly spawning more edge-case bugs/scenarios.
+
+## Deprecated `EntityManager#flush($entity)` and `EntityManager#flush($entities)`
+
+If your code relies on single entity flushing optimisations via
+`EntityManager#flush($entity)`, the signature has been changed to
+`EntityManager#flush()`.
+
+Said API was affected by multiple data integrity bugs due to the fact
+that change tracking was being restricted upon a subset of the managed
+entities. The ORM cannot support committing subsets of the managed 
+entities while also guaranteeing data integrity, therefore this
+utility was removed.
+
+The `flush()` semantics will remain the same, but the change tracking will be performed
+on all entities managed by the unit of work, and not just on the provided
+`$entity` or `$entities`, as the parameter is now completely ignored.
+
+The same applies to `UnitOfWork#commit($entity)`, which will simply be
+`UnitOfWork#commit()`.
+
+If you would still like to perform batching operations over small `UnitOfWork`
+instances, it is suggested to follow these paths instead:
+
+ * eagerly use `EntityManager#clear()` in conjunction with a specific second level
+   cache configuration (see http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/second-level-cache.html)
+ * use an explicit change tracking policy (see http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/change-tracking-policies.html)
+
+## Deprecated `YAML` mapping drivers.
+
+If your code relies on `YamlDriver`  or `SimpleYamlDriver`, you **MUST** change to
+annotation or XML drivers instead.
+
+## Deprecated: `Doctrine\ORM\EntityManagerInterface#copy()`
+
+Method `Doctrine\ORM\EntityManagerInterface#copy()` never got its implementation and is deprecated.
+It will be removed in 3.0.
+
 # Upgrade to 2.6
 
+## Added `Doctrine\ORM\EntityRepository::count()` method
+
+`Doctrine\ORM\EntityRepository::count()` has been added. This new method has different
+signature than `Countable::count()` (required parameter) and therefore are not compatible.
+If your repository implemented the `Countable` interface, you will have to use
+`$repository->count([])` instead and not implement `Countable` interface anymore.
+
 ## Minor BC BREAK: `Doctrine\ORM\Tools\Console\ConsoleRunner` is now final
 
 Since it's just an utilitarian class and should not be inherited.
@@ -13,13 +162,13 @@ now has a required parameter `$pathExpr`.
 
 Method `Doctrine\ORM\Query\Parser#isInternalFunction()` was removed because
 the distinction between internal function and user defined DQL was removed.
-[#6500](https://github.com/doctrine/doctrine2/pull/6500)
+[#6500](https://github.com/doctrine/orm/pull/6500)
 
 ## Minor BC BREAK: removed `Doctrine\ORM\ORMException#overwriteInternalDQLFunctionNotAllowed()`
 
 Method `Doctrine\ORM\Query\Parser#overwriteInternalDQLFunctionNotAllowed()` was
 removed because of the choice to allow users to overwrite internal functions, ie
-`AVG`, `SUM`, `COUNT`, `MIN` and `MAX`. [#6500](https://github.com/doctrine/doctrine2/pull/6500)
+`AVG`, `SUM`, `COUNT`, `MIN` and `MAX`. [#6500](https://github.com/doctrine/orm/pull/6500)
 
 ## PHP 7.1 is now required
 
@@ -35,7 +184,7 @@ As a consequence, automatic cache setup in Doctrine\ORM\Tools\Setup::create*Conf
 ## Minor BC BREAK: removed `Doctrine\ORM\Query\SqlWalker#walkCaseExpression()`
 
 Method `Doctrine\ORM\Query\SqlWalker#walkCaseExpression()` was unused and part
-of the internal API of the ORM, so it was removed. [#5600](https://github.com/doctrine/doctrine2/pull/5600).
+of the internal API of the ORM, so it was removed. [#5600](https://github.com/doctrine/orm/pull/5600).
 
 ## Minor BC BREAK: removed $className parameter on `AbstractEntityInheritancePersister#getSelectJoinColumnSQL()`
 
@@ -290,17 +439,17 @@ above you must implement these new methods.
 
 ## Metadata Drivers
 
-Metadata drivers have been rewritten to reuse code from Doctrine\Common. Anyone who is using the
+Metadata drivers have been rewritten to reuse code from `Doctrine\Persistence`. Anyone who is using the
 `Doctrine\ORM\Mapping\Driver\Driver` interface should instead refer to
-`Doctrine\Common\Persistence\Mapping\Driver\MappingDriver`. Same applies to
+`Doctrine\Persistence\Mapping\Driver\MappingDriver`. Same applies to
 `Doctrine\ORM\Mapping\Driver\AbstractFileDriver`: you should now refer to
-`Doctrine\Common\Persistence\Mapping\Driver\FileDriver`.
+`Doctrine\Persistence\Mapping\Driver\FileDriver`.
 
 Also, following mapping drivers have been deprecated, please use their replacements in Doctrine\Common as listed:
 
- *  `Doctrine\ORM\Mapping\Driver\DriverChain`       => `Doctrine\Common\Persistence\Mapping\Driver\MappingDriverChain`
- *  `Doctrine\ORM\Mapping\Driver\PHPDriver`         => `Doctrine\Common\Persistence\Mapping\Driver\PHPDriver`
- *  `Doctrine\ORM\Mapping\Driver\StaticPHPDriver`   => `Doctrine\Common\Persistence\Mapping\Driver\StaticPHPDriver`
+ *  `Doctrine\ORM\Mapping\Driver\DriverChain`       => `Doctrine\Persistence\Mapping\Driver\MappingDriverChain`
+ *  `Doctrine\ORM\Mapping\Driver\PHPDriver`         => `Doctrine\Persistence\Mapping\Driver\PHPDriver`
+ *  `Doctrine\ORM\Mapping\Driver\StaticPHPDriver`   => `Doctrine\Persistence\Mapping\Driver\StaticPHPDriver`
 
 # Upgrade to 2.2
 
@@ -389,7 +538,7 @@ Previously EntityManager#find(null) returned null. It now throws an exception.
 
 ## Interface for EntityRepository
 
-The EntityRepository now has an interface Doctrine\Common\Persistence\ObjectRepository. This means that your classes that override EntityRepository and extend find(), findOneBy() or findBy() must be adjusted to follow this interface.
+The EntityRepository now has an interface Doctrine\Persistence\ObjectRepository. This means that your classes that override EntityRepository and extend find(), findOneBy() or findBy() must be adjusted to follow this interface.
 
 ## AnnotationReader changes
 

bin/doctrine.bat

@@ -1,9 +1,9 @@
-@echo off
-
-if "%PHPBIN%" == "" set PHPBIN=@php_bin@
-if not exist "%PHPBIN%" if "%PHP_PEAR_PHP_BIN%" neq "" goto USE_PEAR_PATH
-GOTO RUN
-:USE_PEAR_PATH
-set PHPBIN=%PHP_PEAR_PHP_BIN%
-:RUN
-"%PHPBIN%" "@bin_dir@\doctrine" %*
+@echo off
+
+if "%PHPBIN%" == "" set PHPBIN=@php_bin@
+if not exist "%PHPBIN%" if "%PHP_PEAR_PHP_BIN%" neq "" goto USE_PEAR_PATH
+GOTO RUN
+:USE_PEAR_PATH
+set PHPBIN=%PHP_PEAR_PHP_BIN%
+:RUN
+"%PHPBIN%" "@bin_dir@\doctrine" %*

build.properties

@@ -1,3 +0,0 @@
-# Version class and file
-project.version_class = Doctrine\\ORM\\Version
-project.version_file = lib/Doctrine/ORM/Version.php

build.properties.dev

@@ -1,16 +0,0 @@
-version=2.0.0BETA2
-dependencies.common=2.0.0BETA4
-dependencies.dbal=2.0.0BETA4
-stability=beta
-build.dir=build
-dist.dir=dist
-report.dir=reports
-log.archive.dir=logs
-project.pirum_dir=
-project.download_dir=
-project.xsd_dir=
-test.phpunit_configuration_file=
-test.phpunit_generate_coverage=0
-test.pmd_reports=0
-test.pdepend_exec=
-test.phpmd_exec=

build.xml

@@ -1,101 +0,0 @@
-<?xml version="1.0"?>
-<project name="DoctrineORM" default="build" basedir=".">
-    <property file="build.properties" />
-
-    <target name="php">
-        <exec executable="which" outputproperty="php_executable">
-            <arg value="php" />
-        </exec>
-    </target>
-
-    <target name="prepare">
-        <mkdir dir="build" />
-    </target>
-
-    <target name="build" depends="check-git-checkout-clean,prepare,php,composer">
-        <exec executable="${php_executable}">
-            <arg value="build/composer.phar" />
-            <arg value="archive" />
-            <arg value="--dir=build" />
-        </exec>
-    </target>
-
-    <target name="composer" depends="php,composer-check,composer-download">
-        <exec executable="${php_executable}">
-            <arg value="build/composer.phar" />
-            <arg value="install" />
-        </exec>
-    </target>
-
-    <target name="composer-check" depends="prepare">
-        <available file="build/composer.phar" property="composer.present"/>
-    </target>
-
-    <target name="composer-download" unless="composer.present">
-        <exec executable="wget">
-            <arg value="-Obuild/composer.phar" />
-            <arg value="http://getcomposer.org/composer.phar" />
-        </exec>
-    </target>
-
-    <target name="make-release" depends="check-git-checkout-clean,prepare,php">
-        <replace file="${project.version_file}" token="-DEV" value="" failOnNoReplacements="true" />
-        <exec executable="${php_executable}" outputproperty="doctrine.current_version" failonerror="true">
-            <arg value="-r" />
-            <arg value="require_once '${project.version_file}';echo ${project.version_class}::VERSION;" />
-        </exec>
-        <exec executable="${php_executable}" outputproperty="doctrine.next_version" failonerror="true">
-            <arg value="-r" />
-            <arg value="$parts = explode('.', str_ireplace(array('-DEV', '-ALPHA', '-BETA'), '', '${doctrine.current_version}'));
-                if (count($parts) != 3) {
-                    throw new \InvalidArgumentException('Version is assumed in format x.y.z, ${doctrine.current_version} given');
-                }
-                $parts[2]++;
-                echo implode('.', $parts);
-            " />
-        </exec>
-
-        <git-commit file="${project.version_file}" message="Release ${doctrine.current_version}" />
-        <git-tag version="${doctrine.current_version}" />
-        <replace file="${project.version_file}" token="${doctrine.current_version}" value="${doctrine.next_version}-DEV" />
-        <git-commit file="${project.version_file}" message="Bump version to ${doctrine.next_version}" />
-    </target>
-
-    <target name="check-git-checkout-clean">
-        <exec executable="git" failonerror="true">
-            <arg value="diff-index" />
-            <arg value="--quiet" />
-            <arg value="HEAD" />
-        </exec>
-    </target>
-
-    <macrodef name="git-commit">
-        <attribute name="file" default="NOT SET"/>
-        <attribute name="message" default="NOT SET"/>
-
-        <sequential>
-            <exec executable="git">
-                <arg value="add" />
-                <arg value="@{file}" />
-            </exec>
-            <exec executable="git">
-                <arg value="commit" />
-                <arg value="-m" />
-                <arg value="@{message}" />
-            </exec>
-        </sequential>
-    </macrodef>
-
-    <macrodef name="git-tag">
-        <attribute name="version" default="NOT SET" />
-
-        <sequential>
-            <exec executable="git">
-                <arg value="tag" />
-                <arg value="-m" />
-                <arg value="v@{version}" />
-                <arg value="v@{version}" />
-            </exec>
-        </sequential>
-    </macrodef>
-</project>

ci/github/phpunit/mysqli.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="utf-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true"
+         beStrictAboutOutputDuringTests="true"
+         beStrictAboutTodoAnnotatedTests="true"
+         failOnRisky="true"
+         failOnWarning="true"
+>
+    <php>
+        <var name="db_driver" value="mysqli"/>
+        <var name="db_host" value="127.0.0.1" />
+        <var name="db_port" value="3306"/>
+        <var name="db_user" value="root" />
+        <var name="db_dbname" value="doctrine_tests" />
+
+        <!-- necessary change for some CLI/console output test assertions -->
+        <env name="COLUMNS" value="120"/>
+    </php>
+
+    <testsuites>
+        <testsuite name="Doctrine DBAL Test Suite">
+            <directory>../../../tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory suffix=".php">../../../lib/Doctrine</directory>
+        </whitelist>
+    </filter>
+
+    <groups>
+        <exclude>
+            <group>performance</group>
+            <group>locking_functional</group>
+        </exclude>
+    </groups>
+</phpunit>

ci/github/phpunit/pdo_mysql.xml

@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="utf-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true"
+         beStrictAboutOutputDuringTests="true"
+         beStrictAboutTodoAnnotatedTests="true"
+         failOnRisky="true"
+         failOnWarning="true"
+>
+    <php>
+        <var name="db_driver" value="pdo_mysql"/>
+        <var name="db_host" value="127.0.0.1" />
+        <var name="db_port" value="3306"/>
+        <var name="db_user" value="root" />
+        <var name="db_dbname" value="doctrine_tests" />
+
+        <!-- necessary change for some CLI/console output test assertions -->
+        <env name="COLUMNS" value="120"/>
+    </php>
+
+    <testsuites>
+        <testsuite name="Doctrine DBAL Test Suite">
+            <directory>../../../tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory suffix=".php">../../../lib/Doctrine</directory>
+        </whitelist>
+    </filter>
+
+
+    <groups>
+        <exclude>
+            <group>performance</group>
+            <group>locking_functional</group>
+        </exclude>
+    </groups>
+</phpunit>

ci/github/phpunit/pdo_pgsql.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="utf-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true"
+         beStrictAboutOutputDuringTests="true"
+         beStrictAboutTodoAnnotatedTests="true"
+         failOnRisky="true"
+         failOnWarning="true"
+>
+    <php>
+        <var name="db_driver" value="pdo_pgsql"/>
+        <var name="db_host" value="localhost" />
+        <var name="db_user" value="postgres" />
+        <var name="db_password" value="postgres" />
+        <var name="db_dbname" value="doctrine_tests" />
+
+        <!-- necessary change for some CLI/console output test assertions -->
+        <env name="COLUMNS" value="120"/>
+    </php>
+
+    <testsuites>
+        <testsuite name="Doctrine DBAL Test Suite">
+            <directory>../../../tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory suffix=".php">../../../lib/Doctrine</directory>
+        </whitelist>
+    </filter>
+
+    <groups>
+        <exclude>
+            <group>performance</group>
+            <group>locking_functional</group>
+        </exclude>
+    </groups>
+</phpunit>

ci/github/phpunit/sqlite.xml

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true"
+         beStrictAboutOutputDuringTests="true"
+         beStrictAboutTodoAnnotatedTests="true"
+         failOnRisky="true"
+         failOnWarning="true"
+>
+    <php>
+        <!-- necessary change for some CLI/console output test assertions -->
+        <env name="COLUMNS" value="120"/>
+    </php>
+
+    <testsuites>
+        <testsuite name="Doctrine DBAL Test Suite">
+            <directory>../../../tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory suffix=".php">../../../lib/Doctrine</directory>
+        </whitelist>
+    </filter>
+
+    <groups>
+        <exclude>
+            <group>performance</group>
+            <group>locking_functional</group>
+        </exclude>
+    </groups>
+</phpunit>

composer.json

@@ -3,7 +3,7 @@
     "type": "library",
     "description": "Object-Relational-Mapper for PHP",
     "keywords": ["orm", "database"],
-    "homepage": "http://www.doctrine-project.org",
+    "homepage": "https://www.doctrine-project.org/projects/orm.html",
     "license": "MIT",
     "authors": [
         {"name": "Guilherme Blanco", "email": "guilhermeblanco@gmail.com"},
@@ -18,19 +18,25 @@
     "require": {
         "php": "^7.1",
         "ext-pdo": "*",
-        "doctrine/annotations": "~1.5",
-        "doctrine/cache": "~1.6",
-        "doctrine/collections": "^1.4",
-        "doctrine/common": "^2.7.1",
-        "doctrine/dbal": "^2.6",
-        "doctrine/instantiator": "~1.1",
-        "symfony/console": "~3.0|~4.0"
+        "composer/package-versions-deprecated": "^1.8",
+        "doctrine/annotations": "^1.11.1",
+        "doctrine/cache": "^1.9.1",
+        "doctrine/collections": "^1.5",
+        "doctrine/common": "^2.11 || ^3.0",
+        "doctrine/dbal": "^2.9.3",
+        "doctrine/event-manager": "^1.1",
+        "doctrine/inflector": "^1.0",
+        "doctrine/instantiator": "^1.3",
+        "doctrine/lexer": "^1.0",
+        "doctrine/persistence": "^1.3.3 || ^2.0",
+        "symfony/console": "^3.0|^4.0|^5.0"
     },
     "require-dev": {
-        "doctrine/coding-standard": "^1.0",
-        "phpunit/phpunit": "^6.5",
-        "squizlabs/php_codesniffer": "^3.2",
-        "symfony/yaml": "~3.4|~4.0"
+        "doctrine/coding-standard": "^6.0",
+        "phpstan/phpstan": "^0.12.18",
+        "phpunit/phpunit": "^8.0",
+        "symfony/yaml": "^3.4|^4.0|^5.0",
+        "vimeo/psalm": "^3.11"
     },
     "suggest": {
         "symfony/yaml": "If you want to use YAML Metadata Mapping Driver"
@@ -47,7 +53,7 @@
     "bin": ["bin/doctrine"],
     "extra": {
         "branch-alias": {
-            "dev-master": "2.6.x-dev"
+            "dev-master": "2.7.x-dev"
         }
     },
     "archive": {

docs/bin/generate-docs.sh

@@ -7,4 +7,4 @@ rm build -Rf
 sphinx-build en build
 
 sphinx-build -b latex en build/pdf
-rubber --into build/pdf --pdf build/pdf/Doctrine2ORM.tex
+rubber --into build/pdf --pdf build/pdf/Doctrine2ORM.tex

docs/bin/install-dependencies.sh

@@ -1,2 +1,2 @@
 #!/bin/bash
-sudo apt-get update && sudo apt-get install -y python2.7 python-sphinx python-pygments
+sudo apt-get update && sudo apt-get install -y python2.7 python-sphinx python-pygments

docs/en/changelog/migration_2_5.rst

@@ -1,711 +0,0 @@
-What is new in Doctrine ORM 2.5?
-================================
-
-This document describes changes between Doctrine ORM 2.4 and 2.5.
-It contains a description of all the new features and sections about
-behavioral changes and potential backwards compatibility breaks.
-Please review this document carefully when updating to Doctrine 2.5.
-
-First note, that with the ORM 2.5 release we are dropping support
-for PHP 5.3. We are enforcing this with Composer, servers without
-at least PHP 5.4 will not allow installing Doctrine 2.5.
-
-New Features and Improvements
------------------------------
-
-Events: PostLoad now triggered after associations are loaded
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Before Doctrine 2.5 if you had an entity with a ``@PostLoad`` event
-defined then Doctrine would trigger listeners after the fields were
-loaded, but before assocations are available.
-
-- `DDC-54 <http://doctrine-project.org/jira/browse/DDC-54>`_
-- `Commit #a90629 <https://github.com/doctrine/doctrine2/commit/a906295c65f1516737458fbee2f6fa96254f27a5>`_
-
-Events: Add API to programatically add event listeners to Entity
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When developing third party libraries or decoupled applications
-it can be interesting to develop an entity listener without knowing
-the entities that require this listener.
-
-You can now attach entity listeners to entities using the
-``AttachEntityListenersListener`` class, which is listening to the
-``loadMetadata`` event that is fired once for every entity during
-metadata generation:
-
-.. code-block:: php
-
-    <?php
-    use Doctrine\ORM\Tools\AttachEntityListenersListener;
-    use Doctrine\ORM\Events;
-
-    $listener = new AttachEntityListenersListener();
-    $listener->addEntityListener(
-        'MyProject\Entity\User', 'MyProject\Listener\TimestampableListener',
-        Events::prePersist, 'onPrePersist'
-    );
-
-    $evm->addEventListener(Events::loadClassMetadata, $listener);
-
-    class TimestampableListener
-    {
-        public function onPrePersist($event)
-        {
-            $entity = $event->getEntity();
-            $entity->setCreated(new \DateTime('now'));
-        }
-    }
-
-Embeddable Objects
-~~~~~~~~~~~~~~~~~~
-
-Doctrine now supports creating multiple PHP objects from one database table
-implementing a feature called "Embeddable Objects". Next to an ``@Entity``
-class you can now define a class that is embeddable into a database table of an
-entity using the ``@Embeddable`` annotation. Embeddable objects can never be
-saved, updated or deleted on their own, only as part of an entity (called
-"root-entity" or "aggregate"). Consequently embeddables don't have a primary
-key, they are identified only by their values.
-
-Example of defining and using embeddables classes:
-
-.. code-block:: php
-
-    <?php
-
-    /** @Entity */
-    class Product
-    {
-        /** @Id @Column(type="integer") @GeneratedValue */
-        private $id;
-
-        /** @Embedded(class = "Money") */
-        private $price;
-    }
-
-    /** @Embeddable */
-    class Money
-    {
-        /** @Column(type = "decimal") */
-        private $value;
-
-        /** @Column(type = "string") */
-        private $currency = 'EUR';
-    }
-
-You can read more on the features of Embeddables objects `in the documentation
-<http://docs.doctrine-project.org/en/latest/tutorials/embeddables.html>`_.
-
-This feature was developed by external contributor `Johannes Schmitt
-<https://twitter.com/schmittjoh>`_
-
-- `DDC-93 <http://doctrine-project.org/jira/browse/DDC-93>`_
-- `Pull Request #835 <https://github.com/doctrine/doctrine2/pull/835>`_
-
-Second-Level-Cache
-~~~~~~~~~~~~~~~~~~
-
-Since version 2.0 of Doctrine, fetching the same object twice by primary key
-would result in just one query. This was achieved by the identity map pattern
-(first-level-cache) that kept entities in memory. 
-
-The newly introduced second-level-cache works a bit differently. Instead
-of saving objects in memory, it saves them in a fast in-memory cache such
-as Memcache, Redis, Riak or MongoDB. Additionally it allows saving the result
-of more complex queries than by primary key. Summarized this feature works
-like the existing Query result cache, but it is much more powerful.
-
-As an example lets cache an entity Country that is a relation to the User
-entity. We always want to display the country, but avoid the additional
-query to this table.
-
-.. code-block:: php
-
-    <?php
-    /**
-     * @Entity
-     * @Cache(usage="READ_ONLY", region="country_region")
-     */
-    class Country
-    {
-        /**
-         * @Id
-         * @GeneratedValue
-         * @Column(type="integer")
-         */
-        protected $id;
-
-        /**
-         * @Column(unique=true)
-         */
-        protected $name;
-    }
-
-In this example we have specified a caching region name called
-``country_region``, which we have to configure now on the EntityManager:
-
-.. code-block:: php
-
-    $config = new \Doctrine\ORM\Configuration();
-    $config->setSecondLevelCacheEnabled();
-
-    $cacheConfig  =  $config->getSecondLevelCacheConfiguration();
-    $regionConfig =  $cacheConfig->getRegionsConfiguration();
-    $regionConfig->setLifetime('country_region', 3600); 
-
-Now Doctrine will first check for the data of any country in the cache
-instead of the database.
-
-- `Documentation
-  <http://docs.doctrine-project.org/en/latest/reference/second-level-cache.html>`_
-- `Pull Request #808 <https://github.com/doctrine/doctrine2/pull/808>`_
-
-Criteria API: Support for ManyToMany assocations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We introduced support for querying collections using the `Criteria API
-<http://docs.doctrine-project.org/en/latest/reference/working-with-associations.html#filtering-collections>`_
-in 2.4. This only worked efficently for One-To-Many assocations, not for
-Many-To-Many. With the start of 2.5 also Many-To-Many associations get queried
-instead of loading them into memory.
-
-Criteria API: Add new contains() expression
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It is now possible to use the Criteria API to check for string contains needle
-using ``contains()``. This translates to using a ``column LIKE '%needle%'`` SQL
-condition.
-
-.. code-block:: php
-
-    <?php
-    use \Doctrine\Common\Collections\Criteria;
-
-    $criteria = Criteria::create()
-        ->where(Criteria::expr()->contains('name', 'Benjamin'));
-
-    $users = $repository->matching($criteria);
-
-Criteria API: Support for EXTRA_LAZY
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A collection that is marked as ``fetch="EXTRA_LAZY"`` will now return another
-lazy collection when using ``Collection::matching($criteria)``:
-
-.. code-block:: php
-
-    <?php
-
-    class Post
-    {
-        /** @OneToMany(targetEntity="Comment", fetch="EXTRA_LAZY") */
-        private $comments;
-    }
-
-    $criteria = Criteria::create()
-        ->where(Criteria->expr()->eq("published", 1));
-
-    $publishedComments = $post->getComments()->matching($criteria);
-
-    echo count($publishedComments);
-
-The lazy criteria currently supports the ``count()`` and ``contains()``
-functionality lazily. All other operations of the ``Collection`` interface
-trigger a full load of the collection.
-
-This feature was contributed by `Michaël Gallego <https://github.com/bakura10>`_.
-
-- `Pull Request #882 <https://github.com/doctrine/doctrine2/pull/882>`_
-- `Pull Request #1032 <https://github.com/doctrine/doctrine2/pull/1032>`_
-
-Mapping: Allow configuring Index flags
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It is now possible to control the index flags in the DBAL
-schema abstraction from the ORM using metadata. This was possible
-only with a schema event listener before.
-
-.. code-block:: php
-
-    <?php
-
-    /**
-     * @Table(name="product", indexes={@Index(columns={"description"},flags={"fulltext"})})
-     */
-    class Product
-    {
-        private $description;
-    }
-
-This feature was contributed by `Adrian Olek <https://github.com/adrianolek>`_.
-
-- `Pull Request #973 <https://github.com/doctrine/doctrine2/pull/973>`_
-
-SQLFilter API: Check if a parameter is set
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can now check in your SQLFilter if a parameter was set. This allows
-to more easily control which features of a filter to enable or disable.
-
-Extending on the locale example of the documentation:
-
-.. code-block:: php
-
-    <?php
-    class MyLocaleFilter extends SQLFilter
-    {
-        public function addFilterConstraint(ClassMetadata $targetEntity, $targetTableAlias)
-        {
-            if (!$targetEntity->reflClass->implementsInterface('LocaleAware')) {
-                return "";
-            }
-
-            if (!$this->hasParameter('locale')) {
-                return "";
-            }
-
-            return $targetTableAlias.'.locale = ' . $this->getParameter('locale');
-        }
-    }
-
-This feature was contributed by `Miroslav Demovic <https://github.com/mdemo>`_
-
-- `Pull Request #963 <https://github.com/doctrine/doctrine2/pull/963>`_
-
-
-EXTRA_LAZY Improvements
-~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Efficient query when using EXTRA_LAZY and containsKey
-
-    When calling ``Collection::containsKey($key)`` on one-to-many and many-to-many
-    collections using ``indexBy`` and ``EXTRA_LAZY`` a query is now executed to check
-    for the existance for the item. Prevoiusly this operation was performed in memory
-    by loading all entities of the collection.
-
-    .. code-block:: php
-
-        <?php
-
-        class User
-        {
-            /** @OneToMany(targetEntity="Group", indexBy="id") */
-            private $groups;
-        }
-
-        if ($user->getGroups()->containsKey($groupId)) {
-            echo "User is in group $groupId\n";
-        }
-
-    This feature was contributed by `Asmir Mustafic <https://github.com/goetas>`_
-
-    - `Pull Request #937 <https://github.com/doctrine/doctrine2/pull/937>`_
-
-2. Add EXTRA_LAZY Support for get() for owning and inverse many-to-many 
-
-   This was contributed by `Sander Marechal <https://github.com/sandermarechal>`_.
-
-Improve efficiency of One-To-Many EAGER
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When marking a one-to-many association with ``fetch="EAGER"`` it will now
-execute one query less than before and work correctly in combination with
-``indexBy``.
-
-Better support for EntityManagerInterface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Many of the locations where previously only the ``Doctrine\ORM\EntityManager``
-was allowed are now changed to accept the ``EntityManagerInterface`` that was
-introduced in 2.4. This allows you to more easily use the decorator pattern
-to extend the EntityManager if you need. It's still not replaced everywhere,
-so you still have to be careful.
-
-DQL Improvements
-~~~~~~~~~~~~~~~~
-
-1. It is now possible to add functions to the ``ORDER BY`` clause in DQL statements:
-
-.. code-block:: php
-
-    <?php
-    $dql = "SELECT u FROM User u ORDER BY CONCAT(u.username, u.name)";
-
-2. Support for functions in ``IS NULL`` expressions:
-
-.. code-block:: php
-
-    <?php
-    $dql = "SELECT u.name FROM User u WHERE MAX(u.name) IS NULL";
-
-3. A ``LIKE`` expression is now suported in ``HAVING`` clause.
-
-4. Subselects are now supported inside a ``NEW()`` expression:
-
-.. code-block:: php
-
-    <?php
-    $dql = "SELECT new UserDTO(u.name, SELECT count(g.id) FROM Group g WHERE g.id = u.id) FROM User u";
-
-5. ``MEMBER OF`` expression now allows to filter for more than one result:
-
-.. code-block:: php
-
-   <?php
-   $dql = "SELECT u FROM User u WHERE :groups MEMBER OF u.groups";
-   $query = $entityManager->createQuery($dql);
-   $query->setParameter('groups', array(1, 2, 3));
-
-   $users = $query->getResult();
-
-6. Expressions inside ``COUNT()`` now allowed
-
-.. code-block:: php
-
-    <?php
-    $dql = "SELECT COUNT(DISTINCT CONCAT(u.name, u.lastname)) FROM User u";
-
-7. Add support for ``HOUR`` in ``DATE_ADD()``/``DATE_SUB()`` functions
-
-Custom DQL Functions: Add support for factories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Previously custom DQL functions could only be provided with their
-full-qualified class-name, preventing runtime configuration through
-dependency injection.
-
-A simplistic approach has been contributed by `Matthieu Napoli
-<https://github.com/mnapoli>`_ to pass a callback instead that resolves
-the function:
-
-.. code-block:: php
-
-    <?php
-
-    $config = new \Doctrine\ORM\Configuration();
-
-    $config->addCustomNumericFunction(
-        'IS_PUBLISHED', function($funcName) use ($currentSiteId) {
-            return new IsPublishedFunction($currentSiteId);
-         }
-    );
-
-Query API: WHERE IN Query using a Collection as parameter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When performing a ``WHERE IN`` query for a collection of entities you can
-now pass the array collection of entities as a parameter value to the query
-object:
-
-.. code-block:: php
-
-    <?php
-
-    $categories = $rootCategory->getChildren();
-
-    $queryBuilder
-        ->select('p')
-        ->from('Product', 'p')
-        ->where('p.category IN (:categories)')
-        ->setParameter('categories', $categories)
-    ;
-
-This feature was contributed by `Michael Perrin
-<https://github.com/michaelperrin>`_.
-
-- `Pull Request #590 <https://github.com/doctrine/doctrine2/pull/590>`_
-- `DDC-2319 <http://doctrine-project.org/jira/browse/DDC-2319>`_
-
-Query API: Add support for default Query Hints
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To configure multiple different features such as custom AST Walker, fetch modes,
-locking and other features affecting DQL generation we have had a feature
-called "query hints" since version 2.0. 
-
-It is now possible to add query hints that are always enabled for every Query:
-
-.. code-block:: php
-
-    <?php
-
-    $config = new \Doctrine\ORM\Configuration();
-    $config->setDefaultQueryHints(
-        'doctrine.customOutputWalker' => 'MyProject\CustomOutputWalker'
-    );
-
-This feature was contributed by `Artur Eshenbrener
-<https://github.com/Strate>`_.
-
-- `Pull Request #863 <https://github.com/doctrine/doctrine2/pull/863>`_
-
-ResultSetMappingBuilder: Add support for Single-Table Inheritance
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Before 2.5 the ResultSetMappingBuilder did not work with entities
-that are using Single-Table-Inheritance. This restriction was lifted
-by adding the missing support.
-
-YAML Mapping: Many-To-Many doesnt require join column definition
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In Annotations and XML it was not necessary using conventions for naming
-the many-to-many join column names, in YAML it was not possible however.
-
-A many-to-many definition in YAML is now possible using this minimal
-definition:
-
-.. code-block:: yaml
-
-    manyToMany:
-        groups:
-            targetEntity: Group
-            joinTable:
-                name: users_groups
-
-Schema Validator Command: Allow to skip sub-checks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The Schema Validator command executes two independent checks
-for validity of the mappings and if the schema is synchronized
-correctly. It is now possible to skip any of the two steps
-when executing the command:
-
-::
-
-    $ php vendor/bin/doctrine orm:validate-schema --skip-mapping
-    $ php vendor/bin/doctrine orm:validate-schema --skip-sync
-
-This allows you to write more specialized continuous integration and automation
-checks. When no changes are found the command returns the exit code 0
-and 1, 2 or 3 when failing because of mapping, sync or both.
-
-EntityGenerator Command: Avoid backups
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When calling the EntityGenerator for an existing entity, Doctrine would
-create a backup file every time to avoid losing changes to the code. You
-can now skip generating the backup file by passing the ``--no-backup``
-flag:
-
-::
-
-    $ php vendor/bin/doctrine orm:generate-entities src/ --no-backup
-
-Support for Objects as Identifiers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It is now possible to use Objects as identifiers for Entities
-as long as they implement the magic method ``__toString()``.
-
-.. code-block:: php
-
-    <?php
-
-    class UserId
-    {
-        private $value;
-
-        public function __construct($value)
-        {
-            $this->value = $value;
-        }
-
-        public function __toString()
-        {
-            return (string)$this->value;
-        }
-    }
-
-    class User
-    {
-        /** @Id @Column(type="userid") */
-        private $id;
-
-        public function __construct(UserId $id)
-        {
-            $this->id = $id;
-        }
-    }
-
-    class UserIdType extends \Doctrine\DBAL\Types\Type
-    {
-        // ...
-    }
-
-    Doctrine\DBAL\Types\Type::addType('userid', 'MyProject\UserIdType');
-
-Behavioral Changes (BC Breaks)
-------------------------------
-
-NamingStrategy interface changed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``Doctrine\ORM\Mapping\NamingStrategyInterface`` changed slightly
-to pass the Class Name of the entity into the join column name generation:
-
-:: 
-
-    -    function joinColumnName($propertyName);
-    +    function joinColumnName($propertyName, $className = null);
-
-It also received a new method for supporting embeddables:
-
-::
-
-    public function embeddedFieldToColumnName($propertyName, $embeddedColumnName);
-
-Minor BC BREAK: EntityManagerInterface instead of EntityManager in type-hints
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 
-As of 2.5, classes requiring the ``EntityManager`` in any method signature will now require 
-an ``EntityManagerInterface`` instead.
-If you are extending any of the following classes, then you need to check following
-signatures:
-
-- ``Doctrine\ORM\Tools\DebugUnitOfWorkListener#dumpIdentityMap(EntityManagerInterface $em)``
-- ``Doctrine\ORM\Mapping\ClassMetadataFactory#setEntityManager(EntityManagerInterface $em)``
-
-Minor BC BREAK: Custom Hydrators API change
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-As of 2.5, ``AbstractHydrator`` does not enforce the usage of cache as part of
-API, and now provides you a clean API for column information through the method
-``hydrateColumnInfo($column)``.
-Cache variable being passed around by reference is no longer needed since
-Hydrators are per query instantiated since Doctrine 2.4.
-
-- `DDC-3060 <http://doctrine-project.org/jira/browse/DDC-3060>`_
-
-Minor BC BREAK: All non-transient classes in an inheritance must be part of the inheritance map
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-As of 2.5, classes, if you define an inheritance map for an inheritance tree, you are required
-to map all non-transient classes in that inheritance, including the root of the inheritance.
-
-So far, the root of the inheritance was allowed to be skipped in the inheritance map: this is
-not possible anymore, and if you don't plan to persist instances of that class, then you should
-either:
-
-- make that class as ``abstract``
-- add that class to your inheritance map
-
-If you fail to do so, then a ``Doctrine\ORM\Mapping\MappingException`` will be thrown.
-
-
-- `DDC-3300 <http://doctrine-project.org/jira/browse/DDC-3300>`_
-- `DDC-3503 <http://doctrine-project.org/jira/browse/DDC-3503>`_
-
-Minor BC BREAK: Entity based EntityManager#clear() calls follow cascade detach
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Whenever ``EntityManager#clear()`` method gets called with a given entity class
-name, until 2.4, it was only detaching the specific requested entity.
-As of 2.5, ``EntityManager`` will follow configured cascades, providing a better
-memory management since associations will be garbage collected, optimizing
-resources consumption on long running jobs.
-
-Updates on entities scheduled for deletion are no longer processed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In Doctrine 2.4, if you modified properties of an entity scheduled for deletion, UnitOfWork would
-produce an ``UPDATE`` statement to be executed right before the ``DELETE`` statement. The entity in question
-was therefore present in ``UnitOfWork#entityUpdates``, which means that ``preUpdate`` and ``postUpdate``
-listeners were (quite pointlessly) called. In ``preFlush`` listeners, it used to be possible to undo
-the scheduled deletion for updated entities (by calling ``persist()`` if the entity was found in both
-``entityUpdates`` and ``entityDeletions``). This does not work any longer, because the entire changeset
-calculation logic is optimized away.
-
-Minor BC BREAK: Default lock mode changed from LockMode::NONE to null in method signatures
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A misconception concerning default lock mode values in method signatures lead to unexpected behaviour
-in SQL statements on SQL Server. With a default lock mode of ``LockMode::NONE`` throughout the
-method signatures in ORM, the table lock hint ``WITH (NOLOCK)`` was appended to all locking related
-queries by default. This could result in unpredictable results because an explicit ``WITH (NOLOCK)``
-table hint tells SQL Server to run a specific query in transaction isolation level READ UNCOMMITTED
-instead of the default READ COMMITTED transaction isolation level.
-Therefore there now is a distinction between ``LockMode::NONE`` and ``null`` to be able to tell
-Doctrine whether to add table lock hints to queries by intention or not. To achieve this, the following
-method signatures have been changed to declare ``$lockMode = null`` instead of ``$lockMode = LockMode::NONE``:
-
-- ``Doctrine\ORM\Cache\Persister\AbstractEntityPersister#getSelectSQL()``
-- ``Doctrine\ORM\Cache\Persister\AbstractEntityPersister#load()``
-- ``Doctrine\ORM\Cache\Persister\AbstractEntityPersister#refresh()``
-- ``Doctrine\ORM\Decorator\EntityManagerDecorator#find()``
-- ``Doctrine\ORM\EntityManager#find()``
-- ``Doctrine\ORM\EntityRepository#find()``
-- ``Doctrine\ORM\Persisters\BasicEntityPersister#getSelectSQL()``
-- ``Doctrine\ORM\Persisters\BasicEntityPersister#load()``
-- ``Doctrine\ORM\Persisters\BasicEntityPersister#refresh()``
-- ``Doctrine\ORM\Persisters\EntityPersister#getSelectSQL()``
-- ``Doctrine\ORM\Persisters\EntityPersister#load()``
-- ``Doctrine\ORM\Persisters\EntityPersister#refresh()``
-- ``Doctrine\ORM\Persisters\JoinedSubclassPersister#getSelectSQL()``
-
-You should update signatures for these methods if you have subclassed one of the above classes.
-Please also check the calling code of these methods in your application and update if necessary.
-
-.. note::
-
-    This in fact is really a minor BC BREAK and should not have any affect on database vendors
-    other than SQL Server because it is the only one that supports and therefore cares about
-    ``LockMode::NONE``. It's really just a FIX for SQL Server environments using ORM.
-
-Minor BC BREAK: __clone method not called anymore when entities are instantiated via metadata API
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-As of PHP 5.6, instantiation of new entities is deferred to the
-`doctrine/instantiator <https://github.com/doctrine/instantiator>`_ library, which will avoid calling ``__clone``
-or any public API on instantiated objects.
-
-BC BREAK: DefaultRepositoryFactory is now final
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Please implement the ``Doctrine\ORM\Repository\RepositoryFactory`` interface instead of extending
-the ``Doctrine\ORM\Repository\DefaultRepositoryFactory``.
-
-BC BREAK: New object expression DQL queries now respects user provided aliasing and not return consumed fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When executing DQL queries with new object expressions, instead of returning
-DTOs numerically indexes, it will now respect user provided aliases. Consider
-the following query:
-
-::
-
-    SELECT new UserDTO(u.id,u.name) as user,new AddressDTO(a.street,a.postalCode) as address, a.id as addressId
-    FROM User u INNER JOIN u.addresses a WITH a.isPrimary = true
-    
-Previously, your result would be similar to this:
-
-::
-
-    array(
-        0=>array(
-            0=>{UserDTO object},
-            1=>{AddressDTO object},
-            2=>{u.id scalar},
-            3=>{u.name scalar},
-            4=>{a.street scalar},
-            5=>{a.postalCode scalar},
-            'addressId'=>{a.id scalar},
-        ),
-        ...
-    )
-
-From now on, the resultset will look like this:
-
-::
-
-    array(
-        0=>array(
-            'user'=>{UserDTO object},
-            'address'=>{AddressDTO object},
-            'addressId'=>{a.id scalar}
-        ),
-        ...
-    )
-

docs/en/cookbook/advanced-field-value-conversion-using-custom-mapping-types.rst

@@ -11,9 +11,9 @@ There are several ways to achieve this: converting the value inside the Type
 class, converting the value on the database-level or a combination of both.
 
 This article describes the third way by implementing the MySQL specific column
-type `Point <http://dev.mysql.com/doc/refman/5.5/en/gis-class-point.html>`_.
+type `Point <https://dev.mysql.com/doc/refman/8.0/en/gis-class-point.html>`_.
 
-The ``Point`` type is part of the `Spatial extension <http://dev.mysql.com/doc/refman/5.5/en/spatial-extensions.html>`_
+The ``Point`` type is part of the `Spatial extension <https://dev.mysql.com/doc/refman/8.0/en/spatial-extensions.html>`_
 of MySQL and enables you to store a single location in a coordinate space by
 using x and y coordinates. You can use the Point type to store a 
 longitude/latitude pair to represent a geographic location.
@@ -192,9 +192,9 @@ object into a string representation before saving to the database (in the
 ``convertToDatabaseValue`` method) and back into an object after fetching the
 value from the database (in the ``convertToPHPValue`` method).
 
-The format of the string representation format is called `Well-known text (WKT)
-<http://en.wikipedia.org/wiki/Well-known_text>`_. The advantage of this format
-is, that it is both human readable and parsable by MySQL.
+The format of the string representation format is called
+`Well-known text (WKT) <http://en.wikipedia.org/wiki/Well-known_text>`_.
+The advantage of this format is, that it is both human readable and parsable by MySQL.
 
 Internally, MySQL stores geometry values in a binary format that is not 
 identical to the WKT format. So, we need to let MySQL transform the WKT
@@ -204,8 +204,8 @@ This is where the ``convertToPHPValueSQL`` and  ``convertToDatabaseValueSQL``
 methods come into play.
 
 This methods wrap a sql expression (the WKT representation of the Point) into
-MySQL functions `PointFromText <http://dev.mysql.com/doc/refman/5.5/en/creating-spatial-values.html#function_pointfromtext>`_
-and `AsText <http://dev.mysql.com/doc/refman/5.5/en/functions-to-convert-geometries-between-formats.html#function_astext>`_
+MySQL functions `ST_PointFromText <https://dev.mysql.com/doc/refman/8.0/en/gis-wkt-functions.html#function_st-pointfromtext>`_
+and `ST_AsText <https://dev.mysql.com/doc/refman/8.0/en/gis-format-conversion-functions.html#function_st-astext>`_
 which convert WKT strings to and from the internal format of MySQL.
 
 .. note::
@@ -249,7 +249,7 @@ Example usage
     $em->clear();
 
     // Fetch the Location object
-    $query = $em->createQuery("SELECT l FROM Geo\Entity\Location WHERE l.address = '1600 Amphitheatre Parkway, Mountain View, CA'");
+    $query = $em->createQuery("SELECT l FROM Geo\Entity\Location l WHERE l.address = '1600 Amphitheatre Parkway, Mountain View, CA'");
     $location = $query->getSingleResult();
 
     /* @var Geo\ValueObject\Point */

docs/en/cookbook/aggregate-fields.rst

@@ -22,7 +22,7 @@ into the account can either be of positive or negative money
 values. Each account has a credit limit and the account is never
 allowed to have a balance below that value.
 
-For simplicity we live in a world were money is composed of
+For simplicity we live in a world where money is composed of
 integers only. Also we omit the receiver/sender name, stated reason
 for transfer and the execution date. These all would have to be
 added on the ``Entry`` object.
@@ -32,30 +32,39 @@ Our entities look like:
 .. code-block:: php
 
     <?php
+
     namespace Bank\Entities;
+
+    use Doctrine\ORM\Mapping as ORM;
     
     /**
-     * @Entity
+     * @ORM\Entity
      */
     class Account
     {
-        /** @Id @GeneratedValue @Column(type="integer") */
-        private $id;
-    
-        /** @Column(type="string", unique=true) */
-        private $no;
+        /**
+         * @ORM\Id
+         * @ORM\GeneratedValue
+         * @ORM\Column(type="integer")
+         */
+        private ?int $id;
     
         /**
-         * @OneToMany(targetEntity="Entry", mappedBy="account", cascade={"persist"})
+         * @ORM\Column(type="string", unique=true)
          */
-        private $entries;
+        private string $no;
     
         /**
-         * @Column(type="integer")
+         * @ORM\OneToMany(targetEntity="Entry", mappedBy="account", cascade={"persist"})
          */
-        private $maxCredit = 0;
+        private array $entries;
     
-        public function __construct($no, $maxCredit = 0)
+        /**
+         * @ORM\Column(type="integer")
+         */
+        private int $maxCredit = 0;
+    
+        public function __construct(string $no, int $maxCredit = 0)
         {
             $this->no = $no;
             $this->maxCredit = $maxCredit;
@@ -64,31 +73,35 @@ Our entities look like:
     }
     
     /**
-     * @Entity
+     * @ORM\Entity
      */
     class Entry
     {
-        /** @Id @GeneratedValue @Column(type="integer") */
-        private $id;
+        /**
+         * @ORM\Id
+         * @ORM\GeneratedValue
+         * @ORM\Column(type="integer")
+         */
+        private ?int $id;
     
         /**
-         * @ManyToOne(targetEntity="Account", inversedBy="entries")
+         * @ORM\ManyToOne(targetEntity="Account", inversedBy="entries")
          */
-        private $account;
+        private Account $account;
     
         /**
-         * @Column(type="integer")
+         * @ORM\Column(type="integer")
          */
-        private $amount;
+        private int $amount;
     
-        public function __construct($account, $amount)
+        public function __construct(Account $account, int $amount)
         {
             $this->account = $account;
             $this->amount = $amount;
             // more stuff here, from/to whom, stated reason, execution date and such
         }
     
-        public function getAmount()
+        public function getAmount(): Amount
         {
             return $this->amount;
         }
@@ -146,12 +159,14 @@ collection, which means we can compute this value at runtime:
     class Account
     {
         // .. previous code
-        public function getBalance()
+
+        public function getBalance(): int
         {
             $balance = 0;
             foreach ($this->entries as $entry) {
                 $balance += $entry->getAmount();
             }
+
             return $balance;
         }
     }
@@ -175,13 +190,12 @@ relation with this method:
     <?php
     class Account
     {
-        public function addEntry($amount)
+        public function addEntry(int $amount): void
         {
             $this->assertAcceptEntryAllowed($amount);
     
             $e = new Entry($this, $amount);
             $this->entries[] = $e;
-            return $e;
         }
     }
 
@@ -190,7 +204,10 @@ Now look at the following test-code for our entities:
 .. code-block:: php
 
     <?php
-    class AccountTest extends \PHPUnit_Framework_TestCase
+
+    use PHPUnit\Framework\TestCase;
+
+    class AccountTest extends TestCase
     {
         public function testAddEntry()
         {
@@ -208,7 +225,7 @@ Now look at the following test-code for our entities:
         {
             $account = new Account("123456", $maxCredit = 200);
     
-            $this->setExpectedException("Exception");
+            $this->expectException(Exception::class);
             $account->addEntry(-1000);
         }
     }
@@ -219,9 +236,12 @@ To enforce our rule we can now implement the assertion in
 .. code-block:: php
 
     <?php
+
     class Account
     {
-        private function assertAcceptEntryAllowed($amount)
+        // .. previous code
+
+        private function assertAcceptEntryAllowed(int $amount): void
         {
             $futureBalance = $this->getBalance() + $amount;
             $allowedMinimalBalance = ($this->maxCredit * -1);
@@ -266,23 +286,22 @@ entries collection) we want to add an aggregate field called
     class Account
     {
         /**
-         * @Column(type="integer")
+         * @ORM\Column(type="integer")
          */
-        private $balance = 0;
+        private int $balance = 0;
     
-        public function getBalance()
+        public function getBalance(): int
         {
             return $this->balance;
         }
     
-        public function addEntry($amount)
+        public function addEntry(int $amount): void
         {
             $this->assertAcceptEntryAllowed($amount);
     
             $e = new Entry($this, $amount);
             $this->entries[] = $e;
             $this->balance += $amount;
-            return $e;
         }
     }
 
@@ -306,12 +325,15 @@ potentially lead to inconsistent state. See this example:
 .. code-block:: php
 
     <?php
+
+    use Bank\Entities\Account;
+
     // The Account $accId has a balance of 0 and a max credit limit of 200:
     // request 1 account
-    $account1 = $em->find('Bank\Entities\Account', $accId);
+    $account1 = $em->find(Account::class, $accId);
     
     // request 2 account
-    $account2 = $em->find('Bank\Entities\Account', $accId);
+    $account2 = $em->find(Account::class, $accId);
     
     $account1->addEntry(-200);
     $account2->addEntry(-200);
@@ -322,7 +344,7 @@ The aggregate field ``Account::$balance`` is now -200, however the
 SUM over all entries amounts yields -400. A violation of our max
 credit rule.
 
-You can use both optimistic or pessimistic locking to save-guard
+You can use both optimistic or pessimistic locking to safe-guard
 your aggregate fields against this kind of race-conditions. Reading
 Eric Evans DDD carefully he mentions that the "Aggregate Root"
 (Account in our example) needs a locking mechanism.
@@ -332,10 +354,14 @@ Optimistic locking is as easy as adding a version column:
 .. code-block:: php
 
     <?php
+
     class Account
     {
-        /** @Column(type="integer") @Version */
-        private $version;
+        /**
+         * @ORM\Column(type="integer")
+         * @ORM\Version
+         */
+        private int $version;
     }
 
 The previous example would then throw an exception in the face of
@@ -349,9 +375,11 @@ the database using a FOR UPDATE.
 .. code-block:: php
 
     <?php
+
+    use Bank\Entities\Account;
     use Doctrine\DBAL\LockMode;
-    
-    $account = $em->find('Bank\Entities\Account', $accId, LockMode::PESSIMISTIC_READ);
+
+    $account = $em->find(Account::class, $accId, LockMode::PESSIMISTIC_READ);
 
 Keeping Updates and Deletes in Sync
 -----------------------------------
@@ -372,5 +400,3 @@ field that offers serious performance benefits over iterating all
 the related objects that make up an aggregate value. Finally I
 showed how you can ensure that your aggregate fields do not get out
 of sync due to race-conditions and concurrent access.
-
-

docs/en/cookbook/dql-custom-walkers.rst

@@ -167,7 +167,7 @@ can be set via ``Query::setHint($name, $value)`` as shown in the
 previous example with the ``HINT_CUSTOM_TREE_WALKERS`` query hint.
 
 We will implement a custom Output Walker that allows to specify the
-SQL\_NO\_CACHE query hint.
+``SQL_NO_CACHE`` query hint.
 
 .. code-block:: php
 
@@ -180,7 +180,7 @@ SQL\_NO\_CACHE query hint.
 
 Our ``MysqlWalker`` will extend the default ``SqlWalker``. We will
 modify the generation of the SELECT clause, adding the
-SQL\_NO\_CACHE on those queries that need it:
+``SQL_NO_CACHE`` on those queries that need it:
 
 .. code-block:: php
 

docs/en/cookbook/dql-user-defined-functions.rst

@@ -21,7 +21,7 @@ the :doc:`Native Query <../reference/native-sql>` chapter.
 The DQL Parser has hooks to register functions that can then be
 used in your DQL queries and transformed into SQL, allowing to
 extend Doctrines Query capabilities to the vendors strength. This
-post explains the Used-Defined Functions API (UDF) of the Dql
+post explains the User-Defined Functions API (UDF) of the Dql
 Parser and shows some examples to give you some hints how you would
 extend DQL.
 
@@ -70,7 +70,7 @@ methods, which are quite handy in my opinion:
 Date Diff
 ---------
 
-`Mysql's DateDiff function <http://dev.mysql.com/doc/refman/5.1/en/date-and-time-functions.html#function_datediff>`_
+`Mysql's DateDiff function <https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_datediff>`_
 takes two dates as argument and calculates the difference in days
 with ``date1-date2``.
 
@@ -164,7 +164,7 @@ Date Add
 
 Often useful it the ability to do some simple date calculations in
 your DQL query using
-`MySql's DATE\_ADD function <http://dev.mysql.com/doc/refman/5.1/en/date-and-time-functions.html#function_date-add>`_.
+`MySql's DATE_ADD function <https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-add>`_.
 
 I'll skip the blah and show the code for this function:
 
@@ -246,6 +246,6 @@ vendor sql functions and extend the DQL languages scope.
 
 Code for this Extension to DQL and other Doctrine Extensions can be
 found
-`in my Github DoctrineExtensions repository <http://github.com/beberlei/DoctrineExtensions>`_.
+`in the GitHub DoctrineExtensions repository <http://github.com/beberlei/DoctrineExtensions>`_.
 
 

docs/en/cookbook/entities-in-session.rst

@@ -44,7 +44,7 @@ Serializing entity into the session
 -----------------------------------
 
 Entities that are serialized into the session normally contain references to
-other entities as well. Think of the user entity has a reference to his
+other entities as well. Think of the user entity has a reference to their
 articles, groups, photos or many other different entities. If you serialize
 this object into the session then you don't want to serialize the related
 entities as well. This is why you should call ``EntityManager#detach()`` on this

docs/en/cookbook/implementing-the-notify-changetracking-policy.rst

@@ -22,8 +22,8 @@ implement the ``NotifyPropertyChanged`` interface from the
 .. code-block:: php
 
     <?php
-    use Doctrine\Common\NotifyPropertyChanged;
-    use Doctrine\Common\PropertyChangedListener;
+    use Doctrine\Persistence\NotifyPropertyChanged;
+    use Doctrine\Persistence\PropertyChangedListener;
     
     abstract class DomainObject implements NotifyPropertyChanged
     {

docs/en/cookbook/implementing-wakeup-or-clone.rst

@@ -11,8 +11,8 @@ However, it is quite easy to make use of these methods in a safe
 way by guarding the custom wakeup or clone code with an entity
 identity check, as demonstrated in the following sections.
 
-Safely implementing \_\_wakeup
-------------------------------
+Safely implementing __wakeup
+----------------------------
 
 To safely implement ``__wakeup``, simply enclose your
 implementation code in an identity check as follows:
@@ -37,8 +37,8 @@ implementation code in an identity check as follows:
         //...
     }
 
-Safely implementing \_\_clone
------------------------------
+Safely implementing __clone
+---------------------------
 
 Safely implementing ``__clone`` is pretty much the same:
 

docs/en/cookbook/integrating-with-codeigniter.rst

@@ -1,140 +0,0 @@
-Integrating with CodeIgniter
-============================
-
-This is recipe for using Doctrine 2 in your
-`CodeIgniter <http://www.codeigniter.com>`_ framework.
-
-.. note::
-
-    This might not work for all CodeIgniter versions and may require
-    slight adjustments.
-
-
-Here is how to set it up:
-
-Make a CodeIgniter library that is both a wrapper and a bootstrap
-for Doctrine 2.
-
-Setting up the file structure
------------------------------
-
-Here are the steps:
-
-
--  Add a php file to your system/application/libraries folder
-   called Doctrine.php. This is going to be your wrapper/bootstrap for
-   the D2 entity manager.
--  Put the Doctrine folder (the one that contains Common, DBAL, and
-   ORM) inside that same libraries folder.
--  Your system/application/libraries folder now looks like this:
-
-   system/applications/libraries -Doctrine -Doctrine.php -index.html
-
--  If you want, open your config/autoload.php file and autoload
-   your Doctrine library.
-
-   <?php $autoload['libraries'] = array('doctrine');
-
-
-Creating your Doctrine CodeIgniter library
-------------------------------------------
-
-Now, here is what your Doctrine.php file should look like.
-Customize it to your needs.
-
-.. code-block:: php
-
-    <?php
-    use Doctrine\Common\ClassLoader,
-        Doctrine\ORM\Configuration,
-        Doctrine\ORM\EntityManager,
-        Doctrine\Common\Cache\ArrayCache,
-        Doctrine\DBAL\Logging\EchoSQLLogger;
-    
-    class Doctrine {
-    
-      public $em = null;
-    
-      public function __construct()
-      {
-        // load database configuration from CodeIgniter
-        require_once APPPATH.'config/database.php';
-    
-        // Set up class loading. You could use different autoloaders, provided by your favorite framework,
-        // if you want to.
-        require_once APPPATH.'libraries/Doctrine/Common/ClassLoader.php';
-    
-        $doctrineClassLoader = new ClassLoader('Doctrine',  APPPATH.'libraries');
-        $doctrineClassLoader->register();
-        $entitiesClassLoader = new ClassLoader('models', rtrim(APPPATH, "/" ));
-        $entitiesClassLoader->register();
-        $proxiesClassLoader = new ClassLoader('Proxies', APPPATH.'models/proxies');
-        $proxiesClassLoader->register();
-    
-        // Set up caches
-        $config = new Configuration;
-        $cache = new ArrayCache;
-        $config->setMetadataCacheImpl($cache);
-        $driverImpl = $config->newDefaultAnnotationDriver(array(APPPATH.'models/Entities'));
-        $config->setMetadataDriverImpl($driverImpl);
-        $config->setQueryCacheImpl($cache);
-
-        $config->setQueryCacheImpl($cache);
-    
-        // Proxy configuration
-        $config->setProxyDir(APPPATH.'/models/proxies');
-        $config->setProxyNamespace('Proxies');
-    
-        // Set up logger
-        $logger = new EchoSQLLogger;
-        $config->setSQLLogger($logger);
-    
-        $config->setAutoGenerateProxyClasses( TRUE );
-    
-        // Database connection information
-        $connectionOptions = array(
-            'driver' => 'pdo_mysql',
-            'user' =>     $db['default']['username'],
-            'password' => $db['default']['password'],
-            'host' =>     $db['default']['hostname'],
-            'dbname' =>   $db['default']['database']
-        );
-    
-        // Create EntityManager
-        $this->em = EntityManager::create($connectionOptions, $config);
-      }
-    }
-
-Please note that this is a development configuration; for a
-production system you'll want to use a real caching system like
-APC, get rid of EchoSqlLogger, and turn off
-autoGenerateProxyClasses.
-
-For more details, consult the
-`Doctrine 2 Configuration documentation <http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/configuration.html>`_.
-
-Now to use it
--------------
-
-Whenever you need a reference to the entity manager inside one of
-your controllers, views, or models you can do this:
-
-.. code-block:: php
-
-    <?php
-    $em = $this->doctrine->em;
-
-That's all there is to it. Once you get the reference to your
-EntityManager do your Doctrine 2.0 voodoo as normal.
-
-Note: If you do not choose to autoload the Doctrine library, you
-will need to put this line before you get a reference to it:
-
-.. code-block:: php
-
-    <?php
-    $this->load->library('doctrine');
-
-Good luck!
-
-

docs/en/cookbook/strategy-cookbook-introduction.rst

@@ -3,7 +3,7 @@ Strategy-Pattern
 
 This recipe will give you a short introduction on how to design
 similar entities without using expensive (i.e. slow) inheritance
-but with not more than \* the well-known strategy pattern \* event
+but with not more than *the well-known strategy pattern* event
 listeners
 
 Scenario / Problem

docs/en/cookbook/validation-of-entities.rst

@@ -25,8 +25,8 @@ the additional benefit of being able to re-use your validation in
 any other part of your domain.
 
 Say we have an ``Order`` with several ``OrderLine`` instances. We
-never want to allow any customer to order for a larger sum than he
-is allowed to:
+never want to allow any customer to order for a larger sum than they
+are allowed to:
 
 .. code-block:: php
 
@@ -134,4 +134,4 @@ instances. This was already discussed in the previous blog post on
 the Versionable extension, which requires another type of event
 called "onFlush".
 
-Further readings: :doc:`Lifecycle Events <../reference/events>`
+Further readings: :ref:`reference-events-lifecycle-events`

docs/en/cookbook/working-with-datetime.rst

@@ -1,7 +1,7 @@
 Working with DateTime Instances
 ===============================
 
-There are many nitty gritty details when working with PHPs DateTime instances. You have know their inner
+There are many nitty gritty details when working with PHPs DateTime instances. You have to know their inner
 workings pretty well not to make mistakes with date handling. This cookbook entry holds several
 interesting pieces of information on how to work with PHP DateTime instances in Doctrine 2.
 
@@ -90,7 +90,10 @@ the UTC time at the time of the booking and the timezone the event happened in.
 
     class UTCDateTimeType extends DateTimeType
     {
-        static private $utc;
+        /**
+         * @var \DateTimeZone
+         */
+        private static $utc;
 
         public function convertToDatabaseValue($value, AbstractPlatform $platform)
         {
@@ -110,7 +113,7 @@ the UTC time at the time of the booking and the timezone the event happened in.
             $converted = \DateTime::createFromFormat(
                 $platform->getDateTimeFormatString(),
                 $value,
-                self::$utc ? self::$utc : self::$utc = new \DateTimeZone('UTC')
+                self::getUtc()
             );
 
             if (! $converted) {
@@ -123,6 +126,11 @@ the UTC time at the time of the booking and the timezone the event happened in.
 
             return $converted;
         }
+        
+        private static function getUtc(): \DateTimeZone
+        {
+            return self::$utc ?: self::$utc = new \DateTimeZone('UTC');
+        }
     }
 
 This database type makes sure that every DateTime instance is always saved in UTC, relative

docs/en/index.rst

@@ -13,11 +13,11 @@ If this documentation is not helping to answer questions you have about
 Doctrine ORM don't panic. You can get help from different sources:
 
 -  There is a :doc:`FAQ <reference/faq>` with answers to frequent questions.
--  The `Doctrine Mailing List <http://groups.google.com/group/doctrine-user>`_
--  Internet Relay Chat (IRC) in #doctrine on Freenode
--  Report a bug on `JIRA <http://www.doctrine-project.org/jira>`_.
+-  The `Doctrine Mailing List <https://groups.google.com/group/doctrine-user>`_
+-  Slack chat room `#orm <https://www.doctrine-project.org/slack>`_
+-  Report a bug on `GitHub <https://github.com/doctrine/orm/issues>`_.
 -  On `Twitter <https://twitter.com/search/%23doctrine2>`_ with ``#doctrine2``
--  On `StackOverflow <http://stackoverflow.com/questions/tagged/doctrine2>`_
+-  On `StackOverflow <https://stackoverflow.com/questions/tagged/doctrine-orm>`_
 
 If you need more structure over the different topics you can browse the :doc:`table
 of contents <toc>`.
@@ -72,9 +72,9 @@ Advanced Topics
 * :doc:`Transactions and Concurrency <reference/transactions-and-concurrency>`
 * :doc:`Filters <reference/filters>`
 * :doc:`NamingStrategy <reference/namingstrategy>`
-* :doc:`Improving Performance <reference/improving-performance>` 
-* :doc:`Caching <reference/caching>` 
-* :doc:`Partial Objects <reference/partial-objects>` 
+* :doc:`Improving Performance <reference/improving-performance>`
+* :doc:`Caching <reference/caching>`
+* :doc:`Partial Objects <reference/partial-objects>`
 * :doc:`Change Tracking Policies <reference/change-tracking-policies>`
 * :doc:`Best Practices <reference/best-practices>`
 * :doc:`Metadata Drivers <reference/metadata-drivers>`
@@ -95,7 +95,7 @@ Tutorials
 Changelogs
 ----------
 
-* :doc:`Migration to 2.5 <changelog/migration_2_5>`
+* `Upgrade <https://github.com/doctrine/doctrine2/blob/master/UPGRADE.md>`_
 
 Cookbook
 --------
@@ -103,7 +103,7 @@ Cookbook
 * **Patterns**:
   :doc:`Aggregate Fields <cookbook/aggregate-fields>` |
   :doc:`Decorator Pattern <cookbook/decorator-pattern>` |
-  :doc:`Strategy Pattern <cookbook/strategy-cookbook-introduction>` 
+  :doc:`Strategy Pattern <cookbook/strategy-cookbook-introduction>`
 
 * **DQL Extension Points**:
   :doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` |
@@ -118,9 +118,6 @@ Cookbook
   :doc:`Entities in the Session <cookbook/entities-in-session>` |
   :doc:`Keeping your Modules independent <cookbook/resolve-target-entity-listener>`
 
-* **Integration into Frameworks/Libraries**
-  :doc:`CodeIgniter <cookbook/integrating-with-codeigniter>`
-
 * **Hidden Gems**
   :doc:`Prefixing Table Name <cookbook/sql-table-prefixes>`
 

docs/en/make.bat

@@ -1,113 +1,113 @@
-@ECHO OFF
-
-REM Command file for Sphinx documentation
-
-set SPHINXBUILD=sphinx-build
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-if NOT "%PAPER%" == "" (
-	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
-)
-
-if "%1" == "" goto help
-
-if "%1" == "help" (
-	:help
-	echo.Please use `make ^<target^>` where ^<target^> is one of
-	echo.  html      to make standalone HTML files
-	echo.  dirhtml   to make HTML files named index.html in directories
-	echo.  pickle    to make pickle files
-	echo.  json      to make JSON files
-	echo.  htmlhelp  to make HTML files and a HTML help project
-	echo.  qthelp    to make HTML files and a qthelp project
-	echo.  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
-	echo.  changes   to make an overview over all changed/added/deprecated items
-	echo.  linkcheck to check all external links for integrity
-	echo.  doctest   to run all doctests embedded in the documentation if enabled
-	goto end
-)
-
-if "%1" == "clean" (
-	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
-	del /q /s %BUILDDIR%\*
-	goto end
-)
-
-if "%1" == "html" (
-	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	goto end
-)
-
-if "%1" == "dirhtml" (
-	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
-	goto end
-)
-
-if "%1" == "pickle" (
-	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
-	echo.
-	echo.Build finished; now you can process the pickle files.
-	goto end
-)
-
-if "%1" == "json" (
-	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
-	echo.
-	echo.Build finished; now you can process the JSON files.
-	goto end
-)
-
-if "%1" == "htmlhelp" (
-	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
-	echo.
-	echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in %BUILDDIR%/htmlhelp.
-	goto end
-)
-
-if "%1" == "qthelp" (
-	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
-	echo.
-	echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Doctrine2ORM.qhcp
-	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Doctrine2ORM.ghc
-	goto end
-)
-
-if "%1" == "latex" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	echo.
-	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "changes" (
-	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
-	echo.
-	echo.The overview file is in %BUILDDIR%/changes.
-	goto end
-)
-
-if "%1" == "linkcheck" (
-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
-	echo.
-	echo.Link check complete; look for any errors in the above output ^
-or in %BUILDDIR%/linkcheck/output.txt.
-	goto end
-)
-
-if "%1" == "doctest" (
-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
-	echo.
-	echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
-	goto end
-)
-
-:end
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+set SPHINXBUILD=sphinx-build
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html      to make standalone HTML files
+	echo.  dirhtml   to make HTML files named index.html in directories
+	echo.  pickle    to make pickle files
+	echo.  json      to make JSON files
+	echo.  htmlhelp  to make HTML files and a HTML help project
+	echo.  qthelp    to make HTML files and a qthelp project
+	echo.  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  changes   to make an overview over all changed/added/deprecated items
+	echo.  linkcheck to check all external links for integrity
+	echo.  doctest   to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Doctrine2ORM.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Doctrine2ORM.ghc
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end

docs/en/reference/advanced-configuration.rst

@@ -292,7 +292,7 @@ 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 <./../../../../../projects/doctrine-dbal/en/latest/reference/configuration.html>`_.
+`DBAL section <https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/configuration.html>`_.
 
 Proxy Objects
 -------------

docs/en/reference/annotations-reference.rst

@@ -99,7 +99,7 @@ Optional attributes:
 
 -  **length**: Used by the "string" type to determine its maximum
    length in the database. Doctrine does not validate the length of a
-   string values for you.
+   string value for you.
 
 -  **precision**: The precision for a decimal (exact numeric) column
    (applies only for decimal column), which is the maximum number of
@@ -181,7 +181,7 @@ Examples:
     protected $initials;
 
     /**
-     * @Column(type="integer", name="login_count" nullable=false, options={"unsigned":true, "default":0})
+     * @Column(type="integer", name="login_count", nullable=false, options={"unsigned":true, "default":0})
      */
     protected $loginCount;
 
@@ -619,22 +619,17 @@ Examples:
 This annotation is used in the context of relations in
 :ref:`@ManyToOne <annref_manytoone>`, :ref:`@OneToOne <annref_onetoone>` fields
 and in the Context of :ref:`@JoinTable <annref_jointable>` nested inside
-a @ManyToMany. This annotation is not required. If it is not
-specified the attributes *name* and *referencedColumnName* are
-inferred from the table and primary key names.
-
-Required attributes:
+a @ManyToMany. If this annotation or both *name* and *referencedColumnName*
+are missing they will be computed considering the field's name and the current
+:doc:`naming strategy <namingstrategy>`.
 
+Optional attributes:
 
 -  **name**: Column name that holds the foreign key identifier for
    this relation. In the context of @JoinTable it specifies the column
    name in the join table.
 -  **referencedColumnName**: Name of the primary key identifier that
-   is used for joining of this relation.
-
-Optional attributes:
-
-
+   is used for joining of this relation. Defaults to *id*.
 -  **unique**: Determines whether this relation is exclusive between the
    affected entities and should be enforced as such on the database
    constraint level. Defaults to false.

docs/en/reference/architecture.rst

@@ -18,7 +18,7 @@ well.
 Requirements
 ------------
 
-Doctrine 2 requires a minimum of PHP 5.4. For greatly improved
+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

docs/en/reference/association-mapping.rst

@@ -18,9 +18,9 @@ This chapter is split into three different sections.
 
 One tip for working with relations is to read the relation from left to right, where the left word refers to the current Entity. For example:
 
-- OneToMany - One instance of the current Entity has Many instances (references) to the refered Entity.
-- ManyToOne - Many instances of the current Entity refer to One instance of the refered Entity.
-- OneToOne - One instance of the current Entity refers to One instance of the refered Entity.
+- OneToMany - One instance of the current Entity has Many instances (references) to the referred Entity.
+- ManyToOne - Many instances of the current Entity refer to One instance of the referred Entity.
+- OneToOne - One instance of the current Entity refers to One instance of the referred Entity.
 
 See below for all the possible relations. 
 
@@ -286,7 +286,7 @@ below.
         // ...
 
         /**
-         * One Student has One Student.
+         * One Student has One Mentor.
          * @OneToOne(targetEntity="Student")
          * @JoinColumn(name="mentor_id", referencedColumnName="id")
          */
@@ -313,8 +313,8 @@ One-To-Many, Bidirectional
 --------------------------
 
 A one-to-many association has to be bidirectional, unless you are using a
-join table. This is because the many side in a one-to-many association holds
-the foreign key, making it the owning side. Doctrine needs the many side
+join table. This is because the "many" side in a one-to-many association holds
+the foreign key, making it the owning side. Doctrine needs the "many" side
 defined in order to understand the association.
 
 This bidirectional mapping requires the ``mappedBy`` attribute on the
@@ -335,7 +335,7 @@ bidirectional many-to-one.
         {
             // ...
             /**
-             * One Product has Many Features.
+             * One product has many features. This is the inverse side.
              * @OneToMany(targetEntity="Feature", mappedBy="product")
              */
             private $features;
@@ -351,7 +351,7 @@ bidirectional many-to-one.
         {
             // ...
             /**
-             * Many Features have One Product.
+             * Many features have one product. This is the owning side.
              * @ManyToOne(targetEntity="Product", inversedBy="features")
              * @JoinColumn(name="product_id", referencedColumnName="id")
              */

docs/en/reference/basic-mapping.rst

@@ -270,7 +270,7 @@ A cookbook article shows how to define :doc:`your own custom mapping types
 .. warning::
 
     All Date types assume that you are exclusively using the default timezone
-    set by `date_default_timezone_set() <http://docs.php.net/manual/en/function.date-default-timezone-set.php>`_
+    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.
 
@@ -328,8 +328,8 @@ annotation.
 
 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, SERIAL with PostgreSQL,
-Sequences with Oracle and so on.
+database vendor prefers: AUTO_INCREMENT with MySQL, sequences with PostgreSQL 
+and Oracle and so on.
 
 Identifier Generation Strategies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/en/reference/batch-processing.rst

@@ -16,6 +16,15 @@ especially what the strategies presented here provide help with.
     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
 ------------
 
@@ -75,7 +84,7 @@ with the batching strategy that was already used for bulk inserts:
 
     <?php
     $batchSize = 20;
-    $i = 0;
+    $i = 1;
     $q = $em->createQuery('select u from MyProject\Model\User u');
     $iterableResult = $q->iterate();
     foreach ($iterableResult as $row) {
@@ -136,7 +145,7 @@ The following example shows how to do this:
 
     <?php
     $batchSize = 20;
-    $i = 0;
+    $i = 1;
     $q = $em->createQuery('select u from MyProject\Model\User u');
     $iterableResult = $q->iterate();
     while (($row = $iterableResult->next()) !== false) {

docs/en/reference/caching.rst

@@ -1,8 +1,8 @@
 Caching
 =======
 
-Doctrine provides cache drivers in the ``Common`` package for some
-of the most popular caching implementations such as APC, Memcache
+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 
@@ -29,10 +29,10 @@ abstract protected methods that each of the drivers must
 implement:
 
 
--  \_doFetch($id)
--  \_doContains($id)
--  \_doSave($id, $data, $lifeTime = false)
--  \_doDelete($id)
+-  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
@@ -43,43 +43,31 @@ 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>`.
+`cache directory on GitHub <https://github.com/doctrine/cache/tree/master/lib/Doctrine/Common/Cache>`_.
 
-APC
-~~~
+PhpFileCache
+~~~~~~~~~~~~
 
-In order to use the APC cache driver you must have it compiled and
-enabled in your php.ini. You can read about APC
-`in the PHP Documentation <http://us2.php.net/apc>`_. 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.
+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.
 
-Below is a simple example of how you could use the APC cache driver
-by itself.
+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\ApcCache();
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
+        '/path/to/writable/directory'
+    );
     $cacheDriver->save('cache_id', 'my_data');
 
-APCu
-~~~~
-
-In order to use the APCu cache driver you must have it compiled and
-enabled in your php.ini. You can read about APCu
-`in the PHP Documentation <http://us2.php.net/apcu>`_. 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 APCu cache driver
-by itself.
-
-.. code-block:: php
-
-    <?php
-    $cacheDriver = new \Doctrine\Common\Cache\ApcuCache();
-    $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
 ~~~~~~~~
@@ -128,24 +116,6 @@ driver by itself.
     $cacheDriver->setMemcached($memcached);
     $cacheDriver->save('cache_id', 'my_data');
 
-Xcache
-~~~~~~
-
-In order to use the Xcache cache driver you must have it compiled
-and enabled in your php.ini. You can read about Xcache
-`here <http://xcache.lighttpd.net/>`_. 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 Xcache cache
-driver by itself.
-
-.. code-block:: php
-
-    <?php
-    $cacheDriver = new \Doctrine\Common\Cache\XcacheCache();
-    $cacheDriver->save('cache_id', 'my_data');
-
 Redis
 ~~~~~
 
@@ -282,6 +252,8 @@ You can set the namespace a cache driver should use by using the
     <?php
     $cacheDriver->setNamespace('my_namespace_');
 
+.. _integrating-with-the-orm:
+
 Integrating with the ORM
 ------------------------
 
@@ -304,8 +276,11 @@ 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(new \Doctrine\Common\Cache\ApcuCache());
+    $config->setQueryCacheImpl($cacheDriver);
 
 Result Cache
 ~~~~~~~~~~~~
@@ -318,7 +293,11 @@ cache implementation.
 .. code-block:: php
 
     <?php
-    $config->setResultCacheImpl(new \Doctrine\Common\Cache\ApcuCache());
+    $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.
@@ -327,7 +306,7 @@ the result cache.
 
     <?php
     $query = $em->createQuery('select u from \Entities\User u');
-    $query->useResultCache(true);
+    $query->enableResultCache();
 
 You can also configure an individual query to use a different
 result cache driver.
@@ -335,18 +314,21 @@ result cache driver.
 .. code-block:: php
 
     <?php
-    $query->setResultCacheDriver(new \Doctrine\Common\Cache\ApcuCache());
+    $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 pass false to ``useResultCache()``.
+    disable it use ``disableResultCache()``.
 
     ::
 
         <?php
-        $query->useResultCache(false);
+        $query->disableResultCache();
 
 
 If you want to set the time the cache has to live you can use the
@@ -367,12 +349,12 @@ yourself with the ``setResultCacheId()`` method.
     $query->setResultCacheId('my_custom_id');
 
 You can also set the lifetime and cache ID by passing the values as
-the second and third argument to ``useResultCache()``.
+the first and second argument to ``enableResultCache()``.
 
 .. code-block:: php
 
     <?php
-    $query->useResultCache(true, 3600, 'my_custom_id');
+    $query->enableResultCache(3600, 'my_custom_id');
 
 Metadata Cache
 ~~~~~~~~~~~~~~
@@ -387,7 +369,11 @@ first.
 .. code-block:: php
 
     <?php
-    $config->setMetadataCacheImpl(new \Doctrine\Common\Cache\ApcuCache());
+    $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.
@@ -423,6 +409,12 @@ To clear the result cache use the ``orm:clear-cache:result`` task.
 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
 --------------
 

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

@@ -71,8 +71,8 @@ follows:
 .. code-block:: php
 
     <?php
-    use Doctrine\Common\NotifyPropertyChanged,
-        Doctrine\Common\PropertyChangedListener;
+    use Doctrine\Persistence\NotifyPropertyChanged,
+        Doctrine\Persistence\PropertyChangedListener;
     
     /**
      * @Entity

docs/en/reference/configuration.rst

@@ -1,9 +1,7 @@
 Installation and Configuration
 ==============================
 
-Doctrine can be installed with `Composer <http://www.getcomposer.org>`_.  For
-older versions we still have `PEAR packages
-<http://pear.doctrine-project.org>`_.
+Doctrine can be installed with `Composer <https://getcomposer.org>`_.
 
 Define the following requirement in your ``composer.json`` file:
 
@@ -16,8 +14,7 @@ Define the following requirement in your ``composer.json`` file:
     }
 
 Then call ``composer install`` from your command line. If you don't know
-how Composer works, check out their `Getting Started
-<http://getcomposer.org/doc/00-intro.md>`_ to set up.
+how Composer works, check out their `Getting Started <https://getcomposer.org/doc/00-intro.md>`_ to set up.
 
 Class loading
 -------------
@@ -93,8 +90,7 @@ Inside the ``Setup`` methods several assumptions are made:
 -  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.
+If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration <reference/advanced-configuration>` section.
 
 .. note::
 

docs/en/reference/dql-doctrine-query-language.rst

@@ -103,15 +103,15 @@ their inclusion in the SELECT clause.
 
 In this case, the result will be an array of arrays.  In the example
 above, each element of the result array would be an array of the
-scalar name and address values. 
+scalar name and address values.
 
-You can select scalars from any entity in the query. 
+You can select scalars from any entity in the query.
 
 **Mixed**
 
 .. code-block:: sql
 
-    ``SELECT u, p.quantity FROM Users u...``
+    SELECT u, p.quantity FROM Users u...
 
 Here, the result will again be an array of arrays, with each element
 being an array made up of a User object and the scalar value
@@ -250,7 +250,7 @@ Retrieve the Username and Name of a CmsUser:
     $users = $query->getResult(); // array of CmsUser username and name values
     echo $users[0]['username'];
 
-Retrieve a ForumUser and his single associated entity:
+Retrieve a ForumUser and its single associated entity:
 
 .. code-block:: php
 
@@ -259,7 +259,7 @@ Retrieve a ForumUser and his single associated entity:
     $users = $query->getResult(); // array of ForumUser objects with the avatar association loaded
     echo get_class($users[0]->getAvatar());
 
-Retrieve a CmsUser and fetch join all the phonenumbers he has:
+Retrieve a CmsUser and fetch join all the phonenumbers it has:
 
 .. code-block:: php
 
@@ -491,7 +491,7 @@ Joins between entities without associations were not possible until version
 .. code-block:: php
 
     <?php
-    $query = $em->createQuery('SELECT u FROM User u JOIN Blacklist b WITH u.email = b.email');
+    $query = $em->createQuery('SELECT u FROM User u JOIN Banlist b WITH u.email = b.email');
 
 .. note::
     The differences between WHERE, WITH and HAVING clauses may be
@@ -691,8 +691,8 @@ clauses:
 -  TRIM([LEADING \| TRAILING \| BOTH] ['trchar' FROM] str) - Trim
    the string by the given trim char, defaults to whitespaces.
 -  UPPER(str) - Return the upper-case of the given string.
--  DATE_ADD(date, days, unit) - Add the number of days to a given date. (Supported units are DAY, MONTH)
--  DATE_SUB(date, days, unit) - Substract the number of days from a given date. (Supported units are DAY, MONTH)
+-  DATE_ADD(date, value, unit) - Add the given time to a given date. (Supported units are SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR)
+-  DATE_SUB(date, value, unit) - Subtract the given time from a given date. (Supported units are SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR)
 -  DATE_DIFF(date1, date2) - Calculate the difference in days between date1-date2.
 
 Arithmetic operators
@@ -996,8 +996,9 @@ the Query class. Here they are:
    result contains more than one object, an ``NonUniqueResultException``
    is thrown. If the result contains no objects, an ``NoResultException``
    is thrown. The pure/mixed distinction does not apply.
--  ``Query#getOneOrNullResult()``: Retrieve a single object. If no
-   object is found null will be returned.
+-  ``Query#getOneOrNullResult()``: Retrieve a single object. If the
+   result contains more than one object, a ``NonUniqueResultException``
+   is thrown. If no object is found null will be returned.
 -  ``Query#getArrayResult()``: Retrieves an array graph (a nested
    array) that is largely interchangeable with the object graph
    generated by ``Query#getResult()`` for read-only purposes.
@@ -1172,7 +1173,7 @@ why we are listing as many of the assumptions here for reference:
 - If an object is already in memory from a previous query of any kind, then
   then the previous object is used, even if the database may contain more
   recent data. Data from the database is discarded. This even happens if the
-  previous object is still an unloaded proxy. 
+  previous object is still an unloaded proxy.
 
 This list might be incomplete.
 
@@ -1452,10 +1453,10 @@ Given that there are 10 users and corresponding addresses in the database the ex
     SELECT * FROM address WHERE id IN (1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
 
 .. note::
-    Changing the fetch mode during a query mostly makes sense for one-to-one and many-to-one relations. In that case, 
+    Changing the fetch mode during a query mostly makes sense for one-to-one and many-to-one relations. In that case,
     all the necessary IDs are available after the root entity (``user`` in the above example) has been loaded. So, one
     query per association can be executed to fetch all the referred-to entities (``address``).
-    
+
     For one-to-many relations, changing the fetch mode to eager will cause to execute one query **for every root entity
     loaded**. This gives no improvement over the ``lazy`` fetch mode which will also initialize the associations on
     a one-by-one basis once they are accessed.

docs/en/reference/events.rst

@@ -145,49 +145,53 @@ An example for a correct notation can be found in the example
 Lifecycle Events
 ----------------
 
-The EntityManager and UnitOfWork trigger a bunch of events during
-the life-time of their registered entities.
+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
+
+-  ``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
+   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
+-  ``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
+-  ``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
+-  ``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
+-  ``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
+-  ``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
+-  ``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.
+-  ``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::
 
@@ -199,7 +203,7 @@ the life-time of their registered entities.
 
 .. warning::
 
-    Note that the postRemove event or any events triggered after an entity removal
+    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.
@@ -222,13 +226,13 @@ listeners:
 -  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 and other relevant data.
+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
+    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.
@@ -243,6 +247,11 @@ 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
@@ -323,7 +332,7 @@ XML would look something like this:
     <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
-                              /Users/robo/dev/php/Doctrine/doctrine-mapping.xsd">
+                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
         <entity name="User">
 
@@ -405,9 +414,9 @@ 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. Please read the
-:ref:`reference-events-implementing-listeners` section carefully if you
-are trying to write your own listener.
+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
@@ -418,7 +427,7 @@ A lifecycle event listener looks like the following:
 .. code-block:: php
 
     <?php
-    use Doctrine\Common\Persistence\Event\LifecycleEventArgs;
+    use Doctrine\Persistence\Event\LifecycleEventArgs;
 
     class MyEventListener
     {
@@ -440,8 +449,8 @@ A lifecycle event subscriber may look like this:
 
     <?php
     use Doctrine\ORM\Events;
-    use Doctrine\Common\EventSubscriber;
-    use Doctrine\Common\Persistence\Event\LifecycleEventArgs;
+    use Doctrine\EventSubscriber;
+    use Doctrine\Persistence\Event\LifecycleEventArgs;
 
     class MyEventSubscriber implements EventSubscriber
     {
@@ -496,16 +505,16 @@ Implementing Event Listeners
 ----------------------------
 
 This section explains what is and what is not allowed during
-specific lifecycle events of the UnitOfWork. Although you get
-passed the EntityManager 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
+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.
+``EntityManager`` or ``UnitOfWork`` APIs inside these events.
 
 prePersist
 ~~~~~~~~~~
@@ -548,8 +557,9 @@ preFlush
 ~~~~~~~~
 
 ``preFlush`` is called at ``EntityManager#flush()`` before
-anything else. ``EntityManager#flush()`` can be called safely
-inside its listeners.
+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
 
@@ -580,8 +590,8 @@ entities and their associations have been computed. This means, the
 -  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
+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
@@ -729,7 +739,7 @@ Restrictions for this event:
    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
+   ``EntityManager#remove()``, even in combination with the ``UnitOfWork``
    API are strongly discouraged and don't work as expected outside the
    flush operation.
 
@@ -985,4 +995,3 @@ process and manipulate the instance.
         }
     }
 
-

docs/en/reference/faq.rst

@@ -21,12 +21,6 @@ created database tables and columns.
 Entity Classes
 --------------
 
-I access a variable and its null, what is wrong?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If this variable is a public variable then you are violating one of the criteria for entities.
-All properties have to be protected or private for the proxy object pattern to work.
-
 How can I add default values to a column?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -204,6 +198,21 @@ No, it is not supported to sort by function in DQL. If you need this functionali
 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?
 ----------------------------------
 

docs/en/reference/filters.rst

@@ -39,7 +39,7 @@ proper quoting of parameters.
 
     <?php
     namespace Example;
-    use Doctrine\ORM\Mapping\ClassMetaData,
+    use Doctrine\ORM\Mapping\ClassMetadata,
         Doctrine\ORM\Query\Filter\SQLFilter;
 
     class MyLocaleFilter extends SQLFilter

docs/en/reference/improving-performance.rst

@@ -4,7 +4,7 @@ Improving Performance
 Bytecode Cache
 --------------
 
-It is highly recommended to make use of a bytecode cache like APC.
+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.
 
@@ -20,12 +20,19 @@ 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 (preferably with APC or Memcache as the
-cache driver). Operating Doctrine without these caches means
+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
 --------------------------------
 
@@ -42,6 +49,8 @@ for updates, which means when you call flush on the EntityManager these entities
 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
 ----------------------
 
@@ -52,7 +61,7 @@ for more information on how this fetch mode works.
 Temporarily change fetch mode in DQL
 ------------------------------------
 
-See :ref:`Doctrine Query Language chapter <dql-temporarily-change-fetch-mode>`
+See :ref:`dql-temporarily-change-fetch-mode`
 
 
 Apply Best Practices
@@ -61,6 +70,7 @@ 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
 ------------------------

docs/en/reference/inheritance-mapping.rst

@@ -174,7 +174,7 @@ 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 allows
+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.
 
@@ -289,9 +289,15 @@ column and cascading on delete.
 
 Overrides
 ---------
-Used to override a mapping for an entity field or relationship.
-May be applied to an entity that extends a mapped superclass
-to override a relationship or field mapping defined by the mapped superclass.
+
+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
@@ -493,7 +499,7 @@ Could be used by an entity that extends a mapped superclass to override a field
          *          column=@Column(
          *              name     = "guest_id",
          *              type     = "integer",
-                        length   = 140
+         *              length   = 140
          *          )
          *      ),
          *      @AttributeOverride(name="name",
@@ -501,7 +507,7 @@ Could be used by an entity that extends a mapped superclass to override a field
          *              name     = "guest_name",
          *              nullable = false,
          *              unique   = true,
-                        length   = 240
+         *              length   = 240
          *          )
          *      )
          * })
@@ -584,7 +590,7 @@ 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 columns except the type.
+-  The override can redefine all the attributes except the type.
 
 Query the Type
 --------------

docs/en/reference/installation.rst

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

docs/en/reference/limitations-and-known-issues.rst

@@ -63,7 +63,7 @@ Where the ``attribute_name`` column contains the key and
 ``$attributes``.
 
 The feature request for persistence of primitive value arrays
-`is described in the DDC-298 ticket <http://www.doctrine-project.org/jira/browse/DDC-298>`_.
+`is described in the DDC-298 ticket <https://github.com/doctrine/orm/issues/3743>`_.
 
 Cascade Merge with Bi-directional Associations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -71,8 +71,8 @@ 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 <http://www.doctrine-project.org/jira/browse/DDC-875>`_ Merge can sometimes add the same entity twice into a collection
--  `DDC-763 <http://www.doctrine-project.org/jira/browse/DDC-763>`_ Cascade merge on associated entities can insert too many rows through "Persistence by Reachability"
+-  `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
 ~~~~~~~~~~~~~~~~~
@@ -83,8 +83,8 @@ 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 <http://www.doctrine-project.org/jira/browse/DDC-668>`_
--  `Evaluate possible ways in which stored-procedures can be used <http://www.doctrine-project.org/jira/browse/DDC-445>`_
+-  `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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -94,7 +94,7 @@ PHP Arrays are ordered hash-maps and so should be the
 evaluate a feature that optionally persists and hydrates the keys
 of a Collection instance.
 
-`Ticket DDC-213 <http://www.doctrine-project.org/jira/browse/DDC-213>`_
+`Ticket DDC-213 <https://github.com/doctrine/orm/issues/2817>`_
 
 Mapping many tables to one entity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -116,7 +116,6 @@ blog posts we have written on this topics:
 -  `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>`_
--  `Doctrator <https://github.com/pablodip/doctrator`>_
 
 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
@@ -144,9 +143,7 @@ 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 the Open Bugs on Jira for more details on `bugs, improvement and feature
-requests
-<http://www.doctrine-project.org/jira/secure/IssueNavigator.jspa?reset=true&mode=hide&pid=10032&resolution=-1&sorter/field=updated&sorter/order=DESC>`_.
+See bugs, improvement and feature requests on `Github issues <https://github.com/doctrine/orm/issues>`_.
 
 Identifier Quoting and Legacy Databases
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/en/reference/namingstrategy.rst

@@ -4,9 +4,13 @@ Implementing a NamingStrategy
 .. versionadded:: 2.3
 
 Using a naming strategy you can provide rules for generating database identifiers,
-column or table names when the column or table name is not given. This feature helps
+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.

docs/en/reference/native-sql.rst

@@ -92,7 +92,7 @@ a mapping from DQL alias (key) to SQL alias (value)
 
     <?php
 
-    $selectClause = $builder->generateSelectClause(array(
+    $selectClause = $rsm->generateSelectClause(array(
         'u' => 't1',
         'g' => 't2'
     ));

docs/en/reference/query-builder.rst

@@ -9,6 +9,12 @@ 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -80,7 +86,7 @@ Working with QueryBuilder
 High level API methods
 ^^^^^^^^^^^^^^^^^^^^^^
 
-To simplify even more the way you build a query in Doctrine, you can take
+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
@@ -97,10 +103,9 @@ to work with them, here is the same example 6 re-written using
        ->orderBy('u.name', 'ASC');
 
 ``QueryBuilder`` helper methods are considered the standard way to
-build DQL queries. Although it is supported, using string-based
-queries should be avoided.  You are greatly encouraged to use
-``$qb->expr()->*`` methods. Here is a converted example 8 to
-suggested standard way to build queries:
+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
 
@@ -250,6 +255,21 @@ 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:
@@ -502,7 +522,7 @@ complete list of supported helper methods available:
 Adding a Criteria to a Query
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can also add a :ref:`Criteria <filtering-collections>` to a QueryBuilder by
+You can also add a :ref:`filtering-collections` to a QueryBuilder by
 using ``addCriteria``:
 
 .. code-block:: php
@@ -576,4 +596,3 @@ same query of example 6 written using
       ->add('from', new Expr\From('User', 'u'))
       ->add('where', new Expr\Comparison('u.id', '=', '?1'))
       ->add('orderBy', new Expr\OrderBy('u.name', 'ASC'));
-

docs/en/reference/second-level-cache.rst

@@ -77,11 +77,10 @@ A query region might be something like :
 Cache Regions
 -------------
 
-``Doctrine\ORM\Cache\Region\DefaultRegion`` It's the default implementation.
+``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``
-Defines contracts that should be implemented by a cache provider.
+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.
 
@@ -91,13 +90,10 @@ If you want to support locking for ``READ_WRITE`` strategies you should implemen
 Cache region
 ~~~~~~~~~~~~
 
-Defines a contract for accessing a particular region.
+``Doctrine\ORM\Cache\Region`` defines a contract for accessing a particular
+cache region.
 
-``Doctrine\ORM\Cache\Region``
-
-Defines a contract for accessing a particular cache region.
-
-`See API Doc <http://www.doctrine-project.org/api/orm/2.5/class-Doctrine.ORM.Cache.Region.html>`_.
+`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/Region.html>`_.
 
 Concurrent cache region
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -107,11 +103,9 @@ By default, Doctrine provides a very simple implementation based on file locks `
 
 If you want to use an ``READ_WRITE`` cache, you should consider providing your own cache region.
 
-``Doctrine\ORM\Cache\ConcurrentRegion``
+``Doctrine\ORM\Cache\ConcurrentRegion`` defines a contract for concurrently managed data region.
 
-Defines contract for concurrently managed data region.
-
-`See API Doc <http://www.doctrine-project.org/api/orm/2.5/class-Doctrine.ORM.Cache.ConcurrentRegion.html>`_.
+`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/ConcurrentRegion.html>`_.
 
 Timestamp region
 ~~~~~~~~~~~~~~~~
@@ -120,7 +114,7 @@ Timestamp region
 
 Tracks the timestamps of the most recent updates to particular entity.
 
-`See API Doc <http://www.doctrine-project.org/api/orm/2.5/class-Doctrine.ORM.Cache.TimestampRegion.html>`_.
+`See API Doc <http://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/TimestampRegion.html>`_.
 
 .. _reference-second-level-cache-mode:
 
@@ -177,7 +171,7 @@ Doctrine allows you to specify configurations and some points of extension for t
 Enable Second Level Cache
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To enable the second-level-cache, you should provide a cache factory
+To enable the second-level-cache, you should provide a cache factory.
 ``\Doctrine\ORM\Cache\DefaultCacheFactory`` is the default implementation.
 
 .. code-block:: php
@@ -203,13 +197,18 @@ Cache Factory is the main point of extension.
 
 It allows you to provide a specific implementation of the following components :
 
-* ``QueryCache`` Store and retrieve query cache results.
-* ``CachedEntityPersister`` Store and retrieve entity results.
-* ``CachedCollectionPersister`` Store and retrieve query results.
-* ``EntityHydrator``  Transform an entity into a cache entry and cache entry into entities
-* ``CollectionHydrator`` Transform a collection into a cache entry and cache entry into collection
+``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/2.5/class-Doctrine.ORM.Cache.DefaultCacheFactory.html>`_.
+`See API Doc <http://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/DefaultCacheFactory.html>`_.
 
 Region Lifetime
 ~~~~~~~~~~~~~~~
@@ -225,8 +224,8 @@ To specify a default lifetime for all regions or specify a different lifetime fo
     $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
+    $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
@@ -267,18 +266,22 @@ By providing a cache logger you should be able to get information about all cach
     // 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 information you want.
+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/2.5/class-Doctrine.ORM.Cache.CacheLogger.html>`_.
+`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`` Optional value that specifies the name of the second level cache region.
+  * ``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::
@@ -310,7 +313,7 @@ Entity cache definition
     .. 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 http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <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">
@@ -386,7 +389,7 @@ It caches the primary keys of association and cache each element will be cached
     .. 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 http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <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" />
@@ -579,7 +582,8 @@ The Cache Mode controls how a particular query interacts with the second-level c
 DELETE / UPDATE queries
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-DQL UPDATE / DELETE statements are ported directly into a database and bypass the second-level cache,
+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.
 
@@ -622,7 +626,7 @@ Using the repository query cache
 --------------------------------
 
 As well as ``Query Cache`` all persister queries store only identifier values for an individual query.
-All persister use a single timestamps cache region keeps track of the last update for each persister,
+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.
 
@@ -641,7 +645,7 @@ Using the last update timestamps as part of the query key invalidate the cache k
     $em->clear();
 
     // Reload from database.
-    // At this point the query cache key if not logger valid, the select goes straight
+    // 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
@@ -728,4 +732,5 @@ 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.
+Although entities and query result are cached, count queries will hit the
+database every time.

docs/en/reference/security.rst

@@ -10,7 +10,7 @@ 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](https://github.com/doctrine/dbal/blob/master/docs/en/reference/security.rst)
+- `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
@@ -119,7 +119,7 @@ entity might look like this:
     }
 
 Now the possiblity of mass-asignment exists on this entity and can
-be exploitet by attackers to set the "isAdmin" flag to true on any
+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

docs/en/reference/tools.rst

@@ -252,15 +252,6 @@ will output the SQL for the ran operation.
 Before using the orm:schema-tool commands, remember to configure
 your cli-config.php properly.
 
-.. note::
-
-    When using the Annotation Mapping Driver you have to either setup
-    your autoloader in the cli-config.php correctly to find all the
-    entities, or you can use the second argument of the
-    ``EntityManagerHelper`` to specify all the paths of your entities
-    (or mapping files), i.e.
-    ``new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($em, $mappingPaths);``
-
 Entity Generation
 -----------------
 

docs/en/reference/unitofwork-associations.rst

@@ -39,7 +39,7 @@ 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 his responsibility). Doctrine needs to know which of these
+(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.

docs/en/reference/unitofwork.rst

@@ -148,15 +148,15 @@ 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 he
-wishes to be hydrated. Default result-types include:
+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 most complex parts of Doctrine
+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

docs/en/reference/working-with-associations.rst

@@ -15,7 +15,7 @@ with associations in Doctrine:
    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 assocation is updated, Doctrine only checks
+-  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
@@ -716,6 +716,7 @@ methods:
 * ``in($field, array $values)``
 * ``notIn($field, array $values)``
 * ``contains($field, $value)``
+* ``memberOf($value, $field)``
 * ``startsWith($field, $value)``
 * ``endsWith($field, $value)``
 

docs/en/reference/working-with-objects.rst

@@ -25,6 +25,13 @@ Work that have not yet been persisted are lost.
     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
 -----------------------------
@@ -238,11 +245,17 @@ as follows:
    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 <transitive-persistence>`").
+   ":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
 -----------------
 
@@ -279,12 +292,12 @@ 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 <transitive-persistence>`").
+   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 <transitive-persistence>`").
+   ":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.
@@ -308,7 +321,7 @@ 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()\`.
+   ``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
@@ -323,6 +336,13 @@ in multiple ways with very different performance impacts.
    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
 ------------------
 
@@ -350,14 +370,14 @@ as follows:
    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 <transitive-persistence>`"). Entities which previously referenced X
+   ":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 <transitive-persistence>`"). Entities which previously referenced X
+   ":ref:`transitive-persistence`"). Entities which previously referenced X
    will continue to reference X.
 
 There are several situations in which an entity is detached
@@ -416,7 +436,7 @@ as follows:
 -  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 <transitive-persistence>`").
+   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
@@ -793,7 +813,9 @@ 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. More information on
+``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>`.
 

docs/en/reference/xml-mapping.rst

@@ -7,7 +7,7 @@ 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
-`http://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd <http://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd>`_.
+`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
@@ -21,7 +21,7 @@ setup for the latest code in trunk.
     <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://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
+                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
         ...
 
@@ -107,7 +107,7 @@ of several common elements:
     <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
-                              http://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
+                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
         <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
 
@@ -768,7 +768,7 @@ entity relationship. You can define this in XML with the "association-key" attri
     <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
-                        http://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
+                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
          <entity name="Application\Model\ArticleAttribute">
             <id name="article" association-key="true" />

docs/en/reference/yaml-mapping.rst

@@ -1,6 +1,10 @@
 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.
 

docs/en/sidebar.rst

@@ -0,0 +1,83 @@
+.. toc::
+
+   .. tocheader:: Tutorials
+
+   .. toctree::
+      :depth: 3
+
+      tutorials/getting-started
+      tutorials/getting-started-database
+      tutorials/getting-started-models
+      tutorials/working-with-indexed-associations
+      tutorials/extra-lazy-associations
+      tutorials/composite-primary-keys
+      tutorials/ordered-associations
+      tutorials/override-field-association-mappings-in-subclasses
+      tutorials/pagination
+      tutorials/embeddables
+
+.. toc::
+
+   .. tocheader:: Reference
+
+   .. toctree::
+      :depth: 3
+
+      reference/architecture
+      reference/configuration
+      reference/faq
+      reference/basic-mapping
+      reference/association-mapping
+      reference/inheritance-mapping
+      reference/working-with-objects
+      reference/working-with-associations
+      reference/events
+      reference/unitofwork
+      reference/unitofwork-associations
+      reference/transactions-and-concurrency
+      reference/batch-processing
+      reference/dql-doctrine-query-language
+      reference/query-builder
+      reference/native-sql
+      reference/change-tracking-policies
+      reference/partial-objects
+      reference/xml-mapping
+      reference/yaml-mapping
+      reference/annotations-reference
+      reference/php-mapping
+      reference/caching
+      reference/improving-performance
+      reference/tools
+      reference/metadata-drivers
+      reference/best-practices
+      reference/limitations-and-known-issues
+      tutorials/pagination
+      reference/filters
+      reference/namingstrategy
+      reference/advanced-configuration
+      reference/second-level-cache
+      reference/security
+
+.. toc::
+
+   .. tocheader:: Cookbook
+
+   .. toctree::
+      :depth: 3
+
+      cookbook/aggregate-fields
+      cookbook/custom-mapping-types
+      cookbook/decorator-pattern
+      cookbook/dql-custom-walkers
+      cookbook/dql-user-defined-functions
+      cookbook/implementing-arrayaccess-for-domain-objects
+      cookbook/implementing-the-notify-changetracking-policy
+      cookbook/implementing-wakeup-or-clone
+      cookbook/resolve-target-entity-listener
+      cookbook/sql-table-prefixes
+      cookbook/strategy-cookbook-introduction
+      cookbook/validation-of-entities
+      cookbook/working-with-datetime
+      cookbook/mysql-enums
+      cookbook/advanced-field-value-conversion-using-custom-mapping-types
+      cookbook/entities-in-session

docs/en/toc.rst

@@ -75,7 +75,6 @@ Cookbook
    cookbook/implementing-arrayaccess-for-domain-objects
    cookbook/implementing-the-notify-changetracking-policy
    cookbook/implementing-wakeup-or-clone
-   cookbook/integrating-with-codeigniter
    cookbook/resolve-target-entity-listener
    cookbook/sql-table-prefixes
    cookbook/strategy-cookbook-introduction

docs/en/tutorials/composite-primary-keys.rst

@@ -63,7 +63,7 @@ and year of production as primary keys:
         <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
-                                  http://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="VehicleCatalogue\Model\Car">
                 <id field="name" type="string" />
@@ -203,7 +203,7 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
         <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
-                            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
              <entity name="Application\Model\ArticleAttribute">
                 <id name="article" association-key="true" />

docs/en/tutorials/extra-lazy-associations.rst

@@ -3,7 +3,7 @@ Extra Lazy Associations
 
 .. versionadded:: 2.1
 
-In many cases associations between entities can get pretty large. Even in a simple scenario like a blog.
+In many cases associations between entities can get pretty large. Even in a simple scenario like a blog
 where posts can be commented, you always have to assume that a post draws hundreds of comments.
 In Doctrine 2.0 if you accessed an association it would always get loaded completely into memory. This
 can lead to pretty serious performance problems, if your associations contain several hundreds or thousands
@@ -35,6 +35,15 @@ With extra lazy collections you can now not only add entities to large collectio
 easily using a combination of ``count`` and ``slice``.
 
 
+.. warning::
+
+   ``removeElement`` directly issued DELETE queries to the database from
+   version 2.4.0 to 2.7.0.  This circumvents the flush operation and might run
+   outside a transactional boundary if you don't create one yourself. We
+   consider this a critical bug in the assumptio of how the ORM works and
+   reverted ``removeElement`` EXTRA_LAZY behavior in 2.7.1.
+
+
 Enabling Extra-Lazy Associations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -65,7 +74,7 @@ switch to extra lazy as shown in these examples:
         <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
-                                  http://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Doctrine\Tests\Models\CMS\CmsGroup">
                 <!-- ... -->

docs/en/tutorials/getting-started-database.rst

@@ -7,7 +7,7 @@ Getting Started: Database First
     start with developing Objects and then map them onto your database. When
     you :doc:`Model First <getting-started-models>`, you are modelling your application using tools (for
     example UML) and generate database schema and PHP code from this model.
-    When you have a :doc:`Database First <getting-started-database>`, you already have a database schema
+    When you have a Database First, you already have a database schema
     and generate the corresponding PHP code from it.
 
 .. note::

docs/en/tutorials/getting-started-models.rst

@@ -5,7 +5,7 @@ Getting Started: Model First
 
     When you :doc:`Code First <getting-started>`, you
     start with developing Objects and then map them onto your database. When
-    you :doc:`Model First <getting-started-models>`, you are modelling your application using tools (for
+    you Model First, you are modelling your application using tools (for
     example UML) and generate database schema and PHP code from this model.
     When you have a :doc:`Database First <getting-started-database>`, then you already have a database schema
     and generate the corresponding PHP code from it.

docs/en/tutorials/getting-started.rst

@@ -19,21 +19,20 @@ installed:
 
 - PHP (latest stable version)
 - Composer Package Manager (`Install Composer
-  <http://getcomposer.org/doc/00-intro.md>`_)
+  <https://getcomposer.org/doc/00-intro.md>`_)
 
 The code of this tutorial is `available on Github <https://github.com/doctrine/doctrine2-orm-tutorial>`_.
 
 .. note::
 
-    This tutorial assumes you work with **Doctrine 2.4** and above.
+    This tutorial assumes you work with **Doctrine 2.6** and above.
     Some of the code will not work with lower versions.
 
 What is Doctrine?
 -----------------
 
-Doctrine 2 is an `object-relational mapper (ORM)
-<http://en.wikipedia.org/wiki/Object-relational_mapping>`_ for PHP 5.4+ that
-provides transparent persistence for PHP objects. It uses the Data Mapper
+Doctrine 2 is an `object-relational mapper (ORM) <https://en.wikipedia.org/wiki/Object-relational_mapping>`_
+for PHP 7.1+ that provides transparent persistence for PHP objects. It uses the Data Mapper
 pattern at the heart, aiming for a complete separation of your domain/business
 logic from the persistence in a relational database management system.
 
@@ -62,7 +61,7 @@ An Example Model: Bug Tracker
 
 For this Getting Started Guide for Doctrine we will implement the
 Bug Tracker domain model from the
-`Zend\_Db\_Table <http://framework.zend.com/manual/1.12/en/zend.db.adapter.html>`_
+`Zend_Db_Table <https://framework.zend.com/manual/1.12/en/zend.db.adapter.html>`_
 documentation. Reading their documentation we can extract the
 requirements:
 
@@ -73,21 +72,21 @@ requirements:
 -  Bug reporters and engineers are both Users of the system.
 -  A User can create new Bugs.
 -  The assigned engineer can close a Bug.
--  A User can see all his reported or assigned Bugs.
+-  A User can see all their reported or assigned Bugs.
 -  Bugs can be paginated through a list-view.
 
 Project Setup
 -------------
 
 Create a new empty folder for this tutorial project, for example
-``doctrine2-tutorial`` and create a new file ``composer.json`` with
-the following contents:
+``doctrine2-tutorial`` and create a new file ``composer.json`` inside
+that directory with the following contents:
 
 ::
 
     {
         "require": {
-            "doctrine/orm": "2.4.*",
+            "doctrine/orm": "^2.6.2",
             "symfony/yaml": "2.*"
         },
         "autoload": {
@@ -103,18 +102,21 @@ Install Doctrine using the Composer Dependency Management tool, by calling:
     $ composer install
 
 This will install the packages Doctrine Common, Doctrine DBAL, Doctrine ORM,
-Symfony YAML and Symfony Console into the `vendor` directory. The Symfony 
-dependencies are not required by Doctrine but will be used in this tutorial.
+into the ``vendor`` directory.
 
 Add the following directories:
 ::
 
     doctrine2-tutorial
     |-- config
-    |   |-- xml
+    |   `-- xml
     |   `-- yaml
     `-- src
 
+.. 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.
+
 Obtaining the EntityManager
 ---------------------------
 
@@ -136,7 +138,10 @@ step:
     
     // Create a simple "default" Doctrine ORM configuration for Annotations
     $isDevMode = true;
-    $config = Setup::createAnnotationMetadataConfiguration(array(__DIR__."/src"), $isDevMode);
+    $proxyDir = null;
+    $cache = null;
+    $useSimpleAnnotationReader = false;
+    $config = Setup::createAnnotationMetadataConfiguration(array(__DIR__."/src"), $isDevMode, $proxyDir, $cache, $useSimpleAnnotationReader);
     // or if you prefer yaml or XML
     //$config = Setup::createXMLMetadataConfiguration(array(__DIR__."/config/xml"), $isDevMode);
     //$config = Setup::createYAMLMetadataConfiguration(array(__DIR__."/config/yaml"), $isDevMode);
@@ -150,7 +155,15 @@ step:
     // obtaining the entity manager
     $entityManager = EntityManager::create($conn, $config);
 
-The require_once statement sets up the class autoloading for Doctrine and
+.. 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.
+
+.. note::
+    It is recommended not to use the SimpleAnnotationReader because its
+    usage will be removed for version 3.0.
+
+The ``require_once`` statement sets up the class autoloading for Doctrine and
 its dependencies using Composer's autoloader.
 
 The second block consists of the instantiation of the ORM
@@ -162,7 +175,7 @@ read up on the configuration details in the
 The third block shows the configuration options required to connect to
 a database. In this case, we'll use a file-based SQLite database. All the
 configuration options for all the shipped drivers are given in the
-`DBAL Configuration section of the manual <http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/>`_.
+`DBAL Configuration section of the manual <https://www.doctrine-project.org/projects/doctrine-dbal/en/current/>`_.
 
 The last block shows how the ``EntityManager`` is obtained from a
 factory method.
@@ -173,7 +186,7 @@ Generating the Database Schema
 Doctrine has a command-line interface that allows you to access the SchemaTool,
 a component that can generate a relational database schema based entirely on the
 defined entity classes and their metadata. For this tool to work, a
-cli-config.php file must exist in the project root directory:
+``cli-config.php`` file must exist in the project root directory:
 
 .. code-block:: php
 
@@ -183,20 +196,19 @@ cli-config.php file must exist in the project root directory:
     
     return \Doctrine\ORM\Tools\Console\ConsoleRunner::createHelperSet($entityManager);
 
-Change into your project directory and call the Doctrine command-line tool:
+Now call the Doctrine command-line tool:
 
 ::
 
-    $ cd project/
     $ vendor/bin/doctrine orm:schema-tool:create
 
-Since we haven't added any entity metadata in `src` yet, you'll see a message
+Since we haven't added any entity metadata in ``src`` yet, you'll see a message
 stating "No Metadata Classes to process." In the next section, we'll create a
 Product entity along with the corresponding metadata, and run this command again.
 
 Note that as you modify your entities' metadata during the development process,
 you'll need to update your database schema to stay in sync with the metadata.
-You can rasily recreate the database using the following commands:
+You can easily recreate the database using the following commands:
 
 ::
 
@@ -209,8 +221,8 @@ Or you can use the update functionality:
 
     $ vendor/bin/doctrine orm:schema-tool:update --force
 
-The updating of databases uses a Diff Algorithm for a given
-Database Schema. This is a cornerstone of the ``Doctrine\DBAL`` package,
+The updating of databases uses a diff algorithm for a given
+database schema. This is a cornerstone of the ``Doctrine\DBAL`` package,
 which can even be used without the Doctrine ORM package.
 
 Starting with the Product Entity
@@ -250,16 +262,16 @@ entity definition:
         }
     }
 
-When creating entity classes, all of the fields should be protected or private
-(not public), with getter and setter methods for each one (except $id).
+When creating entity classes, all of the fields should be ``protected`` or ``private``
+(not ``public``), with getter and setter methods for each one (except ``$id``).
 The use of mutators allows Doctrine to hook into calls which
-manipulate the entities in ways that it could not if you just 
+manipulate the entities in ways that it could not if you just
 directly set the values with ``entity#field = foo;``
 
-The id field has no setter since, generally speaking, your code 
-should not set this value since it represents a database id value. 
-(Note that Doctrine itself can still set the value using the 
-Reflection API instead of a defined setter function)
+The id field has no setter since, generally speaking, your code
+should not set this value since it represents a database id value.
+(Note that Doctrine itself can still set the value using the
+Reflection API instead of a defined setter function.)
 
 The next step for persistence with Doctrine is to describe the
 structure of the ``Product`` entity to Doctrine using a metadata
@@ -278,14 +290,24 @@ but you only need to choose one.
 
         <?php
         // src/Product.php
+
+        use Doctrine\ORM\Mapping as ORM;
+
         /**
-         * @Entity @Table(name="products")
-         **/
+         * @ORM\Entity
+         * @ORM\Table(name="products")
+         */
         class Product
         {
-            /** @Id @Column(type="integer") @GeneratedValue **/
+            /** 
+             * @ORM\Id
+             * @ORM\Column(type="integer")
+             * @ORM\GeneratedValue
+             */
             protected $id;
-            /** @Column(type="string") **/
+            /** 
+             * @ORM\Column(type="string") 
+             */
             protected $name;
 
             // .. (other code)
@@ -297,7 +319,7 @@ but you only need to choose one.
         <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
-                            http://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
+                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
               <entity name="Product" table="products">
                   <id name="id" type="integer">
@@ -308,6 +330,10 @@ but you only need to choose one.
               </entity>
         </doctrine-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.
+
     .. code-block:: yaml
 
         # config/yaml/Product.dcm.yml
@@ -323,8 +349,8 @@ but you only need to choose one.
             name:
               type: string
 
-The top-level ``entity`` definition tag specifies information about
-the class and table-name. The primitive type ``Product#name`` is
+The top-level ``entity`` definition specifies information about
+the class and table name. The primitive type ``Product#name`` is
 defined as a ``field`` attribute. The ``id`` property is defined with
 the ``id`` tag.  It has a ``generator`` tag nested inside, which
 specifies that the primary key generation mechanism should automatically
@@ -458,28 +484,36 @@ classes. We'll store them in ``src/Bug.php`` and ``src/User.php``, respectively.
 
     <?php
     // src/Bug.php
+
+    use Doctrine\ORM\Mapping as ORM;
+
     /**
-     * @Entity(repositoryClass="BugRepository") @Table(name="bugs")
+     * @ORM\Table(name="bugs")
      */
     class Bug
     {
         /**
-         * @Id @Column(type="integer") @GeneratedValue
+         * @ORM\Id
+         * @ORM\Column(type="integer")
+         * @ORM\GeneratedValue
          * @var int
          */
         protected $id;
+
         /**
-         * @Column(type="string")
+         * @ORM\Column(type="string")
          * @var string
          */
         protected $description;
+
         /**
-         * @Column(type="datetime")
+         * @ORM\Column(type="datetime")
          * @var DateTime
          */
         protected $created;
+
         /**
-         * @Column(type="string")
+         * @ORM\Column(type="string")
          * @var string
          */
         protected $status;
@@ -524,18 +558,25 @@ classes. We'll store them in ``src/Bug.php`` and ``src/User.php``, respectively.
 
     <?php
     // src/User.php
+
+    use Doctrine\ORM\Mapping as ORM;
+
     /**
-     * @Entity @Table(name="users")
+     * @ORM\Entity 
+     * @ORM\Table(name="users")
      */
     class User
     {
         /**
-         * @Id @GeneratedValue @Column(type="integer")
+         * @ORM\Id
+         * @ORM\GeneratedValue
+         * @ORM\Column(type="integer")
          * @var int
          */
         protected $id;
+
         /**
-         * @Column(type="string")
+         * @ORM\Column(type="string")
          * @var string
          */
         protected $name;
@@ -765,7 +806,7 @@ the database that points from Bugs to Products.
     {
         // ... (previous code)
 
-        protected $products = null;
+        protected $products;
 
         public function assignToProduct(Product $product)
         {
@@ -787,41 +828,50 @@ the ``Product`` before:
 
         <?php
         // src/Bug.php
+
+        use Doctrine\ORM\Mapping as ORM;
+
         /**
-         * @Entity @Table(name="bugs")
-         **/
+         * @ORM\Entity 
+         * @ORM\Table(name="bugs")
+         */
         class Bug
         {
             /**
-             * @Id @Column(type="integer") @GeneratedValue
-             **/
+             * @ORM\Id 
+             * @ORM\Column(type="integer") 
+             * @ORM\GeneratedValue
+             */
             protected $id;
+
             /**
-             * @Column(type="string")
-             **/
+             * @ORM\Column(type="string")
+             */
             protected $description;
+
             /**
-             * @Column(type="datetime")
-             **/
+             * @ORM\Column(type="datetime")
+             */
             protected $created;
+
             /**
-             * @Column(type="string")
-             **/
+             * @ORM\Column(type="string")
+             */
             protected $status;
 
             /**
-             * @ManyToOne(targetEntity="User", inversedBy="assignedBugs")
-             **/
+             * @ORM\ManyToOne(targetEntity="User", inversedBy="assignedBugs")
+             */
             protected $engineer;
 
             /**
-             * @ManyToOne(targetEntity="User", inversedBy="reportedBugs")
-             **/
+             * @ORM\ManyToOne(targetEntity="User", inversedBy="reportedBugs")
+             */
             protected $reporter;
 
             /**
-             * @ManyToMany(targetEntity="Product")
-             **/
+             * @ORM\ManyToMany(targetEntity="Product")
+             */
             protected $products;
 
             // ... (other code)
@@ -833,7 +883,7 @@ the ``Product`` before:
         <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
-                            http://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
+                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Bug" table="bugs">
                 <id name="id" type="integer">
@@ -851,6 +901,10 @@ the ``Product`` before:
             </entity>
         </doctrine-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.
+
     .. code-block:: yaml
 
         # config/yaml/Bug.dcm.yml
@@ -911,34 +965,40 @@ Finally, we'll add metadata mappings for the ``User`` entity.
 
         <?php
         // src/User.php
+
+        use Doctrine\ORM\Mapping as ORM;
+
         /**
-         * @Entity @Table(name="users")
-         **/
+         * @ORM\Entity
+         * @ORM\Table(name="users")
+         */
         class User
         {
             /**
-             * @Id @GeneratedValue @Column(type="integer")
+             * @ORM\Id 
+             * @ORM\GeneratedValue 
+             * @ORM\Column(type="integer")
              * @var int
-             **/
+             */
             protected $id;
 
             /**
-             * @Column(type="string")
+             * @ORM\Column(type="string")
              * @var string
-             **/
+             */
             protected $name;
 
             /**
-             * @OneToMany(targetEntity="Bug", mappedBy="reporter")
+             * @ORM\OneToMany(targetEntity="Bug", mappedBy="reporter")
              * @var Bug[] An ArrayCollection of Bug objects.
-             **/
-            protected $reportedBugs = null;
+             */
+            protected $reportedBugs;
 
             /**
-             * @OneToMany(targetEntity="Bug", mappedBy="engineer")
+             * @ORM\OneToMany(targetEntity="Bug", mappedBy="engineer")
              * @var Bug[] An ArrayCollection of Bug objects.
-             **/
-            protected $assignedBugs = null;
+             */
+            protected $assignedBugs;
 
             // .. (other code)
         }
@@ -949,7 +1009,7 @@ Finally, we'll add metadata mappings for the ``User`` entity.
         <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
-                            http://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
+                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
              <entity name="User" table="users">
                  <id name="id" type="integer">
@@ -963,6 +1023,10 @@ Finally, we'll add metadata mappings for the ``User`` entity.
              </entity>
         </doctrine-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.
+
     .. code-block:: yaml
 
         # config/yaml/User.dcm.yml
@@ -1145,8 +1209,7 @@ The console output of this script is then:
     throw your ORM into the dumpster, because it doesn't support some
     the more powerful SQL concepts.
 
-
-    Instead of handwriting DQL you can use the ``QueryBuilder`` retrieved
+    If you need to build your query dynamically, you can use the ``QueryBuilder`` retrieved
     by calling ``$entityManager->createQueryBuilder()``. There are more
     details about this in the relevant part of the documentation.
 
@@ -1472,9 +1535,12 @@ we have to adjust the metadata slightly.
     .. code-block:: php
 
         <?php
+
+        use Doctrine\ORM\Mapping as ORM;
+
         /**
-         * @Entity(repositoryClass="BugRepository")
-         * @Table(name="bugs")
+         * @ORM\Entity(repositoryClass="BugRepository")
+         * @ORM\Table(name="bugs")
          **/
         class Bug
         {
@@ -1486,13 +1552,17 @@ we have to adjust the metadata slightly.
         <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
-                            http://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
+                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
               <entity name="Bug" table="bugs" repository-class="BugRepository">
 
               </entity>
         </doctrine-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.
+
     .. code-block:: yaml
 
         Bug:

docs/en/tutorials/ordered-associations.rst

@@ -5,8 +5,8 @@ There are use-cases when you'll want to sort collections when they are
 retrieved from the database. In userland you do this as long as you
 haven't initially saved an entity with its associations into the
 database. To retrieve a sorted collection from the database you can
-use the ``@OrderBy`` annotation with an collection that specifies
-an DQL snippet that is appended to all queries with this
+use the ``@OrderBy`` annotation with a collection that specifies
+a DQL snippet that is appended to all queries with this
 collection.
 
 Additional to any ``@OneToMany`` or ``@ManyToMany`` annotation you
@@ -64,7 +64,7 @@ positional statement. Multiple Fields are separated by a comma (,).
 The referenced field names have to exist on the ``targetEntity``
 class of the ``@ManyToMany`` or ``@OneToMany`` annotation.
 
-The semantics of this feature can be described as follows.
+The semantics of this feature can be described as follows:
 
 
 -  ``@OrderBy`` acts as an implicit ORDER BY clause for the given
@@ -73,7 +73,7 @@ The semantics of this feature can be described as follows.
 -  All collections of the ordered type are always retrieved in an
    ordered fashion.
 -  To keep the database impact low, these implicit ORDER BY items
-   are only added to an DQL Query if the collection is fetch joined in
+   are only added to a DQL Query if the collection is fetch joined in
    the DQL query.
 
 Given our previously defined example, the following would not add

docs/en/tutorials/working-with-indexed-associations.rst

@@ -107,7 +107,7 @@ The code and mappings for the Market entity looks like this:
         <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
-                                  http://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Doctrine\Tests\Models\StockExchange\Market">
                 <id name="id" type="integer">
@@ -193,7 +193,7 @@ here are the code and mappings for it:
         <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
-                                  http://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Doctrine\Tests\Models\StockExchange\Stock">
                 <id name="id" type="integer">
@@ -291,6 +291,5 @@ Outlook into the Future
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 For the inverse side of a many-to-many associations there will be a way to persist the keys and the order
-as a third and fourth parameter into the join table. This feature is discussed in `DDC-213 <http://www.doctrine-project.org/jira/browse/DDC-213>`_
+as a third and fourth parameter into the join table. This feature is discussed in `#2817 <https://github.com/doctrine/orm/issues/2817>`_
 This feature cannot be implemented for one-to-many associations, because they are never the owning side.
-

lib/Doctrine/ORM/AbstractQuery.php

@@ -22,10 +22,11 @@ namespace Doctrine\ORM;
 use Doctrine\Common\Util\ClassUtils;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\Common\Collections\ArrayCollection;
-
+use Doctrine\DBAL\Cache\QueryCacheProfile;
+use Doctrine\ORM\Mapping\MappingException as ORMMappingException;
 use Doctrine\ORM\Query\Parameter;
 use Doctrine\ORM\Cache\QueryCacheKey;
-use Doctrine\DBAL\Cache\QueryCacheProfile;
+use Doctrine\Persistence\Mapping\MappingException;
 
 /**
  * Base contract for ORM queries. Base class for Query and NativeQuery.
@@ -70,7 +71,8 @@ abstract class AbstractQuery
     /**
      * The parameter map of this query.
      *
-     * @var \Doctrine\Common\Collections\ArrayCollection
+     * @var ArrayCollection|Parameter[]
+     * @psalm-var ArrayCollection<int, Parameter>
      */
     protected $parameters;
 
@@ -98,7 +100,7 @@ abstract class AbstractQuery
     /**
      * The hydration mode.
      *
-     * @var integer
+     * @var string|int
      */
     protected $_hydrationMode = self::HYDRATE_OBJECT;
 
@@ -239,7 +241,7 @@ abstract class AbstractQuery
      *
      * @param integer $lifetime
      *
-     * @return \Doctrine\ORM\AbstractQuery This query instance.
+     * @return static This query instance.
      */
     public function setLifetime($lifetime)
     {
@@ -259,7 +261,7 @@ abstract class AbstractQuery
     /**
      * @param integer $cacheMode
      *
-     * @return \Doctrine\ORM\AbstractQuery This query instance.
+     * @return static This query instance.
      */
     public function setCacheMode($cacheMode)
     {
@@ -304,7 +306,7 @@ abstract class AbstractQuery
     /**
      * Get all defined parameters.
      *
-     * @return \Doctrine\Common\Collections\ArrayCollection The defined query parameters.
+     * @return ArrayCollection The defined query parameters.
      */
     public function getParameters()
     {
@@ -320,11 +322,13 @@ abstract class AbstractQuery
      */
     public function getParameter($key)
     {
+        $key = Query\Parameter::normalizeName($key);
+
         $filteredParameters = $this->parameters->filter(
             function (Query\Parameter $parameter) use ($key) : bool {
                 $parameterName = $parameter->getName();
 
-                return $key === $parameterName || (string) $key === (string) $parameterName;
+                return $key === $parameterName;
             }
         );
 
@@ -334,14 +338,17 @@ abstract class AbstractQuery
     /**
      * Sets a collection of query parameters.
      *
-     * @param \Doctrine\Common\Collections\ArrayCollection|array $parameters
+     * @param ArrayCollection|mixed[] $parameters
      *
      * @return static This query instance.
+     *
+     * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
      */
     public function setParameters($parameters)
     {
         // BC compatibility with 2.3-
         if (is_array($parameters)) {
+            /** @psalm-var ArrayCollection<int, Parameter> $parameterCollection */
             $parameterCollection = new ArrayCollection();
 
             foreach ($parameters as $key => $value) {
@@ -387,9 +394,11 @@ abstract class AbstractQuery
      *
      * @param mixed $value
      *
-     * @return array|string
+     * @return mixed[]|string|int|float|bool
      *
      * @throws \Doctrine\ORM\ORMInvalidArgumentException
+     *
+     * @psalm-return array|scalar
      */
     public function processParameterValue($value)
     {
@@ -410,16 +419,24 @@ abstract class AbstractQuery
             return $value;
         }
 
-        if (is_object($value) && $this->_em->getMetadataFactory()->hasMetadataFor(ClassUtils::getClass($value))) {
+        if ($value instanceof Mapping\ClassMetadata) {
+            return $value->name;
+        }
+
+        if (! is_object($value)) {
+            return $value;
+        }
+
+        try {
             $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
 
             if ($value === null) {
                 throw ORMInvalidArgumentException::invalidIdentifierBindingEntity();
             }
-        }
-
-        if ($value instanceof Mapping\ClassMetadata) {
-            return $value->name;
+        } catch (MappingException | ORMMappingException $e) {
+            // Silence any mapping exceptions. These can occur if the object in
+            // question is not a mapped entity, in which case we just don't do
+            // any preparation on the value.
         }
 
         return $value;
@@ -459,7 +476,7 @@ abstract class AbstractQuery
      */
     private function translateNamespaces(Query\ResultSetMapping $rsm)
     {
-        $translate = function ($alias) {
+        $translate = function ($alias) : string {
             return $this->_em->getClassMetadata($alias)->getName();
         };
 
@@ -573,21 +590,45 @@ abstract class AbstractQuery
      * Set whether or not to cache the results of this query and if so, for
      * how long and which ID to use for the cache entry.
      *
-     * @param boolean $bool
-     * @param integer $lifetime
-     * @param string  $resultCacheId
+     * @deprecated 2.7 Use {@see enableResultCache} and {@see disableResultCache} instead.
+     *
+     * @param bool   $useCache
+     * @param int    $lifetime
+     * @param string $resultCacheId
      *
      * @return static This query instance.
      */
-    public function useResultCache($bool, $lifetime = null, $resultCacheId = null)
+    public function useResultCache($useCache, $lifetime = null, $resultCacheId = null)
     {
-        if ($bool) {
-            $this->setResultCacheLifetime($lifetime);
-            $this->setResultCacheId($resultCacheId);
+        return $useCache
+            ? $this->enableResultCache($lifetime, $resultCacheId)
+            : $this->disableResultCache();
+    }
 
-            return $this;
-        }
+    /**
+     * Enables caching of the results of this query, for given or default amount of seconds
+     * and optionally specifies which ID to use for the cache entry.
+     *
+     * @param int|null    $lifetime      How long the cache entry is valid, in seconds.
+     * @param string|null $resultCacheId ID to use for the cache entry.
+     *
+     * @return static This query instance.
+     */
+    public function enableResultCache(?int $lifetime = null, ?string $resultCacheId = null) : self
+    {
+        $this->setResultCacheLifetime($lifetime);
+        $this->setResultCacheId($resultCacheId);
 
+        return $this;
+    }
+
+    /**
+     * Disables caching of the results of this query.
+     *
+     * @return static This query instance.
+     */
+    public function disableResultCache() : self
+    {
         $this->_queryCacheProfile = null;
 
         return $this;
@@ -596,7 +637,7 @@ abstract class AbstractQuery
     /**
      * Defines how long the result cache will be active before expire.
      *
-     * @param integer $lifetime How long the cache entry is valid.
+     * @param int|null $lifetime How long the cache entry is valid.
      *
      * @return static This query instance.
      */
@@ -680,8 +721,8 @@ abstract class AbstractQuery
     /**
      * Defines the processing mode to be used during hydration / result set transformation.
      *
-     * @param integer $hydrationMode Doctrine processing mode to be used during hydration process.
-     *                               One of the Query::HYDRATE_* constants.
+     * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
+     *                                  One of the Query::HYDRATE_* constants.
      *
      * @return static This query instance.
      */
@@ -695,7 +736,7 @@ abstract class AbstractQuery
     /**
      * Gets the hydration mode currently used by the query.
      *
-     * @return integer
+     * @return string|int
      */
     public function getHydrationMode()
     {
@@ -707,7 +748,7 @@ abstract class AbstractQuery
      *
      * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
      *
-     * @param int $hydrationMode
+     * @param string|int $hydrationMode
      *
      * @return mixed
      */
@@ -743,7 +784,7 @@ abstract class AbstractQuery
     /**
      * Get exactly one result or null.
      *
-     * @param int $hydrationMode
+     * @param string|int $hydrationMode
      *
      * @return mixed
      *
@@ -781,7 +822,7 @@ abstract class AbstractQuery
      * If the result is not unique, a NonUniqueResultException is thrown.
      * If there is no result, a NoResultException is thrown.
      *
-     * @param integer $hydrationMode
+     * @param string|int $hydrationMode
      *
      * @return mixed
      *
@@ -812,8 +853,9 @@ abstract class AbstractQuery
      *
      * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).
      *
-     * @return mixed The scalar result, or NULL if the query returned no result.
+     * @return mixed The scalar result.
      *
+     * @throws NoResultException        If the query returned no result.
      * @throws NonUniqueResultException If the query result is not unique.
      */
     public function getSingleScalarResult()
@@ -875,7 +917,7 @@ abstract class AbstractQuery
      * iterate over the result.
      *
      * @param ArrayCollection|array|null $parameters    The query parameters.
-     * @param integer|null               $hydrationMode The hydration mode to use.
+     * @param string|int|null            $hydrationMode The hydration mode to use.
      *
      * @return \Doctrine\ORM\Internal\Hydration\IterableResult
      */
@@ -899,7 +941,7 @@ abstract class AbstractQuery
      * Executes the query.
      *
      * @param ArrayCollection|array|null $parameters Query parameters.
-     * @param integer|null               $hydrationMode Processing mode to be used during the hydration process.
+     * @param string|int|null            $hydrationMode Processing mode to be used during the hydration process.
      *
      * @return mixed
      */
@@ -916,7 +958,7 @@ abstract class AbstractQuery
      * Execute query ignoring second level cache.
      *
      * @param ArrayCollection|array|null $parameters
-     * @param integer|null               $hydrationMode
+     * @param string|int|null            $hydrationMode
      *
      * @return mixed
      */
@@ -930,10 +972,11 @@ abstract class AbstractQuery
             $this->setParameters($parameters);
         }
 
-        $setCacheEntry = function() {};
+        $setCacheEntry = static function () : void {
+        };
 
         if ($this->_hydrationCacheProfile !== null) {
-            list($cacheKey, $realCacheKey) = $this->getHydrationCacheId();
+            [$cacheKey, $realCacheKey] = $this->getHydrationCacheId();
 
             $queryCacheProfile = $this->getHydrationCacheProfile();
             $cache             = $queryCacheProfile->getResultCacheDriver();
@@ -947,7 +990,7 @@ abstract class AbstractQuery
                 $result = [];
             }
 
-            $setCacheEntry = function($data) use ($cache, $result, $cacheKey, $realCacheKey, $queryCacheProfile) {
+            $setCacheEntry = static function ($data) use ($cache, $result, $cacheKey, $realCacheKey, $queryCacheProfile) : void {
                 $result[$realCacheKey] = $data;
 
                 $cache->save($cacheKey, $result, $queryCacheProfile->getLifetime());
@@ -974,7 +1017,7 @@ abstract class AbstractQuery
      * Load from second level cache or executes the query and put into cache.
      *
      * @param ArrayCollection|array|null $parameters
-     * @param integer|null               $hydrationMode
+     * @param string|int|null            $hydrationMode
      *
      * @return mixed
      */
@@ -1034,7 +1077,7 @@ abstract class AbstractQuery
      * Will return the configured id if it exists otherwise a hash will be
      * automatically generated for you.
      *
-     * @return array ($key, $hash)
+     * @return array<string, string> ($key, $hash)
      */
     protected function getHydrationCacheId()
     {

lib/Doctrine/ORM/Cache/DefaultCache.php

@@ -60,9 +60,6 @@ class DefaultCache implements Cache
      */
     private $defaultQueryCache;
 
-    /**
-     * {@inheritdoc}
-     */
     public function __construct(EntityManagerInterface $em)
     {
         $this->em           = $em;

lib/Doctrine/ORM/Cache/DefaultEntityHydrator.php

@@ -75,6 +75,10 @@ class DefaultEntityHydrator implements EntityHydrator
         $data = $this->uow->getOriginalEntityData($entity);
         $data = array_merge($data, $metadata->getIdentifierValues($entity)); // why update has no identifier values ?
 
+        if ($metadata->isVersioned) {
+            $data[$metadata->versionField] = $metadata->getFieldValue($entity, $metadata->versionField);
+        }
+
         foreach ($metadata->associationMappings as $name => $assoc) {
             if ( ! isset($data[$name])) {
                 continue;

lib/Doctrine/ORM/Cache/DefaultQueryCache.php

@@ -22,6 +22,7 @@ namespace Doctrine\ORM\Cache;
 
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\ORM\Cache\Persister\CachedPersister;
+use Doctrine\ORM\Cache\Persister\Entity\CachedEntityPersister;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\ORM\Mapping\ClassMetadata;
@@ -29,6 +30,7 @@ use Doctrine\ORM\PersistentCollection;
 use Doctrine\Common\Proxy\Proxy;
 use Doctrine\ORM\Cache;
 use Doctrine\ORM\Query;
+use function assert;
 
 /**
  * Default query cache implementation.
@@ -106,25 +108,27 @@ class DefaultQueryCache implements QueryCache
 
         $result      = [];
         $entityName  = reset($rsm->aliasMap);
-        $hasRelation = ( ! empty($rsm->relationMap));
+        $hasRelation = ! empty($rsm->relationMap);
         $persister   = $this->uow->getEntityPersister($entityName);
-        $region      = $persister->getCacheRegion();
-        $regionName  = $region->getName();
+        assert($persister instanceof CachedEntityPersister);
+
+        $region     = $persister->getCacheRegion();
+        $regionName = $region->getName();
 
         $cm = $this->em->getClassMetadata($entityName);
 
-        $generateKeys = function (array $entry) use ($cm): EntityCacheKey {
+        $generateKeys = static function (array $entry) use ($cm) : EntityCacheKey {
             return new EntityCacheKey($cm->rootEntityName, $entry['identifier']);
         };
 
         $cacheKeys = new CollectionCacheEntry(array_map($generateKeys, $cacheEntry->result));
-        $entries   = $region->getMultiple($cacheKeys);
+        $entries   = $region->getMultiple($cacheKeys) ?? [];
 
         // @TODO - move to cache hydration component
         foreach ($cacheEntry->result as $index => $entry) {
-            $entityEntry = is_array($entries) && array_key_exists($index, $entries) ? $entries[$index] : null;
+            $entityEntry = $entries[$index] ?? null;
 
-            if ($entityEntry === null) {
+            if (! $entityEntry instanceof EntityCacheEntry) {
                 if ($this->cacheLogger !== null) {
                     $this->cacheLogger->entityCacheMiss($regionName, $cacheKeys->identifiers[$index]);
                 }
@@ -145,9 +149,11 @@ class DefaultQueryCache implements QueryCache
             $data = $entityEntry->data;
 
             foreach ($entry['associations'] as $name => $assoc) {
-                $assocPersister  = $this->uow->getEntityPersister($assoc['targetEntity']);
-                $assocRegion     = $assocPersister->getCacheRegion();
-                $assocMetadata   = $this->em->getClassMetadata($assoc['targetEntity']);
+                $assocPersister = $this->uow->getEntityPersister($assoc['targetEntity']);
+                assert($assocPersister instanceof CachedEntityPersister);
+
+                $assocRegion   = $assocPersister->getCacheRegion();
+                $assocMetadata = $this->em->getClassMetadata($assoc['targetEntity']);
 
                 if ($assoc['type'] & ClassMetadata::TO_ONE) {
 
@@ -254,7 +260,7 @@ class DefaultQueryCache implements QueryCache
             throw new CacheException("Second-level cache query supports only select statements.");
         }
 
-        if (isset($hints[Query::HINT_FORCE_PARTIAL_LOAD]) && $hints[Query::HINT_FORCE_PARTIAL_LOAD]) {
+        if (($hints[Query\SqlWalker::HINT_PARTIAL] ?? false) === true || ($hints[Query::HINT_FORCE_PARTIAL_LOAD] ?? false) === true) {
             throw new CacheException("Second level cache does not support partial entities.");
         }
 
@@ -267,15 +273,18 @@ class DefaultQueryCache implements QueryCache
         $rootAlias   = key($rsm->aliasMap);
         $persister   = $this->uow->getEntityPersister($entityName);
 
-        if ( ! ($persister instanceof CachedPersister)) {
+        if (! $persister instanceof CachedEntityPersister) {
             throw CacheException::nonCacheableEntity($entityName);
         }
 
         $region = $persister->getCacheRegion();
 
+        $cm = $this->em->getClassMetadata($entityName);
+        assert($cm instanceof ClassMetadata);
+
         foreach ($result as $index => $entity) {
-            $identifier                     = $this->uow->getEntityIdentifier($entity);
-            $entityKey                      = new EntityCacheKey($entityName, $identifier);
+            $identifier = $this->uow->getEntityIdentifier($entity);
+            $entityKey  = new EntityCacheKey($cm->rootEntityName, $identifier);
 
             if (($key->cacheMode & Cache::MODE_REFRESH) || ! $region->contains($entityKey)) {
                 // Cancel put result if entity put fail
@@ -339,7 +348,9 @@ class DefaultQueryCache implements QueryCache
      * @param array                             $assoc
      * @param mixed                             $assocValue
      *
-     * @return array|null
+     * @return mixed[]|null
+     *
+     * @psalm-return array{targetEntity: string, type: mixed, list?: array[], identifier?: array}|null
      */
     private function storeAssociationCache(QueryCacheKey $key, array $assoc, $assocValue)
     {

lib/Doctrine/ORM/Cache/Logging/StatisticsCacheLogger.php

@@ -33,17 +33,17 @@ use Doctrine\ORM\Cache\QueryCacheKey;
 class StatisticsCacheLogger implements CacheLogger
 {
     /**
-     * @var array
+     * @var int[]
      */
     private $cacheMissCountMap = [];
 
     /**
-     * @var array
+     * @var int[]
      */
     private $cacheHitCountMap = [];
 
     /**
-     * @var array
+     * @var int[]
      */
     private $cachePutCountMap = [];
 
@@ -142,7 +142,7 @@ class StatisticsCacheLogger implements CacheLogger
      *
      * @param string $regionName The name of the cache region.
      *
-     * @return integer
+     * @return int
      */
     public function getRegionHitCount($regionName)
     {
@@ -154,7 +154,7 @@ class StatisticsCacheLogger implements CacheLogger
      *
      * @param string $regionName The name of the cache region.
      *
-     * @return integer
+     * @return int
      */
     public function getRegionMissCount($regionName)
     {
@@ -166,7 +166,7 @@ class StatisticsCacheLogger implements CacheLogger
      *
      * @param string $regionName The name of the cache region.
      *
-     * @return integer
+     * @return int
      */
     public function getRegionPutCount($regionName)
     {
@@ -222,7 +222,7 @@ class StatisticsCacheLogger implements CacheLogger
     /**
      * Get the total number of put in cache.
      *
-     * @return integer
+     * @return int
      */
     public function getPutCount()
     {
@@ -232,7 +232,7 @@ class StatisticsCacheLogger implements CacheLogger
     /**
      * Get the total number of entries successfully retrieved from cache.
      *
-     * @return integer
+     * @return int
      */
     public function getHitCount()
     {
@@ -242,7 +242,7 @@ class StatisticsCacheLogger implements CacheLogger
     /**
      * Get the total number of cached entries *not* found in cache.
      *
-     * @return integer
+     * @return int
      */
     public function getMissCount()
     {

lib/Doctrine/ORM/Cache/Persister/Collection/AbstractCollectionPersister.php

@@ -144,7 +144,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
      * @param \Doctrine\ORM\PersistentCollection     $collection
      * @param \Doctrine\ORM\Cache\CollectionCacheKey $key
      *
-     * @return \Doctrine\ORM\PersistentCollection|null
+     * @return object[]|null
      */
     public function loadCollectionCache(PersistentCollection $collection, CollectionCacheKey $key)
     {
@@ -243,20 +243,6 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
         return $this->persister->get($collection, $index);
     }
 
-    /**
-     * {@inheritdoc}
-     */
-    public function removeElement(PersistentCollection $collection, $element)
-    {
-        if ($persisterResult = $this->persister->removeElement($collection, $element)) {
-            $this->evictCollectionCache($collection);
-            $this->evictElementCache($this->sourceEntity->rootEntityName, $collection->getOwner());
-            $this->evictElementCache($this->targetEntity->rootEntityName, $element);
-        }
-
-        return $persisterResult;
-    }
-
     /**
      * {@inheritdoc}
      */

lib/Doctrine/ORM/Cache/Persister/Entity/AbstractEntityPersister.php

@@ -283,17 +283,17 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     /**
      * Generates a string of currently query
      *
-     * @param array   $query
-     * @param string  $criteria
-     * @param array   $orderBy
-     * @param integer $limit
-     * @param integer $offset
+     * @param string            $query
+     * @param string[]|Criteria $criteria
+     * @param string[]          $orderBy
+     * @param int               $limit
+     * @param int               $offset
      *
      * @return string
      */
     protected function getHash($query, $criteria, array $orderBy = null, $limit = null, $offset = null)
     {
-        list($params) = ($criteria instanceof Criteria)
+        [$params] = $criteria instanceof Criteria
             ? $this->persister->expandCriteriaParameters($criteria)
             : $this->persister->expandParameters($criteria);
 
@@ -452,12 +452,14 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
                 $class = $this->metadataFactory->getMetadataFor($cacheEntry->class);
             }
 
-            if (($entity = $this->hydrator->loadCacheEntry($class, $cacheKey, $cacheEntry, $entity)) !== null) {
+            $cachedEntity = $this->hydrator->loadCacheEntry($class, $cacheKey, $cacheEntry, $entity);
+
+            if ($cachedEntity !== null) {
                 if ($this->cacheLogger) {
                     $this->cacheLogger->entityCacheHit($this->regionName, $cacheKey);
                 }
 
-                return $entity;
+                return $cachedEntity;
             }
         }
 
@@ -542,19 +544,18 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     /**
      * {@inheritdoc}
      */
-    public function loadManyToManyCollection(array $assoc, $sourceEntity, PersistentCollection $coll)
+    public function loadManyToManyCollection(array $assoc, $sourceEntity, PersistentCollection $collection)
     {
         $persister = $this->uow->getCollectionPersister($assoc);
         $hasCache  = ($persister instanceof CachedPersister);
-        $key       = null;
 
         if ( ! $hasCache) {
-            return $this->persister->loadManyToManyCollection($assoc, $sourceEntity, $coll);
+            return $this->persister->loadManyToManyCollection($assoc, $sourceEntity, $collection);
         }
 
-        $ownerId = $this->uow->getEntityIdentifier($coll->getOwner());
+        $ownerId = $this->uow->getEntityIdentifier($collection->getOwner());
         $key     = $this->buildCollectionCacheKey($assoc, $ownerId);
-        $list    = $persister->loadCollectionCache($coll, $key);
+        $list    = $persister->loadCollectionCache($collection, $key);
 
         if ($list !== null) {
             if ($this->cacheLogger) {
@@ -564,7 +565,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
             return $list;
         }
 
-        $list = $this->persister->loadManyToManyCollection($assoc, $sourceEntity, $coll);
+        $list = $this->persister->loadManyToManyCollection($assoc, $sourceEntity, $collection);
 
         $persister->storeCollectionCache($key, $list);
 
@@ -578,18 +579,18 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     /**
      * {@inheritdoc}
      */
-    public function loadOneToManyCollection(array $assoc, $sourceEntity, PersistentCollection $coll)
+    public function loadOneToManyCollection(array $assoc, $sourceEntity, PersistentCollection $collection)
     {
         $persister = $this->uow->getCollectionPersister($assoc);
         $hasCache  = ($persister instanceof CachedPersister);
 
         if ( ! $hasCache) {
-            return $this->persister->loadOneToManyCollection($assoc, $sourceEntity, $coll);
+            return $this->persister->loadOneToManyCollection($assoc, $sourceEntity, $collection);
         }
 
-        $ownerId = $this->uow->getEntityIdentifier($coll->getOwner());
+        $ownerId = $this->uow->getEntityIdentifier($collection->getOwner());
         $key     = $this->buildCollectionCacheKey($assoc, $ownerId);
-        $list    = $persister->loadCollectionCache($coll, $key);
+        $list    = $persister->loadCollectionCache($collection, $key);
 
         if ($list !== null) {
             if ($this->cacheLogger) {
@@ -599,7 +600,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
             return $list;
         }
 
-        $list = $this->persister->loadOneToManyCollection($assoc, $sourceEntity, $coll);
+        $list = $this->persister->loadOneToManyCollection($assoc, $sourceEntity, $collection);
 
         $persister->storeCollectionCache($key, $list);
 

lib/Doctrine/ORM/Cache/Persister/Entity/NonStrictReadWriteCachedEntityPersister.php

@@ -100,6 +100,12 @@ class NonStrictReadWriteCachedEntityPersister extends AbstractEntityPersister
         $this->queuedCache['update'][] = $entity;
     }
 
+    /**
+     * @param object $entity
+     * @param bool   $isChanged
+     *
+     * @return bool
+     */
     private function updateCache($entity, $isChanged)
     {
         $class      = $this->metadataFactory->getMetadataFor(get_class($entity));

lib/Doctrine/ORM/Cache/Region/DefaultMultiGetRegion.php

@@ -21,6 +21,7 @@
 namespace Doctrine\ORM\Cache\Region;
 
 use Doctrine\Common\Cache\MultiGetCache;
+use Doctrine\ORM\Cache\CacheEntry;
 use Doctrine\ORM\Cache\CollectionCacheEntry;
 
 /**
@@ -67,7 +68,12 @@ class DefaultMultiGetRegion extends DefaultRegion
         }
 
         $returnableItems = [];
+
         foreach ($keysToRetrieve as $index => $key) {
+            if (! $items[$key] instanceof CacheEntry) {
+                return null;
+            }
+
             $returnableItems[$index] = $items[$key];
         }
 

lib/Doctrine/ORM/Cache/Region/DefaultRegion.php

@@ -94,7 +94,13 @@ class DefaultRegion implements Region
      */
     public function get(CacheKey $key)
     {
-        return $this->cache->fetch($this->getCacheEntryKey($key)) ?: null;
+        $entry = $this->cache->fetch($this->getCacheEntryKey($key));
+
+        if (! $entry instanceof CacheEntry) {
+            return null;
+        }
+
+        return $entry;
     }
 
     /**
@@ -108,7 +114,7 @@ class DefaultRegion implements Region
             $entryKey   = $this->getCacheEntryKey($key);
             $entryValue = $this->cache->fetch($entryKey);
 
-            if ($entryValue === false) {
+            if (! $entryValue instanceof CacheEntry) {
                 return null;
             }
 

lib/Doctrine/ORM/Cache/Region/FileLockRegion.php

@@ -249,6 +249,8 @@ class FileLockRegion implements ConcurrentRegion
 
     /**
      * {@inheritdoc}
+     *
+     * @return bool
      */
     public function unlock(CacheKey $key, Lock $lock)
     {

lib/Doctrine/ORM/Configuration.php

@@ -25,8 +25,6 @@ use Doctrine\Common\Annotations\CachedReader;
 use Doctrine\Common\Annotations\SimpleAnnotationReader;
 use Doctrine\Common\Cache\ArrayCache;
 use Doctrine\Common\Cache\Cache as CacheDriver;
-use Doctrine\Common\Persistence\Mapping\Driver\MappingDriver;
-use Doctrine\Common\Persistence\ObjectRepository;
 use Doctrine\Common\Proxy\AbstractProxyFactory;
 use Doctrine\ORM\Cache\CacheConfiguration;
 use Doctrine\ORM\Mapping\ClassMetadataFactory;
@@ -39,6 +37,9 @@ use Doctrine\ORM\Mapping\NamingStrategy;
 use Doctrine\ORM\Mapping\QuoteStrategy;
 use Doctrine\ORM\Repository\DefaultRepositoryFactory;
 use Doctrine\ORM\Repository\RepositoryFactory;
+use Doctrine\Persistence\Mapping\Driver\MappingDriver;
+use Doctrine\Persistence\ObjectRepository;
+use function interface_exists;
 
 /**
  * Configuration container for all configuration options of Doctrine.
@@ -70,6 +71,9 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Gets the directory where Doctrine generates any necessary proxy class files.
      *
      * @return string|null
+     *
+     * @deprecated 2.7 We're switch to `ocramius/proxy-manager` and this method isn't applicable any longer
+     * @see https://github.com/Ocramius/ProxyManager
      */
     public function getProxyDir()
     {
@@ -82,6 +86,9 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Gets the strategy for automatically generating proxy classes.
      *
      * @return int Possible values are constants of Doctrine\Common\Proxy\AbstractProxyFactory.
+     *
+     * @deprecated 2.7 We're switch to `ocramius/proxy-manager` and this method isn't applicable any longer
+     * @see https://github.com/Ocramius/ProxyManager
      */
     public function getAutoGenerateProxyClasses()
     {
@@ -107,6 +114,9 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Gets the namespace where proxy classes reside.
      *
      * @return string|null
+     *
+     * @deprecated 2.7 We're switch to `ocramius/proxy-manager` and this method isn't applicable any longer
+     * @see https://github.com/Ocramius/ProxyManager
      */
     public function getProxyNamespace()
     {
@@ -432,6 +442,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $name
      *
      * @return string|null
+     * @psalm-return ?class-string
      */
     public function getCustomStringFunction($name)
     {
@@ -484,6 +495,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $name
      *
      * @return string|null
+     * @psalm-return ?class-string
      */
     public function getCustomNumericFunction($name)
     {
@@ -524,6 +536,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string|callable $className Class name or a callable that returns the function.
      *
      * @return void
+     *
+     * @psalm-param class-string|callable $className
      */
     public function addCustomDatetimeFunction($name, $className)
     {
@@ -536,6 +550,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $name
      *
      * @return string|null
+     *
+     * @psalm-return ?class-string $name
      */
     public function getCustomDatetimeFunction($name)
     {
@@ -557,6 +573,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param array $functions The map of custom DQL date/time functions.
      *
      * @return void
+     *
+     * @psalm-param array<string, string> $functions
      */
     public function setCustomDatetimeFunctions(array $functions)
     {
@@ -587,6 +605,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $modeName The hydration mode name.
      *
      * @return string|null The hydrator class name.
+     *
+     * @psalm-return ?class-string
      */
     public function getCustomHydrationMode($modeName)
     {
@@ -614,6 +634,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $cmfName
      *
      * @return void
+     *
+     * @psalm-param class-string $cmfName
      */
     public function setClassMetadataFactoryName($cmfName)
     {
@@ -622,6 +644,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
 
     /**
      * @return string
+     *
+     * @psalm-return class-string
      */
     public function getClassMetadataFactoryName()
     {
@@ -648,8 +672,10 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @param string $name The name of the filter.
      *
-     * @return string The class name of the filter, or null if it is not
+     * @return string|null The class name of the filter, or null if it is not
      *  defined.
+     *
+     * @psalm-return ?class-string
      */
     public function getFilterClassName($name)
     {
@@ -667,7 +693,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @return void
      *
-     * @throws ORMException If not is a \Doctrine\Common\Persistence\ObjectRepository
+     * @throws ORMException If $classname is not an ObjectRepository.
      */
     public function setDefaultRepositoryClassName($className)
     {
@@ -686,6 +712,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @since 2.2
      *
      * @return string
+     *
+     * @psalm-return class-string
      */
     public function getDefaultRepositoryClassName()
     {
@@ -909,3 +937,5 @@ class Configuration extends \Doctrine\DBAL\Configuration
         $this->_attributes['defaultQueryHints'][$name] = $value;
     }
 }
+
+interface_exists(MappingDriver::class);

lib/Doctrine/ORM/Decorator/EntityManagerDecorator.php

@@ -21,7 +21,7 @@ namespace Doctrine\ORM\Decorator;
 
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\ORM\EntityManagerInterface;
-use Doctrine\Common\Persistence\ObjectManagerDecorator;
+use Doctrine\Persistence\ObjectManagerDecorator;
 
 /**
  * Base class for EntityManager decorators
@@ -65,7 +65,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
      */
     public function beginTransaction()
     {
-        return $this->wrapped->beginTransaction();
+        $this->wrapped->beginTransaction();
     }
 
     /**
@@ -81,7 +81,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
      */
     public function commit()
     {
-        return $this->wrapped->commit();
+        $this->wrapped->commit();
     }
 
     /**
@@ -89,7 +89,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
      */
     public function rollback()
     {
-        return $this->wrapped->rollback();
+        $this->wrapped->rollback();
     }
 
     /**
@@ -153,7 +153,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
      */
     public function close()
     {
-        return $this->wrapped->close();
+        $this->wrapped->close();
     }
 
     /**
@@ -169,15 +169,15 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
      */
     public function lock($entity, $lockMode, $lockVersion = null)
     {
-        return $this->wrapped->lock($entity, $lockMode, $lockVersion);
+        $this->wrapped->lock($entity, $lockMode, $lockVersion);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function find($entityName, $id, $lockMode = null, $lockVersion = null)
+    public function find($className, $id, $lockMode = null, $lockVersion = null)
     {
-        return $this->wrapped->find($entityName, $id, $lockMode, $lockVersion);
+        return $this->wrapped->find($className, $id, $lockMode, $lockVersion);
     }
 
     /**
@@ -185,7 +185,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
      */
     public function flush($entity = null)
     {
-        return $this->wrapped->flush($entity);
+        $this->wrapped->flush($entity);
     }
 
     /**

lib/Doctrine/ORM/EntityManager.php

@@ -23,11 +23,17 @@ use Doctrine\Common\EventManager;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DriverManager;
 use Doctrine\DBAL\LockMode;
+use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\ORM\Proxy\ProxyFactory;
 use Doctrine\ORM\Query\FilterCollection;
 use Doctrine\Common\Util\ClassUtils;
+use Doctrine\Persistence\Mapping\MappingException;
+use Doctrine\Persistence\ObjectRepository;
 use Throwable;
+use function ltrim;
+use const E_USER_DEPRECATED;
+use function trigger_error;
 
 /**
  * The EntityManager is the central access point to ORM functionality.
@@ -322,7 +328,7 @@ use Throwable;
      */
     public function createNamedNativeQuery($name)
     {
-        list($sql, $rsm) = $this->config->getNamedNativeQuery($name);
+        [$sql, $rsm] = $this->config->getNamedNativeQuery($name);
 
         return $this->createNativeQuery($sql, $rsm);
     }
@@ -353,6 +359,13 @@ use Throwable;
      */
     public function flush($entity = null)
     {
+        if ($entity !== null) {
+            @trigger_error(
+                'Calling ' . __METHOD__ . '() with any arguments to flush specific entities is deprecated and will not be supported in Doctrine ORM 3.0.',
+                E_USER_DEPRECATED
+            );
+        }
+
         $this->errorIfClosed();
 
         $this->unitOfWork->commit($entity);
@@ -361,7 +374,7 @@ use Throwable;
     /**
      * Finds an Entity by its identifier.
      *
-     * @param string       $entityName  The class name of the entity to find.
+     * @param string       $className   The class name of the entity to find.
      * @param mixed        $id          The identity of the entity to find.
      * @param integer|null $lockMode    One of the \Doctrine\DBAL\LockMode::* constants
      *                                  or NULL if no specific lock mode should be used
@@ -376,9 +389,13 @@ use Throwable;
      * @throws TransactionRequiredException
      * @throws ORMException
      */
-    public function find($entityName, $id, $lockMode = null, $lockVersion = null)
+    public function find($className, $id, $lockMode = null, $lockVersion = null)
     {
-        $class = $this->metadataFactory->getMetadataFor(ltrim($entityName, '\\'));
+        $class = $this->metadataFactory->getMetadataFor(ltrim($className, '\\'));
+
+        if ($lockMode !== null) {
+            $this->checkLockRequirements($lockMode, $class);
+        }
 
         if ( ! is_array($id)) {
             if ($class->isIdentifierComposite) {
@@ -441,10 +458,6 @@ use Throwable;
 
         switch (true) {
             case LockMode::OPTIMISTIC === $lockMode:
-                if ( ! $class->isVersioned) {
-                    throw OptimisticLockException::notVersioned($class->name);
-                }
-
                 $entity = $persister->load($sortedId);
 
                 $unitOfWork->lock($entity, $lockMode, $lockVersion);
@@ -453,10 +466,6 @@ use Throwable;
 
             case LockMode::PESSIMISTIC_READ === $lockMode:
             case LockMode::PESSIMISTIC_WRITE === $lockMode:
-                if ( ! $this->getConnection()->isTransactionActive()) {
-                    throw TransactionRequiredException::transactionRequired();
-                }
-
                 return $persister->load($sortedId, null, null, [], $lockMode);
 
             default:
@@ -540,9 +549,9 @@ use Throwable;
      *
      * @return void
      *
-     * @throws ORMInvalidArgumentException                           if a non-null non-string value is given
-     * @throws \Doctrine\Common\Persistence\Mapping\MappingException if a $entityName is given, but that entity is not
-     *                                                               found in the mappings
+     * @throws ORMInvalidArgumentException If a non-null non-string value is given.
+     * @throws MappingException            If a $entityName is given, but that entity is not
+     *                                     found in the mappings.
      */
     public function clear($entityName = null)
     {
@@ -550,6 +559,13 @@ use Throwable;
             throw ORMInvalidArgumentException::invalidEntityName($entityName);
         }
 
+        if ($entityName !== null) {
+            @trigger_error(
+                'Calling ' . __METHOD__ . '() with any arguments to clear specific entities is deprecated and will not be supported in Doctrine ORM 3.0.',
+                E_USER_DEPRECATED
+            );
+        }
+
         $this->unitOfWork->clear(
             null === $entityName
                 ? null
@@ -652,9 +668,13 @@ use Throwable;
      * @return void
      *
      * @throws ORMInvalidArgumentException
+     *
+     * @deprecated 2.7 This method is being removed from the ORM and won't have any replacement
      */
     public function detach($entity)
     {
+        @trigger_error('Method ' . __METHOD__ . '() is deprecated and will be removed in Doctrine ORM 3.0.', E_USER_DEPRECATED);
+
         if ( ! is_object($entity)) {
             throw ORMInvalidArgumentException::invalidObject('EntityManager#detach()', $entity);
         }
@@ -673,9 +693,13 @@ use Throwable;
      *
      * @throws ORMInvalidArgumentException
      * @throws ORMException
+     *
+     * @deprecated 2.7 This method is being removed from the ORM and won't have any replacement
      */
     public function merge($entity)
     {
+        @trigger_error('Method ' . __METHOD__ . '() is deprecated and will be removed in Doctrine ORM 3.0.', E_USER_DEPRECATED);
+
         if ( ! is_object($entity)) {
             throw ORMInvalidArgumentException::invalidObject('EntityManager#merge()', $entity);
         }
@@ -687,12 +711,11 @@ use Throwable;
 
     /**
      * {@inheritDoc}
-     *
-     * @todo Implementation need. This is necessary since $e2 = clone $e1; throws an E_FATAL when access anything on $e:
-     * Fatal error: Maximum function nesting level of '100' reached, aborting!
      */
     public function copy($entity, $deep = false)
     {
+        @trigger_error('Method ' . __METHOD__ . '() is deprecated and will be removed in Doctrine ORM 3.0.', E_USER_DEPRECATED);
+
         throw new \BadMethodCallException("Not implemented.");
     }
 
@@ -709,7 +732,7 @@ use Throwable;
      *
      * @param string $entityName The name of the entity.
      *
-     * @return \Doctrine\Common\Persistence\ObjectRepository|\Doctrine\ORM\EntityRepository The repository class.
+     * @return ObjectRepository|EntityRepository The repository class.
      */
     public function getRepository($entityName)
     {
@@ -915,4 +938,26 @@ use Throwable;
     {
         return null !== $this->filterCollection;
     }
+
+    /**
+     * @param int $lockMode
+     * @param ClassMetadata $class
+     * @throws OptimisticLockException
+     * @throws TransactionRequiredException
+     */
+    private function checkLockRequirements(int $lockMode, ClassMetadata $class): void
+    {
+        switch ($lockMode) {
+            case LockMode::OPTIMISTIC:
+                if (!$class->isVersioned) {
+                    throw OptimisticLockException::notVersioned($class->name);
+                }
+                break;
+            case LockMode::PESSIMISTIC_READ:
+            case LockMode::PESSIMISTIC_WRITE:
+                if (!$this->getConnection()->isTransactionActive()) {
+                    throw TransactionRequiredException::transactionRequired();
+                }
+        }
+    }
 }

lib/Doctrine/ORM/EntityManagerInterface.php

@@ -19,8 +19,8 @@
 
 namespace Doctrine\ORM;
 
-use Doctrine\Common\Persistence\ObjectManager;
 use Doctrine\ORM\Query\ResultSetMapping;
+use Doctrine\Persistence\ObjectManager;
 
 /**
  * EntityManager interface
@@ -174,7 +174,7 @@ interface EntityManagerInterface extends ObjectManager
      * @param string $entityName The name of the entity type.
      * @param mixed  $identifier The entity identifier.
      *
-     * @return object The (partial) entity reference.
+     * @return object|null The (partial) entity reference.
      */
     public function getPartialReference($entityName, $identifier);
 
@@ -190,6 +190,8 @@ interface EntityManagerInterface extends ObjectManager
     /**
      * Creates a copy of the given entity. Can create a shallow or a deep copy.
      *
+     * @deprecated 2.7 This method is being removed from the ORM and won't have any replacement
+     *
      * @param object  $entity The entity to copy.
      * @param boolean $deep   FALSE for a shallow copy, TRUE for a deep copy.
      *
@@ -249,7 +251,7 @@ interface EntityManagerInterface extends ObjectManager
     *
     * @deprecated
     *
-    * @param int $hydrationMode
+    * @param string|int $hydrationMode
     *
     * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator
     */
@@ -258,7 +260,7 @@ interface EntityManagerInterface extends ObjectManager
     /**
      * Create a new instance for the given hydration mode.
      *
-     * @param int $hydrationMode
+     * @param string|int $hydrationMode
      *
      * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator
      *

lib/Doctrine/ORM/EntityRepository.php

@@ -19,11 +19,11 @@
 
 namespace Doctrine\ORM;
 
-use Doctrine\Common\Util\Inflector;
-use Doctrine\ORM\Query\ResultSetMappingBuilder;
-use Doctrine\Common\Persistence\ObjectRepository;
-use Doctrine\Common\Collections\Selectable;
 use Doctrine\Common\Collections\Criteria;
+use Doctrine\Common\Collections\Selectable;
+use Doctrine\Common\Inflector\Inflector;
+use Doctrine\ORM\Query\ResultSetMappingBuilder;
+use Doctrine\Persistence\ObjectRepository;
 
 /**
  * An EntityRepository serves as a repository for entities with generic as well as
@@ -57,9 +57,6 @@ class EntityRepository implements ObjectRepository, Selectable
 
     /**
      * Initializes a new <tt>EntityRepository</tt>.
-     *
-     * @param EntityManager         $em    The EntityManager to use.
-     * @param Mapping\ClassMetadata $class The class descriptor.
      */
     public function __construct(EntityManagerInterface $em, Mapping\ClassMetadata $class)
     {

lib/Doctrine/ORM/Event/LifecycleEventArgs.php

@@ -19,7 +19,7 @@
 
 namespace Doctrine\ORM\Event;
 
-use Doctrine\Common\Persistence\Event\LifecycleEventArgs as BaseLifecycleEventArgs;
+use Doctrine\Persistence\Event\LifecycleEventArgs as BaseLifecycleEventArgs;
 
 /**
  * Lifecycle Events are triggered by the UnitOfWork during lifecycle transitions

lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php

@@ -19,7 +19,7 @@
 
 namespace Doctrine\ORM\Event;
 
-use Doctrine\Common\Persistence\Event\LoadClassMetadataEventArgs as BaseLoadClassMetadataEventArgs;
+use Doctrine\Persistence\Event\LoadClassMetadataEventArgs as BaseLoadClassMetadataEventArgs;
 
 /**
  * Class that holds event arguments for a loadMetadata event.

lib/Doctrine/ORM/Event/OnClassMetadataNotFoundEventArgs.php

@@ -19,9 +19,10 @@
 
 namespace Doctrine\ORM\Event;
 
-use Doctrine\Common\Persistence\Event\ManagerEventArgs;
-use Doctrine\Common\Persistence\Mapping\ClassMetadata;
-use Doctrine\Common\Persistence\ObjectManager;
+use Doctrine\Persistence\Event\ManagerEventArgs;
+use Doctrine\Persistence\Mapping\ClassMetadata;
+use Doctrine\Persistence\ObjectManager;
+use function interface_exists;
 
 /**
  * Class that holds event arguments for a `onClassMetadataNotFound` event.
@@ -84,3 +85,4 @@ class OnClassMetadataNotFoundEventArgs extends ManagerEventArgs
     }
 }
 
+interface_exists(ClassMetadata::class);

lib/Doctrine/ORM/Event/OnClearEventArgs.php

@@ -38,7 +38,7 @@ class OnClearEventArgs extends \Doctrine\Common\EventArgs
     private $em;
 
     /**
-     * @var string
+     * @var string|null
      */
     private $entityClass;
 

lib/Doctrine/ORM/Id/AbstractIdGenerator.php

@@ -27,7 +27,7 @@ abstract class AbstractIdGenerator
      * Generates an identifier for an entity.
      *
      * @param EntityManager $em
-     * @param \Doctrine\ORM\Mapping\Entity $entity
+     * @param object|null $entity
      * @return mixed
      */
     abstract public function generate(EntityManager $em, $entity);
@@ -40,7 +40,7 @@ abstract class AbstractIdGenerator
      * By default, this method returns FALSE. Generators that have this requirement
      * must override this method and return TRUE.
      *
-     * @return boolean
+     * @return bool
      */
     public function isPostInsertGenerator()
     {

lib/Doctrine/ORM/Internal/CommitOrderCalculator.php

@@ -164,6 +164,17 @@ class CommitOrderCalculator
                 case self::IN_PROGRESS:
                     if (isset($adjacentVertex->dependencyList[$vertex->hash]) &&
                         $adjacentVertex->dependencyList[$vertex->hash]->weight < $edge->weight) {
+
+                        // If we have some non-visited dependencies in the in-progress dependency, we
+                        // need to visit them before adding the node.
+                        foreach ($adjacentVertex->dependencyList as $adjacentEdge) {
+                            $adjacentEdgeVertex = $this->nodeList[$adjacentEdge->to];
+
+                            if ($adjacentEdgeVertex->state === self::NOT_VISITED) {
+                                $this->visit($adjacentEdgeVertex);
+                            }
+                        }
+
                         $adjacentVertex->state = self::VISITED;
 
                         $this->sortedNodeList[] = $adjacentVertex->value;

lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php

@@ -23,7 +23,10 @@ use Doctrine\DBAL\Types\Type;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\Events;
 use Doctrine\ORM\Mapping\ClassMetadata;
+use Doctrine\ORM\Tools\Pagination\LimitSubqueryWalker;
 use PDO;
+use function array_map;
+use function in_array;
 
 /**
  * Base class for all hydrators. A hydrator is a class that provides some form
@@ -225,14 +228,14 @@ abstract class AbstractHydrator
      *
      * Template method.
      *
-     * @param array $data   The row data.
-     * @param array $result The result to fill.
+     * @param mixed[] $row    The row data.
+     * @param mixed[] $result The result to fill.
      *
      * @return void
      *
      * @throws HydrationException
      */
-    protected function hydrateRowData(array $data, array &$result)
+    protected function hydrateRowData(array $row, array &$result)
     {
         throw new HydrationException("hydrateRowData() not implemented by this hydrator.");
     }
@@ -257,8 +260,19 @@ abstract class AbstractHydrator
      * @param array &$id                 Dql-Alias => ID-Hash.
      * @param array &$nonemptyComponents Does this DQL-Alias has at least one non NULL value?
      *
-     * @return array  An array with all the fields (name => value) of the data row,
-     *                grouped by their component alias.
+     * @return array<string, array<string, mixed>> An array with all the fields
+     *                                             (name => value) of the data
+     *                                             row, grouped by their
+     *                                             component alias.
+     *
+     * @psalm-return array{
+     *                   data: array<array-key, array>,
+     *                   newObjects?: array<array-key, array{
+     *                       class: mixed,
+     *                       args?: array
+     *                   }>,
+     *                   scalars?: array
+     *               }
      */
     protected function gatherRowData(array $data, array &$id, array &$nonemptyComponents)
     {
@@ -296,11 +310,8 @@ abstract class AbstractHydrator
 
                     // If there are field name collisions in the child class, then we need
                     // to only hydrate if we are looking at the correct discriminator value
-                    if(
-                        isset($cacheKeyInfo['discriminatorColumn']) && 
-                        isset($data[$cacheKeyInfo['discriminatorColumn']]) &&
-                        // Note: loose comparison required. See https://github.com/doctrine/doctrine2/pull/6304#issuecomment-323294442
-                        $data[$cacheKeyInfo['discriminatorColumn']] != $cacheKeyInfo['discriminatorValue']
+                    if (isset($cacheKeyInfo['discriminatorColumn'], $data[$cacheKeyInfo['discriminatorColumn']])
+                        && ! in_array((string) $data[$cacheKeyInfo['discriminatorColumn']], $cacheKeyInfo['discriminatorValues'], true)
                     ) {
                         break;
                     }
@@ -352,13 +363,11 @@ abstract class AbstractHydrator
 
             // WARNING: BC break! We know this is the desired behavior to type convert values, but this
             // erroneous behavior exists since 2.0 and we're forced to keep compatibility.
-            if ( ! isset($cacheKeyInfo['isScalar'])) {
-                $dqlAlias  = $cacheKeyInfo['dqlAlias'];
-                $type      = $cacheKeyInfo['type'];
-                $fieldName = $dqlAlias . '_' . $fieldName;
-                $value     = $type
-                    ? $type->convertToPHPValue($value, $this->_platform)
-                    : $value;
+            if (! isset($cacheKeyInfo['isScalar'])) {
+                $type  = $cacheKeyInfo['type'];
+                $value = $type ? $type->convertToPHPValue($value, $this->_platform) : $value;
+
+                $fieldName = $cacheKeyInfo['dqlAlias'] . '_' . $fieldName;
             }
 
             $rowData[$fieldName] = $value;
@@ -401,7 +410,8 @@ abstract class AbstractHydrator
                         $columnInfo,
                         [
                             'discriminatorColumn' => $this->_rsm->discriminatorColumns[$ownerMap],
-                            'discriminatorValue'  => $classMetadata->discriminatorValue
+                            'discriminatorValue'  => $classMetadata->discriminatorValue,
+                            'discriminatorValues' => $this->getDiscriminatorValues($classMetadata),
                         ]
                     );
                 }
@@ -422,6 +432,12 @@ abstract class AbstractHydrator
                     'class'                => new \ReflectionClass($mapping['className']),
                 ];
 
+            case isset($this->_rsm->scalarMappings[$key], $this->_hints[LimitSubqueryWalker::FORCE_DBAL_TYPE_CONVERSION]):
+                return $this->_cache[$key] = [
+                    'fieldName' => $this->_rsm->scalarMappings[$key],
+                    'type'      => Type::getType($this->_rsm->typeMappings[$key]),
+                    'dqlAlias'  => '',
+                ];
             case (isset($this->_rsm->scalarMappings[$key])):
                 return $this->_cache[$key] = [
                     'isScalar'  => true,
@@ -454,6 +470,23 @@ abstract class AbstractHydrator
         return null;
     }
 
+    /**
+     * @return string[]
+     */
+    private function getDiscriminatorValues(ClassMetadata $classMetadata) : array
+    {
+        $values = array_map(
+            function (string $subClass) : string {
+                return (string) $this->getClassMetadata($subClass)->discriminatorValue;
+            },
+            $classMetadata->subClasses
+        );
+
+        $values[] = (string) $classMetadata->discriminatorValue;
+
+        return $values;
+    }
+
     /**
      * Retrieve ClassMetadata associated to entity class name.
      *

lib/Doctrine/ORM/Internal/Hydration/ObjectHydrator.php

@@ -422,7 +422,7 @@ class ObjectHydrator extends AbstractHydrator
                             $this->resultPointers[$dqlAlias] = $reflFieldValue[$index];
                         }
                     } else if ( ! $reflFieldValue) {
-                        $reflFieldValue = $this->initRelatedCollection($parentObject, $parentClass, $relationField, $parentAlias);
+                        $this->initRelatedCollection($parentObject, $parentClass, $relationField, $parentAlias);
                     } else if ($reflFieldValue instanceof PersistentCollection && $reflFieldValue->isInitialized() === false) {
                         $reflFieldValue->setInitialized(true);
                     }