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()``