Convert Doctrine\DBAL\Exception to an interface

[morozov]

Q	A
Type	improvement

Currently, the base exception being a class doesn't allow to reuse of the semantics of the SPL exception classes. For instance, distinguish between logic and runtime exceptions.

Not being able to reuse the semantics defined in SPL causes the following issue about documenting exceptions. For example, take the NotSupported exception which has the following ancestry: NotSupported → \Doctrine\DBAL\Exception → \Exception. As static analyzers see it, semantically, it's just a generic exception as it extends the generic \Exception class. But in fact, it identifies an error in the logic of the code that consumes the API and thereby should not be handled by the caller (an unchecked exception).

Now, take this use case for example:

dbal/src/Platforms/AbstractPlatform.php

Lines 2012 to 2016 in 4bd24c8

	/** @throws Exception If not supported on this platform. */
	public function getSequenceNextValSQL(string $sequence): string
	{
	throw NotSupported::new(__METHOD__);
	}

The method is declared as throwing an exception with unknown semantics. As a result, static analyzers like PhpStorm flag the calls that don't handle this exception as incorrect. If we remove the @throws annotation, then the throw statement is flagged as incorrect. The only way to write statically correct code against this API is to catch the exception and do nothing with it, which is still wrong.

Converting the class to an interface allows retaining the relation of the exception to the DBAL and at the same time reusing the semantics defined in SPL. For example:

dbal/src/Exception/InvalidArgumentException.php

Lines 7 to 14 in 4bd24c8

	use Doctrine\DBAL\Exception;
	/**
	* Exception to be thrown when invalid arguments are passed to any DBAL API
	*
	* @psalm-immutable
	*/
	class InvalidArgumentException extends \InvalidArgumentException implements Exception

In subsequent patches, we can fine-tune the semantics of other exceptions (firstly, NotSupported) by changing their parent from \Exception to something more specific.