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
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 - Calling
SQLite3::enableExceptions(false)
raisesE_DEPRECATED
- Default behavior is still to raise warnings (
enableExceptions(false)
)
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
Backward Incompatible Changes
In PHP 8.3:
- Code parsing the error message to get the error code may fail as the error code has been moved to be consistently at the end of the error message string. 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 (via \RuntimeException)
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
- 2: 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.