Deprecated the userDefinedFunctions driver option for pdo_sqlite

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.

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'],

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)'));
+    }
 }