Last month we released DBAL 2.13.0 as an important push for the ecosystem towards DBAL 3 with an extensive deprecation and forward compatibility layer.

We made a few mistakes, given that the forward compatibility layer is quite complex. As such we have now released Doctrine DBAL 2.13.1 and 3.1.0 with two new APIs that improve the forward compatiblity.

The problem lies in Statement::execute(): 2.13.0 would return a bool and 3.0.0 would return a Result from this method. This kind of API change cannot be handled with a forward compatibility.

As such we introduced two new APIs on Statement that replace execute(). When the old code was:

$statement = $connection->prepare('SELECT * FROM tbl WHERE col = ?');
$statement->execute();

$rows = $statement->fetchAll();

Then the new code is now:

$statement = $connection->prepare('SELECT * FROM tbl WHERE col = ?');
$result = $statement->executeQuery();

$rows = $result->fetchAllAssociative();

The DBAL 2.13 forward compatiblity layer supports both versions of all code and returns a Statement/Result hybrid that has all the APIs that the DBAL Statement had up until version 2.12. This way you can move at your own pace from the old to the new API in your code.

Thank you again to mdumoulin for the work on improving the forward compatiblity and to Sergei Morozov for the thorough reviews and comments.

Again I want to highlight the Runtime Deprecations library that we introduced to support this migration. You can integrate this with your log stack during development and testing:

use Doctrine\Deprecations\Deprecation;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('doctrine');
$log->pushHandler(new StreamHandler('deprecations.log', Logger::INFO));

Deprecation::enableWithPsrLogger($log);

Or alternatively using PHP's global error handler:

Deprecation::enableWithTriggerError();

See the 2.13 blog post for more information about the migration to DBAL 3 and strategy recommendations.