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 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 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 - It's not possible to use warnings anymore.
- Calling
SQLite3::enableExceptions(true)
raisesE_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 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
- 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)
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.