PHP 8.3: SQLite3: New \SQLite3Exception, deprecations, and changes

Version8.3
TypeChange

The SQLite3 extension in PHP 8.3 improves the error handling of the extension to encourage the use of Exceptions, and to discourage the existing behavior of PHP Warnings.

The current default error-handling behavior of the SQLite3 extension is to emit PHP Warnings. This is not changed in PHP 8.3, and PHP 8.3 and other PHP 8.x versions continue to emit a PHP Warning on errors. The SQLite3 extension provides a SQLite3::enableExceptions(true) method that changes the error handling behavior to throw exceptions instead of emitting PHP Warnings.

In PHP 8.3, there are four changes related to this functionality:

PHP 8.3 and all PHP 8.3+ versions will continue to emit warnings. It continues that SQLite3::enableExceptions(true) must be called to enable Exceptions.

New SQLite3Exception Exception Class

PHP 8.3 SQLite3 extension adds a new Exception class in the global namespace, which extends the existing \Exception class.

class SQLite3Exception extends \Exception {}

It does not introduce any additional constants, properties, or methods.

The new \SQLite3Exception exception class can be polyfilled in user-land PHP code. While this does not change the behavior of the SQLite3 extension in older PHP versions, it can be helpful if the applications need to serialize and unserialize exceptions across multiple PHP versions including PHP 8.3.

SQLite3 Error code moved to SQLite3Exception

Prior to PHP 8.3, the PHP Warnings emitted by the SQLite3 extension contained the error code in the warning message.

Unable to prepare statement: 23, not authorized

In PHP 8.3, all of these messages have changed to not include the error code in the warning messages.

For example, the same PHP Warning message above is changed in PHP 8.3 like this:

- Unable to prepare statement: 23, not authorized
+ Unable to prepare statement: not authorized

In PHP 8.3 and later, to obtain the error code, enable Exception support in the SQLite3 instance, and check the error code of the Exceptions.

$db = new SQLite3(':memory:');
$db->enableExceptions(true);

$db->setAuthorizer(function () {
    return false;
});

try {
    $db->querySingle('SELECT 1;');
} catch (\SQLite3Exception $e) {
    echo $e->getMessage() . "\n";
    echo $e->getCode();
}

SQLite3::enableExceptions(false) Deprecated

The SQLite3 extension continues to emit warnings in all PHP 8.x versions including PHP 8.3 and later. This is essentially the same as calling SQLite3::enableExceptions(false) implicitly.

However, explicitly calling SQLite3::enableExceptions(false) is deprecated in PHP 8.3 and later. 

$db = new SQLite3(':memory:');
$db->enableExceptions(false);
Deprecated: SQLite3::enableExceptions(): Use of warnings for SQLite3 is deprecated

Backward Compatibility Impact

This change introduces some minimal backward-compatibility breaks.

  1. The PHP Warning messages from the SQLite3 extension no longer include the error code.
  2. When exceptions are enabled, the thrown exceptions are now \SQLite3Exception, instead of \Exception. However, because \SQLite3Exception extends \Exception class, existing catch () blocks should continue to work.
  3. Calling SQLite3::enableExceptions(false) emits a deprecation warning.

Related Changes

RFC Discussion Implementation