[RFC] Transition SQLite3 to exceptions (#11058)

* Deprecate warnings in SQLite3, change returned exception class to SQLite3Exception

RFC: https://wiki.php.net/rfc/sqlite3_exceptions

Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>

Author: bohwaz

UPGRADING

@@ -117,6 +117,11 @@ PHP 8.3 UPGRADE NOTES
   . The ZipArchive::FL_RECOMPRESS constant is deprecated and will be removed
     in a future version of libzip
 
+- SQLite3
+  . Using exceptions is now preferred, warnings will be removed in the future.
+    Calling SQLite3::enableExceptions(false) will trigger a depreciation warning
+    in this version.
+
 ========================================
 5. Changed Functions
 ========================================
@@ -262,6 +267,12 @@ PHP 8.3 UPGRADE NOTES
 9. Other Changes to Extensions
 ========================================
 
+- SQLite3
+  . The SQLite3 class now throws \SQLite3Exception (extends \Exception) instead
+    of \Exception.
+  . The SQLite error code is now passed in the exception error code instead of being
+    included in the error message.
+
 ========================================
 10. New Global Constants
 ========================================

ext/sqlite3/sqlite3.c

@@ -68,6 +68,13 @@
 const SQLITE3_DETERMINISTIC = UNKNOWN;
 #endif
 
+/**
+ * @strict-properties
+ */
+class SQLite3Exception extends \Exception
+{
+}
+
 /** @not-serializable */
 class SQLite3
 {

ext/sqlite3/sqlite3.stub.php

@@ -18,7 +18,7 @@ echo "Error Msg: " . $db->lastErrorMsg() . "\n";
 --EXPECTF--
 SELECTING from invalid table
 
-Warning: SQLite3::query(): Unable to prepare statement: 1, no such table: non_existent_table in %sbug69972.php on line %d
+Warning: SQLite3::query(): Unable to prepare statement: no such table: non_existent_table in %sbug69972.php on line %d
 Closing database
 bool(true)
 Done

ext/sqlite3/sqlite3_arginfo.h

@@ -17,10 +17,10 @@ try {
     $st->bindValue("a", ":memory:");
     $st->execute();
     var_dump($db->exec('create table db2.r (id int)'));
-} catch (Exception $ex) {
+} catch (SQLite3Exception $ex) {
     echo $ex->getMessage(), PHP_EOL;
 }
 ?>
 --EXPECT--
 bool(true)
-Unable to prepare statement: 23, not authorized
+Unable to prepare statement: not authorized

ext/sqlite3/tests/bug69972.phpt

@@ -20,7 +20,7 @@ echo "Done\n";
 --EXPECTF--
 SELECTING from invalid table
 
-Warning: SQLite3::query(): Unable to prepare statement: 1, no such table: non_existent_table in %s on line %d
+Warning: SQLite3::query(): Unable to prepare statement: no such table: non_existent_table in %s on line %d
 Error Code: 1
 Error Msg: no such table: non_existent_table
 Closing database

ext/sqlite3/tests/gh9032.phpt

@@ -20,10 +20,10 @@ $db = new SQLite3(':memory:');
 
 try {
   $db->loadExtension("");
-} catch (Extension $ex) {
+} catch (\Throwable $ex) {
   var_dump($ex->getMessage());
 }
 
 ?>
 --EXPECTF--
-Warning: SQLite3::loadExtension(): Empty string as an extension in %s on line %d
+string(61) "SQLite3::loadExtension(): Argument #1 ($name) cannot be empty"

ext/sqlite3/tests/sqlite3_20_error.phpt

@@ -24,4 +24,4 @@ try {
 
 ?>
 --EXPECTF--
-Warning: SQLite3::loadExtension(): SQLite Extension are disabled in %s on line %d
+Warning: SQLite3::loadExtension(): SQLite Extensions are disabled in %s on line %d

ext/sqlite3/tests/sqlite3_33_load_extension_param.phpt

@@ -71,7 +71,7 @@ try {
 ?>
 --EXPECT--
 int(1)
-Unable to prepare statement: 23, not authorized
+Unable to prepare statement: not authorized
 bool(true)
 int(42)
 string(6) "SELECT"
@@ -98,7 +98,7 @@ string(28) "sqlite_master,rootpage,main,"
 string(4) "READ"
 string(28) "sqlite_master,rootpage,main,"
 bool(true)
-Unable to prepare statement: 23, not authorized
+Unable to prepare statement: not authorized
 The authorizer callback returned an invalid type: expected int
-Unable to prepare statement: 23, not authorized
-The authorizer callback returned an invalid value
+Unable to prepare statement: not authorized
+The authorizer callback returned an invalid value: 4200

ext/sqlite3/tests/sqlite3_34_load_extension_ext_dir.phpt

@@ -37,6 +37,6 @@ bool(true)
 int(1)
 int(1)
 
-Warning: SQLite3::querySingle(): Unable to prepare statement: 1, table sqlite_master may not be modified in %s on line %d
+Warning: SQLite3::querySingle(): Unable to prepare statement: table sqlite_master may not be modified in %s on line %d
 bool(false)
-int(1)
+int(1)

ext/sqlite3/tests/sqlite3_40_setauthorizer.phpt

@@ -24,6 +24,8 @@ echo "Done\n";
 --EXPECTF--
 bool(false)
 no such table: non_existent_table
+
+Deprecated: SQLite3::enableExceptions(): Use of warnings for SQLite3 is deprecated in %s
 bool(true)
 
 Warning: SQLite3::query(): no such table: non_existent_table in %s on line %d

ext/sqlite3/tests/sqlite3_defensive.phpt

@@ -16,5 +16,5 @@ $stmt = $db->prepare('SELECT foo FROM bar');
 var_dump($stmt);
 ?>
 --EXPECTF--
-Warning: SQLite3::prepare(): Unable to prepare statement: 1, no such table: bar in %s on line %d
+Warning: SQLite3::prepare(): Unable to prepare statement: no such table: bar in %s on line %d
 bool(false)

ext/sqlite3/tests/sqlite3_enable_exceptions.phpt

@@ -38,4 +38,4 @@ try {
 Trampoline for authorizer
 int(1)
 Trampoline for authorizer
-Unable to prepare statement: 23, not authorized
+Unable to prepare statement: not authorized