The usage of user-provided PDO instance is deprecated

[morozov]

Q	A
Type	deprecation
BC Break	no

The support for user-provided PDO instance has been removed in #3548.

The known use cases are:

1. Persistent PDO connections. DBAL 3.0 will supported establishing persistent connections, therefore, providing a pre-created persistent PDO connection will be no longer needed.
2. Sharing PDO instance between DBAL and legacy components. In order to share a PDO instance, initialize the connection in DBAL and access it using Connection::getWrappedConnection()->getWrappedConnection().

Another fix for 2 is to implement your own Driver that is created with an existing PDO instance.

[acoulton]

@morozov there is a third use-case for passing in a user-provided PDO that isn't mentioned in the deprecation (and I'm not sure how best to replace).

In some cases it's desirable to be be able to instantiate Doctrine objects and tools without an actual database connection being available. Examples include:

• Integration tests of service container and dependency factory setups
• Integration / unit tests of code that interacts with things provided by the doctrine entity manager - access to class metadata etc - without having to mock / stub / access / bridge to lots of doctrine internals
• Running doctrine CLI tools like orm:generate-proxies or orm:validate-schema --skip-sync as part of a CI/CD flow in environments like e.g. docker / cloud build etc where there's actually no need for the tool to communicate with a DB, and (without a lot of overhead and faff) no easy way to provide one. generate-proxies is the main issue here, as there's a very strong desire to be able to run that before baking the application codebase into a docker container.

To date, we've worked around this by configuring our dependency container for those environments to inject a custom NullPDO class. That extends PDO to satisfy the Doctrine's constructor-time requirement to have either a PDO implementation or valid live database connection details, but throws if you actually try to perform any database operations.

If that option is being removed then perhaps Doctrine internally needs to support some sort of NullConnection (or be refactored so that code that doesn't actually have to talk to the db doesn't attempt to instantiate a connection at all) to make cases like this possible?

[Ocramius]

Doesn't it make more sense to have a NullConnection in such cases?

[acoulton]

@Ocramius quite possibly so - however when we looked at doing that externally it was a lot more problematic than a standard Connection with a NullPDO.

ISTR (it was a while ago) we tried that first and the issues we ran into included:

• EntityManager depends on the Doctrine\DBAL\Connection class rather than an interface, so a NullConnection would have to extend that class and overwrite most of the current methods, making it harder to keep it stable / in-sync with Doctrine internals over time (the interface of PDO is pretty fixed).
• The implementation of DBAL\Connection contains some methods that still need to return values / create, return or perform actions on instances of dependency classes etc - e.g. looking at it now I think there was an issue that a NullConnection still needs to assign ->platform object, which involves calling the driver, etc. I think also similarly it needs to return a SchemaManager to satisfy dependencies of some of the calling code though again that may not ultimately be used.
• Some of the DBAL\Connection methods that might need to be overridden for a NullConnection are private methods

So yes, if you were going to bring the connection-less concept into Doctrine core then a NullConnection is probably a better way to go, with appropriate refactoring to make it possible to do that in a sensible way.

But externally as it stands it's significantly easier and more robust to use all your current code in the Connection object and just stub out the underlying PDO connection.