Skip to content

D
doctrine-dbal
Commit caec2672 authored by Marco Pivetta's avatar Marco Pivetta Committed by GitHub
Browse files
Options

Merge pull request #2322 from SenseException/events-doc 

[Documentation] Extend Events documentation
parents 7d01ce70 35881573
Show whitespace changes
Inline Side-by-side
Showing with 298 additions and 0 deletions
docs/en/reference/events.rst
View file @ caec2672
......@@ -39,3 +39,301 @@ instance passed to the Connection factory:
$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 commited. 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
<?php
$evm = new EventManager();
$eventName = Events::onSchemaCreateTable;
$evm->addEventListener($eventName, new MyEventListener());
.. code-block:: php
<?php
$evm = new EventManager();
$eventNames = array(Events::onSchemaCreateTable, Events::onSchemaCreateTableColumn);
$evm->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
<?php
class MyEventListener
{
public function onSchemaCreateTable(SchemaCreateTableEventArgs $event)
{
// Your EventListener code
}
}
$evm = new EventManager();
$evm->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
<?php
class MyEventListener
{
public function onSchemaCreateTableColumn(SchemaCreateTableColumnEventArgs $event)
{
// Your EventListener code
}
}
$evm = new EventManager();
$evm->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
<?php
class MyEventListener
{
public function onSchemaDropTable(SchemaDropTableEventArgs $event)
{
// Your EventListener code
}
}
$evm = new EventManager();
$evm->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
<?php
class MyEventListener
{
public function onSchemaAlterTable(SchemaAlterTableEventArgs $event)
{
// Your EventListener code
}
}
$evm = new EventManager();
$evm->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
<?php
class MyEventListener
{
public function onSchemaAlterTableAddColumn(SchemaAlterTableAddColumnEventArgs $event)
{
// Your EventListener code
}
}
$evm = new EventManager();
$evm->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
<?php
class MyEventListener
{
public function onSchemaAlterTableRemoveColumn(SchemaAlterTableRemoveColumnEventArgs $event)
{
// Your EventListener code
}
}
$evm = new EventManager();
$evm->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
<?php
class MyEventListener
{
public function onSchemaAlterTableChangeColumn(SchemaAlterTableChangeColumnEventArgs $event)
{
// Your EventListener code
}
}
$evm = new EventManager();
$evm->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
<?php
class MyEventListener
{
public function onSchemaAlterTableRenameColumn(SchemaAlterTableRenameColumnEventArgs $event)
{
// Your EventListener code
}
}
$evm = new EventManager();
$evm->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
<?php
class MyEventListener
{
public function onSchemaColumnDefinition(SchemaColumnDefinitionEventArgs $event)
{
// Your EventListener code
}
}
$evm = new EventManager();
$evm->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
<?php
class MyEventListener
{
public function onSchemaIndexDefinition(SchemaIndexDefinitionEventArgs $event)
{
// Your EventListener code
}
}
$evm = new EventManager();
$evm->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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment