From 2e207c4db49006c74e3681a89bf1fc2d2b80379d Mon Sep 17 00:00:00 2001
From: "Alexander M. Turek" <me@derrabus.de>
Date: Mon, 10 Oct 2022 21:05:13 +0200
Subject: [PATCH] Deprecated the userDefinedFunctions driver option for
 pdo_sqlite

---
 UPGRADE.md                                    | 31 +++++++++++++++++++
 src/Driver/PDO/SQLite/Driver.php              |  8 +++++
 .../Driver/PDO/SQLite/DriverTest.php          | 23 ++++++++++++++
 3 files changed, 62 insertions(+)

diff --git a/UPGRADE.md b/UPGRADE.md
index c4d48ae99e5..283ede02bdd 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -8,6 +8,37 @@ awareness about deprecated code.
 
 # Upgrade to 3.5
 
+## Deprecated the `userDefinedFunctions` driver option for `pdo_sqlite`
+
+Instead of funneling custom functions through the `userDefinedFunctions` option, use `getNativeConnection()`
+to access the wrapped PDO connection and register your custom functions directly.
+
+### Before
+
+```php
+$connection = DriverManager::getConnection([
+    'driver' => 'pdo_sqlite',
+    'path' => '/path/to/file.db',
+    'driverOptions' => [
+        'userDefinedFunctions' => [
+            'my_function' => ['callback' => [SomeClass::class, 'someMethod'], 'numArgs' => 2],
+        ],
+    ]
+]);
+```
+
+### After
+
+```php
+$connection = DriverManager::getConnection([
+    'driver' => 'pdo_sqlite',
+    'path' => '/path/to/file.db',
+]);
+
+$connection->getNativeConnection()
+    ->sqliteCreateFunction('my_function', [SomeClass::class, 'someMethod'], 2);
+```
+
 ## Deprecated `Table` methods.
 
 The `hasPrimaryKey()` method has been deprecated. Use `getPrimaryKey()` and check if the return value is not null.
diff --git a/src/Driver/PDO/SQLite/Driver.php b/src/Driver/PDO/SQLite/Driver.php
index 9d56526c519..ea442d8d376 100644
--- a/src/Driver/PDO/SQLite/Driver.php
+++ b/src/Driver/PDO/SQLite/Driver.php
@@ -6,6 +6,7 @@
 use Doctrine\DBAL\Driver\PDO\Connection;
 use Doctrine\DBAL\Driver\PDO\Exception;
 use Doctrine\DBAL\Platforms\SqlitePlatform;
+use Doctrine\Deprecations\Deprecation;
 use PDO;
 use PDOException;
 
@@ -30,6 +31,13 @@ public function connect(array $params)
         $driverOptions = $params['driverOptions'] ?? [];
 
         if (isset($driverOptions['userDefinedFunctions'])) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5742',
+                'The SQLite-specific driver option "userDefinedFunctions" is deprecated.'
+                    . ' Register function directly on the native connection instead.',
+            );
+
             $this->userDefinedFunctions = array_merge(
                 $this->userDefinedFunctions,
                 $driverOptions['userDefinedFunctions'],
diff --git a/tests/Functional/Driver/PDO/SQLite/DriverTest.php b/tests/Functional/Driver/PDO/SQLite/DriverTest.php
index 5bf64ffcf9b..b14f66e535b 100644
--- a/tests/Functional/Driver/PDO/SQLite/DriverTest.php
+++ b/tests/Functional/Driver/PDO/SQLite/DriverTest.php
@@ -2,14 +2,18 @@
 
 namespace Doctrine\DBAL\Tests\Functional\Driver\PDO\SQLite;
 
+use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver as DriverInterface;
 use Doctrine\DBAL\Driver\PDO\SQLite\Driver;
 use Doctrine\DBAL\Tests\Functional\Driver\AbstractDriverTest;
 use Doctrine\DBAL\Tests\TestUtil;
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 
 /** @requires extension pdo_sqlite */
 class DriverTest extends AbstractDriverTest
 {
+    use VerifyDeprecations;
+
     protected function setUp(): void
     {
         parent::setUp();
@@ -30,4 +34,23 @@ protected function createDriver(): DriverInterface
     {
         return new Driver();
     }
+
+    public function testRegisterCustomFunction(): void
+    {
+        $params                                          = $this->connection->getParams();
+        $params['driverOptions']['userDefinedFunctions'] = [
+            'my_add' => ['callback' => static fn (int $a, int $b): int => $a + $b, 'numArgs' => 2],
+        ];
+
+        $connection = new Connection(
+            $params,
+            $this->connection->getDriver(),
+            $this->connection->getConfiguration(),
+            $this->connection->getEventManager(),
+        );
+
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/dbal/pull/5742');
+
+        self::assertSame(42, (int) $connection->fetchOne('SELECT my_add(20, 22)'));
+    }
 }