8000 Improve overall DBAL raised Events documentation by SenseException · Pull Request #2322 · doctrine/dbal · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Improve overall DBAL raised Events documentation #2322

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 19, 2016
Merged

Improve overall DBAL raised Events documentation #2322

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ea473f7
Add Schema events skeleton and documentation of onSchemaCreateTable
SenseException Feb 9, 2016
aa996d3
Add documentation of onSchemaCreateTableColumn, onSchemaDropTable and…
SenseException Feb 10, 2016
afe281f
Add description for OnSchemaAlterTableAddColumn, OnSchemaAlterTableRe…
SenseException Feb 15, 2016
7f14180
Add description for onSchemaColumnDefinition and onSchemaIndexDefinition
SenseException Feb 18, 2016
3588157
Add info about columns and indexes completeness
SenseException Feb 18, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
298 changes: 298 additions & 0 deletions docs/en/reference/events.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
0