diff --git a/.doctrine-project.json b/.doctrine-project.json
index 61cd9f998ff..526804a81f3 100644
--- a/.doctrine-project.json
+++ b/.doctrine-project.json
@@ -5,15 +5,24 @@
"slug": "dbal",
"docsSlug": "doctrine-dbal",
"versions": [
+ {
+ "name": "4.0",
+ "branchName": "4.0.x",
+ "slug": "latest",
+ "upcoming": true
+ },
+ {
+ "name": "3.5",
+ "branchName": "3.5.x",
+ "slug": "3.5",
+ "upcoming": true
+ },
{
"name": "3.4",
"branchName": "3.4.x",
- "slug": "latest",
+ "slug": "current",
"current": true,
- "aliases": [
- "current",
- "stable"
- ]
+ "aliases": ["stable"]
},
{
"name": "3.3",
diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml
index 809761e0418..26b5a7f6568 100644
--- a/.github/workflows/continuous-integration.yml
+++ b/.github/workflows/continuous-integration.yml
@@ -213,11 +213,11 @@ jobs:
- "8.1"
postgres-version:
- "10"
- - "13"
- "14"
+ - "15"
include:
- php-version: "8.2"
- postgres-version: "14"
+ postgres-version: "15"
services:
postgres:
diff --git a/UPGRADE.md b/UPGRADE.md
index 63c9ad4820f..666851236c6 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -833,6 +833,67 @@ The following methods have been removed.
# Upgrade to 3.5
+## Deprecated extension via Doctrine Event Manager
+
+Extension of the library behavior via Doctrine Event Manager has been deprecated.
+
+The following methods and properties have been deprecated:
+- `AbstractPlatform::$_eventManager`,
+- `AbstractPlatform::getEventManager()`,
+- `AbstractPlatform::setEventManager()`,
+- `Connection::$_eventManager`,
+- `Connection::getEventManager()`.
+
+## Deprecated extension via connection events
+
+Subscription to the `postConnect` event has been deprecated. Use one of the following replacements for the standard
+event listeners or implement a custom middleware instead.
+
+The following `postConnect` event listeners have been deprecated:
+1. `OracleSessionInit`. Use `Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession`.
+2. `SQLiteSessionInit`. Use `Doctrine\DBAL\Driver\AbstractSQLiteDriver\Middleware\EnableForeignKeys`.
+3. `SQLSessionInit`. Implement a custom middleware.
+
+## Deprecated extension via transaction events
+
+Subscription to the following events has been deprecated:
+- `onTransactionBegin`,
+- `onTransactionCommit`,
+- `onTransactionRollBack`.
+
+The upgrade path will depend on the use case:
+1. If you need to extend the behavior of only the actual top-level transactions (not the ones emulated via savepoints),
+ implement a driver middleware.
+2. If you need to extend the behavior of the top-level and nested transactions, either implement a driver middleware
+ or implement a custom wrapper connection.
+
+## Deprecated extension via schema definition events
+
+Subscription to the following events has been deprecated:
+- `onSchemaColumnDefinition`,
+- `onSchemaIndexDefinition`.
+
+Use a custom schema manager instead.
+
+## Deprecated extension via schema manipulation events
+
+Subscription to the following events has been deprecated:
+- `onSchemaCreateTable`,
+- `onSchemaCreateTableColumn`,
+- `onSchemaDropTable`,
+- `onSchemaAlterTable`,
+- `onSchemaAlterTableAddColumn`,
+- `onSchemaAlterTableRemoveColumn`,
+- `onSchemaAlterTableChangeColumn`,
+- `onSchemaAlterTableRenameColumn`.
+
+The upgrade path will depend on the use case:
+1. If you are using the events to modify the behavior of the platform, you should extend the platform class
+ and implement the corresponding logic in the sub-class.
+2. If you are using the events to modify the arguments processed by the platform (e.g. modify the table definition
+ before the platform generates the `CREATE TABLE` DDL), you should do the needed modifications before calling
+ the corresponding platform or schema manager method.
+
## Deprecated the emulation of the `LOCATE()` function for SQLite
Relying on the availability of the `LOCATE()` on SQLite deprecated. SQLite does not provide that function natively,
@@ -1118,6 +1179,8 @@ Bind parameters using `Statement::bindParam()` or `Statement::bindValue()` inste
1. The `QueryBuilder::getState()` method has been deprecated as the builder state is an internal concern.
2. Relying on the type of the query being built by using `QueryBuilder::getType()` has been deprecated.
If necessary, track the type of the query being built outside of the builder.
+3. The `QueryBuilder::getConnection()` method has been deprecated. Use the connection used to instantiate the builder
+ instead.
The following `QueryBuilder` constants related to the above methods have been deprecated:
diff --git a/ci/github/phpunit/oci8.xml b/ci/github/phpunit/oci8.xml
index fcb0d5423ff..d8e1d99fbf7 100644
--- a/ci/github/phpunit/oci8.xml
+++ b/ci/github/phpunit/oci8.xml
@@ -17,7 +17,6 @@
-
diff --git a/ci/github/phpunit/pdo_oci.xml b/ci/github/phpunit/pdo_oci.xml
index 00daa7f2cd9..ef1e272e5e0 100644
--- a/ci/github/phpunit/pdo_oci.xml
+++ b/ci/github/phpunit/pdo_oci.xml
@@ -17,7 +17,6 @@
-
diff --git a/ci/github/phpunit/pdo_sqlite.xml b/ci/github/phpunit/pdo_sqlite.xml
index 2ff89cc6f10..ad374f5d3df 100644
--- a/ci/github/phpunit/pdo_sqlite.xml
+++ b/ci/github/phpunit/pdo_sqlite.xml
@@ -13,7 +13,6 @@
-
diff --git a/ci/github/phpunit/sqlite3.xml b/ci/github/phpunit/sqlite3.xml
index 3c58120444c..09a27e9c223 100644
--- a/ci/github/phpunit/sqlite3.xml
+++ b/ci/github/phpunit/sqlite3.xml
@@ -13,7 +13,6 @@
-
diff --git a/composer.json b/composer.json
index 2f7a114670a..8a4434784a2 100644
--- a/composer.json
+++ b/composer.json
@@ -41,7 +41,7 @@
"require-dev": {
"doctrine/coding-standard": "10.0.0",
"jetbrains/phpstorm-stubs": "2022.2",
- "phpstan/phpstan": "1.8.8",
+ "phpstan/phpstan": "1.8.10",
"phpstan/phpstan-phpunit": "1.1.1",
"phpstan/phpstan-strict-rules": "^1.4",
"phpunit/phpunit": "9.5.25",
@@ -49,7 +49,7 @@
"squizlabs/php_codesniffer": "3.7.1",
"symfony/cache": "^5.4|^6.0",
"symfony/console": "^4.4.30|^5.4|^6.0",
- "vimeo/psalm": "4.28.0"
+ "vimeo/psalm": "4.29.0"
},
"suggest": {
"symfony/console": "For helpful console commands such as SQL execution and import of files."
diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst
deleted file mode 100644
index 3495a6fc760..00000000000
--- a/docs/en/reference/events.rst
+++ /dev/null
@@ -1,417 +0,0 @@
-Events
-======
-
-Both ``Doctrine\DBAL\DriverManager`` and
-``Doctrine\DBAL\Connection`` accept an instance of
-``Doctrine\Common\EventManager``. The EventManager has a couple of
-events inside the DBAL layer that are triggered for the user to
-listen to.
-
-PostConnect Event
------------------
-
-``Doctrine\DBAL\Events::postConnect`` is triggered right after the
-connection to the database is established. It allows to specify any
-relevant connection specific options and gives access to the
-``Doctrine\DBAL\Connection`` instance that is responsible for the
-connection management via an instance of
-``Doctrine\DBAL\Event\ConnectionEventArgs`` event arguments
-instance.
-
-Doctrine ships with one implementation for the "PostConnect" event:
-
-- ``Doctrine\DBAL\Event\Listeners\OracleSessionInit`` allows to
- specify any number of Oracle Session related environment variables
- that are set right after the connection is established.
-
-You can register events by subscribing them to the ``EventManager``
-instance passed to the Connection factory:
-
-.. code-block:: php
-
- addEventSubscriber(new OracleSessionInit([
- 'NLS_TIME_FORMAT' => 'HH24:MI:SS',
- ]));
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-Schema Events
--------------
-
-There are multiple events in Doctrine DBAL that are triggered on schema changes
-of the database. It is possible to add your own event listener to be able to run
-your own code before changes to the database are committed. An instance of
-``Doctrine\Common\EventManager`` can also be added to :doc:`platforms`.
-
-A event listener class can contain one or more methods to schema events. These
-methods must be named like the events itself.
-
-.. code-block:: php
-
- addEventListener($eventName, new MyEventListener());
-
-.. code-block:: php
-
- addEventListener($eventNames, new MyEventListener());
-
-The following events are available.
-
-OnSchemaCreateTable Event
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onSchemaCreateTable`` is triggered before every
-create statement that is executed by one of the Platform instances and injects
-an instance of ``Doctrine\DBAL\Event\SchemaCreateTableEventArgs`` as event argument
-for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onSchemaCreateTable, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Schema\Table`` instance and its columns, the used Platform and
-provides a way to add additional SQL statements.
-
-OnSchemaCreateTableColumn Event
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onSchemaCreateTableColumn`` is triggered on every new column before a
-create statement that is executed by one of the Platform instances and injects
-an instance of ``Doctrine\DBAL\Event\SchemaCreateTableColumnEventArgs`` as event argument
-for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onSchemaCreateTableColumn, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Schema\Table`` instance, the affected ``Doctrine\DBAL\Schema\Column``,
-the used Platform and provides a way to add additional SQL statements.
-
-OnSchemaDropTable Event
-^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onSchemaDropTable`` is triggered before a drop table
-statement that is executed by one of the Platform instances and injects
-an instance of ``Doctrine\DBAL\Event\SchemaDropTableEventArgs`` as event argument
-for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onSchemaDropTable, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Schema\Table`` instance, the used Platform and
-provides a way to set an additional SQL statement.
-
-OnSchemaAlterTable Event
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onSchemaAlterTable`` is triggered before every
-alter statement that is executed by one of the Platform instances and injects
-an instance of ``Doctrine\DBAL\Event\SchemaAlterTableEventArgs`` as event argument
-for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onSchemaAlterTable, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Schema\TableDiff`` instance, the used Platform and
-provides a way to add additional SQL statements.
-
-OnSchemaAlterTableAddColumn Event
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onSchemaAlterTableAddColumn`` is triggered on every altered column before every
-alter statement that is executed by one of the Platform instances and injects
-an instance of ``Doctrine\DBAL\Event\SchemaAlterTableAddColumnEventArgs`` as event argument
-for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onSchemaAlterTableAddColumn, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Schema\TableDiff`` instance, the affected ``Doctrine\DBAL\Schema\Column``,
-the used Platform and provides a way to add additional SQL statements.
-
-OnSchemaAlterTableRemoveColumn Event
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onSchemaAlterTableRemoveColumn`` is triggered on every column that is going to be removed
-before every alter-drop statement that is executed by one of the Platform instances and injects
-an instance of ``Doctrine\DBAL\Event\SchemaAlterTableRemoveColumnEventArgs`` as event argument
-for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onSchemaAlterTableRemoveColumn, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Schema\TableDiff`` instance, the affected ``Doctrine\DBAL\Schema\Column``,
-the used Platform and provides a way to add additional SQL statements.
-
-OnSchemaAlterTableChangeColumn Event
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onSchemaAlterTableChangeColumn`` is triggered on every column that is going to be changed
-before every alter statement that is executed by one of the Platform instances and injects
-an instance of ``Doctrine\DBAL\Event\SchemaAlterTableRemoveColumnEventArgs`` as event argument
-for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onSchemaAlterTableChangeColumn, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Schema\TableDiff`` instance, a ``Doctrine\DBAL\Schema\ColumnDiff`` of
-the affected column, the used Platform and provides a way to add additional SQL statements.
-
-OnSchemaAlterTableRenameColumn Event
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onSchemaAlterTableRenameColumn`` is triggered on every column that is going to be renamed
-before every alter statement that is executed by one of the Platform instances and injects
-an instance of ``Doctrine\DBAL\Event\SchemaAlterTableRenameColumnEventArgs`` as event argument
-for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onSchemaAlterTableRenameColumn, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Schema\TableDiff`` instance, the old column name and
-the new column in form of a ``Doctrine\DBAL\Schema\Column`` object, the used Platform and provides
-a way to add additional SQL statements.
-
-OnSchemaColumnDefinition Event
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onSchemaColumnDefinition`` is triggered on a schema update and is
-executed for every existing column definition of the database before changes are applied.
-An instance of ``Doctrine\DBAL\Event\SchemaColumnDefinitionEventArgs`` is injected as argument
-for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onSchemaColumnDefinition, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the table column definitions of the current database, table name, Platform and
-``Doctrine\DBAL\Connection`` instance. Columns, that are about to be added, are not listed.
-
-OnSchemaIndexDefinition Event
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onSchemaIndexDefinition`` is triggered on a schema update and is
-executed for every existing index definition of the database before changes are applied.
-An instance of ``Doctrine\DBAL\Event\SchemaIndexDefinitionEventArgs`` is injected as argument
-for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onSchemaIndexDefinition, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the table index definitions of the current database, table name, Platform and
-``Doctrine\DBAL\Connection`` instance. Indexes, that are about to be added, are not listed.
-
-OnTransactionBegin Event
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onTransactionBegin`` is triggered when ``Doctrine\DBAL\Connection::beginTransaction()``
-is called. An instance of ``Doctrine\DBAL\Event\TransactionBeginEventArgs`` is injected as argument for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onTransactionBegin, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Connection`` instance.
-Please note that this event can be called multiple times, since transactions can be nested.
-
-OnTransactionCommit Event
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onTransactionCommit`` is triggered when ``Doctrine\DBAL\Connection::commit()`` is called.
-An instance of ``Doctrine\DBAL\Event\TransactionCommitEventArgs`` is injected as argument for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onTransactionCommit, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Connection`` instance.
-Please note that this event can be called multiple times, since transactions can be nested.
-If you want to know if a transaction is actually committed, you should rely on
-``TransactionCommitEventArgs::getConnection()->getTransactionNestingLevel() === 0`` or
-``TransactionCommitEventArgs::getConnection()->isTransactionActive()``
-
-OnTransactionRollBack Event
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``Doctrine\DBAL\Events::onTransactionRollBack`` is triggered when ``Doctrine\DBAL\Connection::rollBack()`` is called.
-An instance of ``Doctrine\DBAL\Event\TransactionRollBackEventArgs`` is injected as argument for event listeners.
-
-.. code-block:: php
-
- addEventListener(Events::onTransactionRollBack, new MyEventListener());
-
- $conn = DriverManager::getConnection($connectionParams, null, $evm);
-
-It allows you to access the ``Doctrine\DBAL\Connection`` instance.
-Please note that this event can be called multiple times, since transactions can be nested.
-If you want to know if a transaction is actually rolled back, you should rely on
-``TransactionCommitRollBackArgs::getConnection()->getTransactionNestingLevel() === 0`` or
-``TransactionCommitRollBackArgs::getConnection()->isTransactionActive()``
diff --git a/docs/en/sidebar.rst b/docs/en/sidebar.rst
index 4f69c3aa456..d879ead9b63 100644
--- a/docs/en/sidebar.rst
+++ b/docs/en/sidebar.rst
@@ -11,7 +11,6 @@
reference/types
reference/schema-manager
reference/schema-representation
- reference/events
reference/security
reference/supporting-other-databases
reference/portability
diff --git a/psalm.xml.dist b/psalm.xml.dist
index 0de81952fd5..6ea37fdf0b2 100644
--- a/psalm.xml.dist
+++ b/psalm.xml.dist
@@ -32,6 +32,52 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+