# RFC: Use exceptions by default in SQLite3 extension

- Status: Implemented (PHP 8.3)
- Authors: BohwaZ, php at bohwaz dot net
- Date: 2022-10-24
- Version: 0.1
- Implementation: https://github.com/php/php-src/commit/ddd9a08f566d86083d04de320e24f0751a1de759
- Original: https://wiki.php.net/rfc/sqlite3_exceptions
- Page: https://externals.io/rfc/sqlite3_exceptions
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

## Votes

### Use exceptions by default in SQLite3 extension as described in this RFC? (closed)

Yes: 21 · No: 0

Voters: brzuchal (Yes), bwoebi (Yes), colinodell (Yes), crell (Yes), galvao (Yes), geekcom (Yes), girgias (Yes), heiglandreas (Yes), kalle (Yes), levim (Yes), mauricio (Yes), mcmic (Yes), nicolasgrekas (Yes), nielsdos (Yes), ocramius (Yes), petk (Yes), pierrick (Yes), sergey (Yes), stas (Yes), theodorejb (Yes), villfa (Yes)

## Discussions on the mailing list

- [\[RFC\] \[Discussion\] SQLite3: remove warnings, move to exceptions](https://externals.io/message/118873.md) — started on 2022-10-24, 10 messages
- [\[RFC\] Last chance to discuss "Use exceptions by default in SQLite3 extension" before vote](https://externals.io/message/119980.md) — started on 2023-04-12, 1 messages
- [\[VOTE\] Use exceptions by default in SQLite3  extension](https://externals.io/message/120214.md) — started on 2023-05-08, 6 messages

---

## 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 `Exception` class
- 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)` raises `E_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)` raises `E_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

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:

- 8.3: <https://github.com/php/php-src/pull/11058>

## Implementation

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)

## References

- <https://externals.io/message/118873>

## Vote

Voting started 2023-05-09 and has ended end 2023-05-23, Europe/Paris timezone.

**Vote: Use exceptions by default in SQLite3 extension as described in this RFC?** — Yes: 21 · No: 0 (closed)