RFC: Remove @internal annotation on methods that could be reused in a wrapper_classand add a setter

[Crovitche-1623]

Feature Request

What

1. Remove @internal on methods in Doctrine\DBAL\Connection that could be reused in wrapper_class
2. Add the possibility to increment the transactionNestingLevel in a class that extends Doctrine\DBAL\Connection

Why

I'm developping a custom Doctrine\DBAL\Connection (for handling my own custom transaction management) and used the wrapper_class configuration parameter to setup my custom connection.

To do so, I extended the original Doctrine\DBAL\Connection and saw that:

1. Some methods have the @internal annotation:
   a. convertException
   b. getParams
2. The transactionNestingLevel property does not have the protected visibility and has no setter.

How

1. Remove the @internal annotation on convertException and getParams
2. Create a setter for transactionNestingLevel or change the property visibility to protected

[morozov]

I think it's okay to make transactionNestingLevel protected (I don't see much sense in adding a setter for it – that would be effectively the same). As for making getParams() non-internal, it's a strict no.

I don't think we have a good API for customizing the behavior of the existing components, and I don't want to put the project in a position where we will be unable to make certain changes because they would break BC.

If you want to implement such an extension, you should use internal APIs and accept the risks that they may change over time. An alternative would be to decompose the wrapper connection into smaller pieces for which we could declare the interfaces that we can support.