Fix Connection#ping() to have clear behavior, refs GH-414

lib/Doctrine/DBAL/Connection.php

@@ -1491,15 +1491,29 @@ class Connection implements DriverConnection
     }
 
     /**
-     * Ping the server!
+     * Ping the server
+     *
+     * When the server is not available the method returns FALSE.
+     * It is responsibility of the developer to handle this case
+     * and abort the request or reconnect manually:
+     *
+     * @example
+     *
+     *   if ($conn->ping() === false) {
+     *      $conn->close();
+     *      $conn->connect();
+     *   }
+     *
+     * It is undefined if the underlying driver attempts to reconnect
+     * or disconnect when the connection is not available anymore
+     * as long it returns TRUE when a reconnect succeeded and
+     * FALSE when the connection was dropped.
      *
      * @return bool
      */
     public function ping()
     {
-        if ( ! $this->_isConnected) {
-            return false; // Don't connect if not done yet. It will be lazy on first use
-        }
+        $this->connect();
 
         if ($this->_conn instanceof PingableConnection) {
             return $this->_conn->ping();
@@ -1510,10 +1524,7 @@ class Connection implements DriverConnection
 
             return true;
         } catch (DBALException $e) {
-            // As the underlying connection is unset, the next query will connect again thanks to the lazyness
-            $this->close();
+            return false;
         }
-
-        return false;
     }
 }

tests/Doctrine/Tests/DBAL/Functional/ConnectionTest.php

@@ -218,14 +218,9 @@ class ConnectionTest extends \Doctrine\Tests\DbalFunctionalTestCase
         $this->assertEquals($this->_conn->quote("foo", Type::STRING), $this->_conn->quote("foo", \PDO::PARAM_STR));
     }
 
-    public function testPingDoesNotTriggerConnect()
+    public function testPingDoesTriggersConnect()
     {
-        $this->assertFalse($this->_conn->ping());
-    }
-
-    public function testPingReturnsTrueWhenConnectionIsPingedOrOpen()
-    {
-        $this->_conn->connect();
         $this->assertTrue($this->_conn->ping());
+        $this->assertTrue($this->_conn->isConnected());
     }
 }