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 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +