This is an old revision of the document!
PHP RFC: Use exceptions by default in SQLite3 extension
- Version: 0.1
- Date: 2022-10-24
- Author: BohwaZ, php at bohwaz dot net
- Status: Under discussion
- First Published at: http://wiki.php.net/rfc/sqlite3_exceptions
Introduction
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
In PHP 8.3:
- Create a new exception class
SQLite3Exception
, which extends the SPLRuntimeException
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)
raisesE_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 (Calling it withtrue
still works, but is a no-op.) - It's not possible to use warnings anymore.
In PHP 10.0:
- Remove the
SQLite3::enableExceptions
method
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
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 SAPIs
None.
To Existing Extensions
Only SQLite3.
To Opcache
None that I can think of.
New Constants
None.
php.ini Defaults
None.
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
- Proposal 1: accept the proposed plan
- Proposal 2: no change
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)
Implementation
After the project is implemented, this section should contain
- the version(s) it was merged into
- a link to the git commit(s)
- a link to the PHP manual entry for the feature
- a link to the language specification section (if any)
References
Rejected Features
Keep this updated with features that were discussed on the mail lists.