Affects Version/s: None
Fix Version/s: 2.5
Security Level: All
This issue is created automatically through a Github pull request on behalf of deeky666:
This PR aims to have are more solid, abstracted and flexible driver exception conversion API as introduced in PR #364.
It removes the `DBALExcpetion::ERROR_*` constants in favour of returning the appropriate DBAL driver exception directly in the driver. Those constants are of no meaning anymore, as these exceptions get converted into dedicated exception instances anyways. This also allows custom driver implementations to handle their driver exception conversion manually and introducing custom driver exception classes. Moreover it saves one additional conversion step in `DBALException`.
A new `DriverException` interface has been introduced for driver exception to return the error code, SQLSTATE and message. This is an approach to have a uniform driver API just like `Driver`, `Connection` and `Statement`. This also offers some other opportunities.
Complementary the `AbstractDriverException` and `PDOException` classes have been introduced to provide the basic implementation and behaviour for driver exceptions.
`PDOConnection` and `PDOStatement` now wrap all method calls into try catch blocks, catch `\PDOException` and wrap it into DBAL's `PDOException` to provide DBAL's `DriverException` interface.
The API of the `ExceptionConverterDriver` has been changed to take the DBAL generated exception message and a `DriverException` instance to evaluate the driver specific error code and SQLSTATE in order to return the appropriate standardized DBAL driver exception instance.
The following DBAL driver exception class changes have been made:
- Introduce a base `DriverExcpetion` class for all DBAL driver exceptions.
- Introduce a `ConnectionException` class for all errors related to connection attempts (an abstraction just like the vendors do)
- Introduce a `ServerException` class for all error related to operations made on the server (after the connection has succeeded, an abstraction just like the vendors do)
- Introduce a `DatabaseObjectNotFoundException` class as a base class for referenced database objects like schemas, table, constraints, indexes etc. that do not exists in the database (useful also for SQL Server which cannot distinguish between unknown tables, sequences, indexes etc.).
- Introduce a `DatabaseObjectExistsException` class as a base class for referenced database objects like schemas, table, constraints, indexes etc. that do already exists in the database (useful also for SQL Server which cannot distinguish between already existing tables, sequences, indexes etc.).
- Introduce a `ConstraintViolationException` class as a base class for all constraint violations like foreign key constraints, unique constraints, not null constraints, check constraints etc. (useful also if you only want to determine whether a data intergrity problem was found)
- Remove `AccessDeniedException` in favour of `ConnectionException`. The term "access denied" should be reserved for insufficient privileges on a database operation IMO. This exception until now also refered to network errors, unknown hosts etc. errors during a connection attempt. So IMO the term is misleading and should be changed to a more general connection error exception.
- Rename `NotNullableException` to `NotNullConstraintViolationException` as it is a constraint in general and should also be named as such.
- Renamed `DuplicateKeyException` to `UniqueConstraintViolationException` as it is a constraint and should also be named as such.
- Removed `FailedToOpenException` and mapped it to `ConnectionException` as it is a SQLite specific exception and should be treated in a more general/abstracted sense.
- Map `ReadOnlyException` to `ServerException` as it can only occurr if the connection has been established already. It was a connection error before.
There are a lot of changes that have been made but I think they are reasonable and important to have a better abstracted exception API. Also I would like to introduce a `Configuration` option for custom driver exception conversion which is only possible with this approach.
I hope you will like it, otherwise blame me to death!