Skip to content

Commit 01e837f

Browse files
morozovmorozov
committed
Deprecate extension via connection events
1 parent 946db1d commit 01e837f

File tree

17 files changed

+130
-65
lines changed

17 files changed

+130
-65
lines changed

‎UPGRADE.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,16 @@ awareness about deprecated code.
88

99
# Upgrade to 3.5
1010

11+
## Deprecated extension via connection events
12+
13+
Subscription to the `postConnect` event has been deprecated. Use one of the following replacements for the standard
14+
event listeners or implement a custom middleware instead.
15+
16+
The following `postConnect` event listeners have been deprecated:
17+
1. `OracleSessionInit`. Use `Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession`.
18+
2. `SQLiteSessionInit`. Use `Doctrine\DBAL\Driver\AbstractSQLiteDriver\Middleware\EnableForeignKeys`.
19+
3. `SQLSessionInit`. Implement a custom middleware.
20+
1121
## Deprecated extension via transaction events
1222

1323
Subscription to the following events has been deprecated:

‎ci/github/phpunit/oci8.xml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@
1717
<var name="db_password" value="oracle"/>
1818
<var name="db_dbname" value="XE"/>
1919
<var name="db_charset" value="AL32UTF8" />
20-
<var name="db_event_subscribers" value="Doctrine\DBAL\Event\Listeners\OracleSessionInit"/>
2120

2221
<var name="tmpdb_driver" value="oci8"/>
2322
<var name="tmpdb_host" value="localhost"/>

‎ci/github/phpunit/pdo_oci.xml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@
1717
<var name="db_password" value="oracle"/>
1818
<var name="db_dbname" value="XE"/>
1919
<var name="db_charset" value="AL32UTF8" />
20-
<var name="db_event_subscribers" value="Doctrine\DBAL\Event\Listeners\OracleSessionInit"/>
2120

2221
<var name="tmpdb_driver" value="pdo_oci"/>
2322
<var name="tmpdb_host" value="localhost"/>

‎ci/github/phpunit/pdo_sqlite.xml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@
1313

1414
<var name="db_driver" value="pdo_sqlite"/>
1515
<var name="db_memory" value="true"/>
16-
<var name="db_event_subscribers" value="Doctrine\DBAL\Event\Listeners\SQLiteSessionInit"/>
1716
</php>
1817

1918
<testsuites>

‎ci/github/phpunit/sqlite3.xml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@
1313

1414
<var name="db_driver" value="sqlite3"/>
1515
<var name="db_memory" value="true"/>
16-
<var name="db_event_subscribers" value="Doctrine\DBAL\Event\Listeners\SQLiteSessionInit"/>
1716
</php>
1817

1918
<testsuites>

‎docs/en/reference/events.rst

Lines changed: 0 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -7,36 +7,6 @@ Both ``Doctrine\DBAL\DriverManager`` and
77
events inside the DBAL layer that are triggered for the user to
88
listen to.
99

10-
PostConnect Event
11-
-----------------
12-
13-
``Doctrine\DBAL\Events::postConnect`` is triggered right after the
14-
connection to the database is established. It allows to specify any
15-
relevant connection specific options and gives access to the
16-
``Doctrine\DBAL\Connection`` instance that is responsible for the
17-
connection management via an instance of
18-
``Doctrine\DBAL\Event\ConnectionEventArgs`` event arguments
19-
instance.
20-
21-
Doctrine ships with one implementation for the "PostConnect" event:
22-
23-
- ``Doctrine\DBAL\Event\Listeners\OracleSessionInit`` allows to
24-
specify any number of Oracle Session related environment variables
25-
that are set right after the connection is established.
26-
27-
You can register events by subscribing them to the ``EventManager``
28-
instance passed to the Connection factory:
29-
30-
.. code-block:: php
31-
32-
<?php
33-
$evm = new EventManager();
34-
$evm->addEventSubscriber(new OracleSessionInit([
35-
'NLS_TIME_FORMAT' => 'HH24:MI:SS',
36-
]));
37-
38-
$conn = DriverManager::getConnection($connectionParams, null, $evm);
39-
4010
Schema Events
4111
-------------
4212

‎psalm.xml.dist

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,10 @@
118118
<referencedClass name="Doctrine\DBAL\Event\TransactionBeginEventArgs"/>
119119
<referencedClass name="Doctrine\DBAL\Event\TransactionCommitEventArgs"/>
120120
<referencedClass name="Doctrine\DBAL\Event\TransactionRollBackEventArgs"/>
121+
<referencedClass name="Doctrine\DBAL\Event\ConnectionEventArgs"/>
122+
<referencedClass name="Doctrine\DBAL\Event\Listeners\OracleSessionInit"/>
123+
<referencedClass name="Doctrine\DBAL\Event\Listeners\SQLSessionInit"/>
124+
<referencedClass name="Doctrine\DBAL\Event\Listeners\SQLiteSessionInit"/>
121125
</errorLevel>
122126
</DeprecatedClass>
123127
<DeprecatedConstant>
@@ -142,9 +146,15 @@
142146
TODO: remove in 4.0.0
143147
-->
144148
<file name="src/Connection.php"/>
149+
<file name="src/Connections/PrimaryReadReplicaConnection.php"/>
150+
<file name="src/Event/Listeners/OracleSessionInit.php"/>
151+
<file name="src/Event/Listeners/SQLSessionInit.php"/>
152+
<file name="src/Event/Listeners/SQLiteSessionInit.php"/>
145153
<file name="src/Platforms/AbstractPlatform.php"/>
146154
<file name="src/Schema/AbstractSchemaManager.php"/>
147155
<file name="tests/ConnectionTest.php"/>
156+
<file name="tests/Events/OracleSessionInitTest.php"/>
157+
<file name="tests/Events/SQLSessionInitTest.php"/>
148158
<file name="tests/Functional/Schema/SchemaManagerFunctionalTestCase.php"/>
149159
<file name="tests/Platforms/AbstractPlatformTestCase.php"/>
150160
</errorLevel>

‎src/Connection.php

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -340,6 +340,13 @@ public function connect()
340340
}
341341

342342
if ($this->_eventManager->hasListeners(Events::postConnect)) {
343+
Deprecation::trigger(
344+
'doctrine/dbal',
345+
'https://github.com/doctrine/dbal/issues/5784',
346+
'Subscribing to %s events is deprecated. Implement a middleware instead.',
347+
Events::postConnect,
348+
);
349+
343350
$eventArgs = new Event\ConnectionEventArgs($this);
344351
$this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
345352
}

‎src/Connections/PrimaryReadReplicaConnection.php

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
use Doctrine\DBAL\Events;
1414
use Doctrine\DBAL\Exception;
1515
use Doctrine\DBAL\Statement;
16+
use Doctrine\Deprecations\Deprecation;
1617
use InvalidArgumentException;
1718

1819
use function array_rand;
@@ -199,6 +200,13 @@ protected function performConnect(?string $connectionName = null): bool
199200
}
200201

201202
if ($this->_eventManager->hasListeners(Events::postConnect)) {
203+
Deprecation::trigger(
204+
'doctrine/dbal',
205+
'https://github.com/doctrine/dbal/issues/5784',
206+
'Subscribing to %s events is deprecated. Implement a middleware instead.',
207+
Events::postConnect,
208+
);
209+
202210
$eventArgs = new ConnectionEventArgs($this);
203211
$this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
204212
}

‎src/Driver/AbstractSQLiteDriver/Middleware/EnableForeignKeys.php

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<?php
2+
3+
namespace Doctrine\DBAL\Driver\AbstractSQLiteDriver\Middleware;
4+
5+
use Doctrine\DBAL\Driver;
6+
use Doctrine\DBAL\Driver\Connection;
7+
use Doctrine\DBAL\Driver\Middleware;
8+
use Doctrine\DBAL\Driver\Middleware\AbstractDriverMiddleware;
9+
10+
class EnableForeignKeys implements Middleware
11+
{
12+
public function wrap(Driver $driver): Driver
13+
{
14+
return new class ($driver) extends AbstractDriverMiddleware {
15+
/**
16+
* {@inheritDoc}
17+
*/
18+
public function connect(array $params): Connection
19+
{
20+
$connection = parent::connect($params);
21+
22+
$connection->exec('PRAGMA foreign_keys=ON');
23+
24+
return $connection;
25+
}
26+
};
27+
}
28+
}

‎src/Driver/OCI8/Middleware/InitializeSession.php

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<?php
2+
3+
namespace Doctrine\DBAL\Driver\OCI8\Middleware;
4+
5+
use Doctrine\DBAL\Driver;
6+
use Doctrine\DBAL\Driver\Connection;
7+
use Doctrine\DBAL\Driver\Middleware;
8+
use Doctrine\DBAL\Driver\Middleware\AbstractDriverMiddleware;
9+
10+
class InitializeSession implements Middleware
11+
{
12+
public function wrap(Driver $driver): Driver
13+
{
14+
return new class ($driver) extends AbstractDriverMiddleware {
15+
/**
16+
* {@inheritDoc}
17+
*/
18+
public function connect(array $params): Connection
19+
{
20+
$connection = parent::connect($params);
21+
22+
$connection->exec(
23+
'ALTER SESSION SET'
24+
. " NLS_DATE_FORMAT = 'YYYY-MM-DD HH24:MI:SS'"
25+
. " NLS_TIME_FORMAT = 'HH24:MI:SS'"
26+
. " NLS_DATE_FORMAT = 'YYYY-MM-DD HH24:MI:SS'"
27+
. " NLS_TIMESTAMP_FORMAT = 'YYYY-MM-DD HH24:MI:SS'"
28+
. " NLS_TIMESTAMP_TZ_FORMAT = 'YYYY-MM-DD HH24:MI:SS TZH:TZM'"
29+
. " NLS_NUMERIC_CHARACTERS = '.,'",
30+
);
31+
32+
return $connection;
33+
}
34+
};
35+
}
36+
}

‎src/Event/ConnectionEventArgs.php

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77

88
/**
99
* Event Arguments used when a Driver connection is established inside Doctrine\DBAL\Connection.
10+
*
11+
* @deprecated
1012
*/
1113
class ConnectionEventArgs extends EventArgs
1214
{

‎src/Event/Listeners/OracleSessionInit.php

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@
2323
* NLS_DATE_FORMAT="YYYY-MM-DD HH24:MI:SS"
2424
* NLS_TIMESTAMP_FORMAT="YYYY-MM-DD HH24:MI:SS"
2525
* NLS_TIMESTAMP_TZ_FORMAT="YYYY-MM-DD HH24:MI:SS TZH:TZM"
26+
*
27+
* @deprecated Use {@see \Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession} instead.
2628
*/
2729
class OracleSessionInit implements EventSubscriber
2830
{

‎src/Event/Listeners/SQLSessionInit.php

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99

1010
/**
1111
* Session init listener for executing a single SQL statement right after a connection is opened.
12+
*
13+
* @deprecated Implement a middleware instead.
1214
*/
1315
class SQLSessionInit implements EventSubscriber
1416
{

‎src/Event/Listeners/SQLiteSessionInit.php

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
use Doctrine\DBAL\Events;
88
use Doctrine\DBAL\Exception;
99

10+
/** @deprecated Use {@see \Doctrine\DBAL\Driver\AbstractSQLiteDriver\Middleware\EnableForeignKeys} instead. */
1011
class SQLiteSessionInit implements EventSubscriber
1112
{
1213
/**

‎src/Events.php

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ private function __construct()
1818
{
1919
}
2020

21+
/** @deprecated */
2122
public const postConnect = 'postConnect';
2223

2324
/** @deprecated */

‎tests/TestUtil.php

Lines changed: 23 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,26 @@
22

33
namespace Doctrine\DBAL\Tests;
44

5-
use Doctrine\Common\EventSubscriber;
5+
use Doctrine\DBAL\Configuration;
66
use Doctrine\DBAL\Connection;
7+
use Doctrine\DBAL\Driver\AbstractSQLiteDriver\Middleware\EnableForeignKeys;
8+
use Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession;
79
use Doctrine\DBAL\DriverManager;
8-
use Doctrine\DBAL\Event\Listeners\SQLiteSessionInit;
910
use Doctrine\DBAL\Exception\DatabaseObjectNotFoundException;
1011
use Doctrine\DBAL\Platforms\AbstractPlatform;
1112
use Doctrine\DBAL\Platforms\DB2Platform;
1213
use Doctrine\DBAL\Platforms\OraclePlatform;
1314
use Doctrine\DBAL\Platforms\SqlitePlatform;
14-
use InvalidArgumentException;
1515
use PHPUnit\Framework\Assert;
1616

1717
use function array_keys;
1818
use function array_map;
1919
use function array_values;
20-
use function explode;
2120
use function extension_loaded;
2221
use function file_exists;
2322
use function implode;
2423
use function in_array;
2524
use function is_string;
26-
use function is_subclass_of;
27-
use function sprintf;
2825
use function strlen;
2926
use function strpos;
3027
use function substr;
@@ -66,13 +63,10 @@ public static function getConnection(): Connection
6663

6764
$params = self::getConnectionParams();
6865

69-
$connection = DriverManager::getConnection($params);
70-
71-
if (isset($params['event_subscribers'])) {
72-
self::addDbEventSubscribers($connection, explode(',', $params['event_subscribers']));
73-
}
74-
75-
return $connection;
66+
return DriverManager::getConnection(
67+
$params,
68+
self::createConfiguration($params['driver']),
69+
);
7670
}
7771

7872
/** @return mixed[] */
@@ -141,28 +135,27 @@ private static function getFallbackConnectionParams(): array
141135
}
142136

143137
return [
144-
'driver' => 'pdo_sqlite',
145-
'memory' => true,
146-
'event_subscribers' => SQLiteSessionInit::class,
138+
'driver' => 'pdo_sqlite',
139+
'memory' => true,
147140
];
148141
}
149142

150-
/** @param list<string> $subscribers */
151-
private static function addDbEventSubscribers(Connection $connection, array $subscribers): void
143+
private static function createConfiguration(string $driver): Configuration
152144
{
153-
$evm = $connection->getEventManager();
154-
155-
foreach ($subscribers as $subscriber) {
156-
if (! is_subclass_of($subscriber, EventSubscriber::class)) {
157-
throw new InvalidArgumentException(sprintf(
158-
'"%s" is not a valid event subscriber. It must be a class that implements "%s".',
159-
$subscriber,
160-
EventSubscriber::class,
161-
));
162-
}
163-
164-
$evm->addEventSubscriber(new $subscriber());
145+
$configuration = new Configuration();
146+
147+
switch ($driver) {
148+
case 'pdo_oci':
149+
case 'oci8':
150+
$configuration->setMiddlewares([new InitializeSession()]);
151+
break;
152+
case 'pdo_sqlite':
153+
case 'sqlite3':
154+
$configuration->setMiddlewares([new EnableForeignKeys()]);
155+
break;
165156
}
157+
158+
return $configuration;
166159
}
167160

168161
/** @return mixed[] */
@@ -211,7 +204,6 @@ private static function mapConnectionParameters(array $configuration, string $pr
211204
'unix_socket',
212205
'path',
213206
'charset',
214-
'event_subscribers',
215207
] as $parameter
216208
) {
217209
if (! isset($configuration[$prefix . $parameter])) {

0 commit comments

Comments
 (0)