[TASK] Fix spelling issues
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 8.1 / Feature-75454-DoctrineDBALForDatabaseConnections.rst
1 =========================================================================================
2 Feature: #75454 - Added PHP library "Doctrine DBAL" for Database Connections within TYPO3
3 =========================================================================================
4
5 Description
6 ===========
7
8 The PHP library ``Doctrine DBAL`` has been added via composer dependency to work as a powerful database
9 abstraction layer with many features for database abstraction, schema introspection and
10 schema management within TYPO3.
11
12 A TYPO3-specific PHP class called ``TYPO3\CMS\Core\Database\ConnectionPool`` has been added as a
13 manager for database connections.
14
15 All connections configured below ``$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']`` are
16 accessible using this manager, enabling the parallel usage of multiple database systems.
17
18 By using the database abstraction options and the QueryBuilder provided SQL statements being
19 built will be properly quoted and compatible with different DBMS out of the box as far as
20 possible.
21
22 Existing ``$GLOBALS['TYPO3_CONF_VARS']['DB']`` options have been removed and/or migrated to the
23 new Doctrine-compliant options.
24
25 Documentation for Doctrine DBAL can be found at http://www.doctrine-project.org/projects/dbal.html.
26
27 The :php:``Connection`` class provides convenience methods for ``insert``, ``select``, ``update``,
28 ``delete``and ``truncate`` statements. For ``select``, ``update`` an ``delete`` only simple
29 equality comparisons (``WHERE "aField" = 'aValue') are supported. For complex statements it's
30 required to use the :php:``QueryBuilder``.
31
32 It is possible to swap tables out of the default database and use a specific setup (e.g.
33 for logging or caching). This snippet of a LocalConfiguration could for exampe be used
34 to swap the sys_log table out to another database or even another database server:
35
36 .. code-block:: php
37
38     //LocalConfiguration.php
39     //[...]
40     'DB' => [
41         'Connections' => [
42             'Default' => [
43                 'charset' => 'utf8',
44                 'dbname' => 'default_dbname',
45                 'driver' => 'mysqli',
46                 'host' => 'default_host',
47                 'password' => '***',
48                 'port' => 3306,
49                 'user' => 'default_user',
50             ],
51             'Syslog' => [
52                 'charset' => 'utf8',
53                 'dbname' => 'syslog_dbname',
54                 'driver' => 'mysqli',
55                 'host' => 'syslog_host',
56                 'password' => '***',
57                 'port' => 3306,
58                 'user' => 'syslog_user',
59             ],
60         ],
61         'TableMapping' => [
62             'sys_log' => 'Syslog'
63         ]
64     ],
65     //[...]
66
67 Impact
68 ======
69
70 Currently the :php:``DatabaseConnection`` class only uses Doctrine to establish the database
71 connection to MySQL, no advanced options are being used yet.
72
73 Connections always need to be requested with a table name so that the abstraction of
74 table names to database connections stays intact.
75
76 The :php:``ConnectionPool`` class can be used like this:
77
78 .. code-block:: php
79
80    // Get a connection which can be used for multiple operations
81    /** @var \TYPO3\CMS\Core\Database\Connecction $conn */
82    $conn = GeneralUtility::makeInstance(ConnectionPool::class)->getConnectionForTable('aTable');
83    $affectedRows = $conn->insert(
84       'aTable',
85       $fields, // Associative array of column/value pairs, automatically quoted & escaped
86    );
87
88 .. code-block:: php
89
90    // Get a QueryBuilder, which should only be used a single time
91    $query = GeneralUtility::makeInstance(ConnectionPool::class)->getQueryBuilderForTable('aTable);
92    $query->select('*')
93       ->from('aTable)
94       ->where(
95          $query->expr()->eq('aField', $query->createNamedParameter($aValue)),
96          $query->expr()->lte(
97             'anotherField',
98             $query->createNamedParameter($anotherValue)
99          )
100       );
101    $rows = $query->execute()->fetchAll();
102
103 Extension authors are advised to use the ``ConnectionPool`` and ``Connection`` classes instead of using
104 the Doctrine DBAL directly in order to ensure a clear upgrade path when updates to the underlying
105 API need to be done.
106
107 .. index:: php