[3.0] Rework driver exceptions

[BenMorel]

Q	A
Type	improvement
BC Break	yes
Fixed issues	N/A

Summary

Consumers of the Driver\Connection API are not interested in catching individual exceptions implementing Driver\DriverException, and will always catch (DriverException).

As such, the multiple implementations of DriverException provide little to no value, clutter the codebase, and force introducing a new exception class or using new class whenever we need to throw a DriverException from a new place.

This design was probably chosen for 2 reasons:

• a historical reason: Driver\PDOConnection originally extended \PDO, and as such Driver\PDOException extended \PDOException. To implement an interface common to all drivers, it was chosen to create an interface DriverException, that Driver\PDOException would implement, while still extending \PDOException. This requirement is gone, as the DBAL is evolving away from extending PDO, towards encapsulation.
• a practical reason: custom exceptions allow for custom factory methods; these can easily be replaced with static methods on the Connection classes.

Proposed changes

• AbstractDriverException is now a concrete DriverException, replacing the interface
• All sub-exceptions are now gone
• All exotic new class ... extends AbstractDriverException are now replaced with new DriverException
• Factory methods from sub-exceptions are moved to a public static method in the Connection, that can be used from within the Connection itself and from the Statement
• All relevant Connection methods are now explicitly documented as throwing DriverException

This last point is very important: so far, most of the methods had no documented exceptions, while query() and exec() were documented as throwing DBALException, a contract that was never respected:

• PDOConnection::query() and exec() throw Driver\PDOException, which is a DriverException, not a DBALException
• DB2Exception::query() and exec() throw DB2Exception, which is a DriverException
• SQLSrvException::query() and exec() throw SQLSrvException (via SQLSrvStatement::execute()), which is a DriverException
• ... and so on.

[morozov]

There is absolutely no conflict in #3335 with exceptions: it's just using the new class where a concrete DriverException class is not available.

@Majkl578 drives the rework of exceptions. As far as I understand, design-wise it's not what he had in mind.

[BenMorel]

@morozov #3335 does not make any changes to exceptions, on the contrary it tries to accommodate them as best as it can.

@Majkl578 Could you please review #3335, to see if it poses any problem to you?

[morozov]

@BenMorel I made some progress recently cleaning up driver exceptions in #4072, #4085, #4125, #4130, and other PRs (see the history of the 3.0.x branch).

Currently, some of the problems you were trying to solve are solved but not everything is changed the way you planned to. Do you want to try and rebase your PR onto 3.0.x and see if any changes are still relevant?

[BenMorel]

@morozov I’m on vacation right now, I’ll try to look into this as soon as I get back!

[BenMorel]

Looking at 3.0.x and master, exceptions look in good shape and the project now looks much closer to what I had in mind.

I'm therefore closing this PR, and would rather open a new one if I were to suggest other changes in the future.

Thank you.

[morozov]

Sounds good. Thanks for following up, @BenMorel.