PHP RFC: Use exceptions by default in SQLite3 extension


The SQLite3 extension is still using PHP warnings by default. PDO is using exceptions, like everyone else.

It's time to move to exceptions.

Proposal 1

Progressively deprecate warnings (PHP 8.3), make exceptions the default (9.0) and remove warnings (10.0).

In PHP 8.3:

  • Create a new exception class SQLite3Exception, which extends the SPL RuntimeException class, like in mysqli and PDO
  • Remove SQLite3 error code from the error message, and assign it to the exception code
  • Make SQLite3::enableExceptions(true) throw SQLite3Exception instead of Exception
  • Default behavior is still to raise warnings
  • Calling SQLite3::enableExceptions(false) raises E_DEPRECATED

In PHP 9.0:

  • Make SQLite3 throw exceptions of class SQLite3Exception by default, instead of raising warnings
  • Calling SQLite3::enableExceptions(false) throws an error
  • It's not possible to use warnings anymore.
  • Calling SQLite3::enableExceptions(true) raises E_DEPRECATED, to alert that the method will get removed

In PHP 10.0:

  • Remove the SQLite3::enableExceptions method

Proposal 2

Same as proposal 1, but make SQLite3 throw exceptions by default in PHP 8.3 instead of 9.0.

Backward Incompatible Changes

In PHP 8.3:

  • Code parsing the error message to get the error code may fail, but this is unlikely as the proper way is to use SQLite3::lastErrorCode()
  • Code already relying on exceptions will not see a difference, as previously \Exception was thrown, and \SQLite3Exception is a subclass of \Exception
  • (Proposal 2 only:) code not using enableExceptions to enable warnings will need to add this call and mute the E_DEPRECATED message

In PHP 9.0:

  • Calls to SQLite3::enableExceptions(false) will break
  • Code relying on hiding warnings will break

In PHP 10.0:

  • Calls to SQLite3::enableExceptions() will fail

Proposed PHP Version(s)

PHP 8.3, 9.0, 10.0

RFC Impact



To Existing Extensions

Only SQLite3.

To Opcache

None that I can think of.

New Constants


php.ini Defaults


Unaffected PHP Functionality

Everything outside of SQLite3 extension.

Future Scope

Assign SQLite3 error constants to SQLite3Exception class, eg. SQLite3Exception::READONLY, see https://www.sqlite.org/rescode.html

Proposed Voting Choices

  • 1: accept proposal 1 (deprecate progressively, default to exceptions in 9.0)
  • 2: accept proposal 2 (same, but default to exceptions in 8.3)
  • 3: don't change anything

Patches and Tests

Pull request: https://github.com/php/php-src/pull/9816 (this is for the while behaviour for 10.0, it will be broken into multiple PRs)


After the project is implemented, this section should contain

  1. the version(s) it was merged into
  2. a link to the git commit(s)
  3. a link to the PHP manual entry for the feature
  4. a link to the language specification section (if any)


Rejected Features

Keep this updated with features that were discussed on the mail lists.

rfc/sqlite3_exceptions.txt · Last modified: 2022/10/29 09:45 by bohwaz