Merge pull request #65 from clue-labs/quit

Rename close() to quit() and use promises for quit() method

Author: jsor

README.md

@@ -44,7 +44,7 @@ $factory->createConnection($uri)->then(function (ConnectionInterface $connection
         }
     );
 
-    $connection->close();
+    $connection->quit();
 });
 
 $loop->run();
@@ -259,6 +259,22 @@ $connection->ping()->then(function () {
 });
 ```
 
+#### quit()
+
+The `quit(): PromiseInterface<void, Exception>` method can be used to
+quit (soft-close) the connection.
+
+This method returns a promise that will resolve (with a void value) on
+success or will reject with an `Exception` on error. The MySQL protocol
+is inherently sequential, so that all commands will be performed in order
+and outstanding commands will be put into a queue to be executed once the
+previous commands are completed.
+
+```php
+$connection->query('CREATE TABLE test ...');
+$connection->quit();
+```
+
 ## Install
 
 The recommended way to install this library is [through Composer](https://getcomposer.org).

examples/01-query.php

@@ -32,7 +32,7 @@
         echo 'Error: ' . $error->getMessage() . PHP_EOL;
     });
 
-    $connection->close();
+    $connection->quit();
 }, 'printf');
 
 $loop->run();

examples/02-query-stream.php

@@ -26,7 +26,7 @@
         echo 'CLOSED' . PHP_EOL;
     });
 
-    $connection->close();
+    $connection->quit();
 }, 'printf');
 
 $loop->run();

examples/11-interactive.php

@@ -31,7 +31,7 @@
         if ($query === 'exit') {
             // exit command should close the connection
             echo 'bye.' . PHP_EOL;
-            $connection->close();
+            $connection->quit();
             return;
         }
 
@@ -74,9 +74,7 @@
 
     // close connection when STDIN closes (EOF or CTRL+D)
     $stdin->on('close', function () use ($connection) {
-        if ($connection->getState() === ConnectionInterface::STATE_AUTHENTICATED) {
-            $connection->close();
-        }
+        $connection->quit();
     });
 
     // close STDIN (stop reading) when connection closes

src/ConnectionInterface.php

@@ -208,17 +208,20 @@ public function getServerOptions();
     public function getState();
 
     /**
-     * Close the connection.
+     * Quits (soft-close) the connection.
      *
-     * @param callable|null $callback A callback which should be run after
-     *                                connection successfully closed.
-     *
-     * $callback signature:
+     * This method returns a promise that will resolve (with a void value) on
+     * success or will reject with an `Exception` on error. The MySQL protocol
+     * is inherently sequential, so that all commands will be performed in order
+     * and outstanding commands will be put into a queue to be executed once the
+     * previous commands are completed.
      *
-     *  function (ConnectionInterface $conn): void
+     * ```php
+     * $connection->query('CREATE TABLE test ...');
+     * $connection->quit();
+     * ```
      *
-     * @return void
-     * @throws Exception if the connection is not initialized or already closed/closing
+     * @return PromiseInterface Returns a Promise<void,Exception>
      */
-    public function close($callback = null);
+    public function quit();
 }

src/Io/Connection.php

@@ -215,21 +215,21 @@ public function getState()
         return $this->state;
     }
 
-    /**
-     * {@inheritdoc}
-     */
-    public function close($callback = null)
+    public function quit()
     {
-        $this->_doCommand(new QuitCommand($this))
-            ->on('success', function () use ($callback) {
-                $this->state = self::STATE_CLOSED;
-                $this->emit('end', [$this]);
-                $this->emit('close', [$this]);
-                if (is_callable($callback)) {
-                    $callback($this);
-                }
-            });
-        $this->state = self::STATE_CLOSEING;
+        return new Promise(function ($resolve, $reject) {
+            $this->_doCommand(new QuitCommand($this))
+                ->on('error', function ($reason) use ($reject) {
+                    $reject($reason);
+                })
+                ->on('success', function () use ($resolve) {
+                    $this->state = self::STATE_CLOSED;
+                    $this->emit('end', [$this]);
+                    $this->emit('close', [$this]);
+                    $resolve();
+                });
+            $this->state = self::STATE_CLOSEING;
+        });
     }
 
     /**

tests/FactoryTest.php

@@ -106,7 +106,7 @@ public function testConnectWithValidAuthWillRunUtilClose()
         $uri = $this->getConnectionString();
         $factory->createConnection($uri)->then(function (ConnectionInterface $connection) {
             echo 'connected.';
-            $connection->close(function ($e) {
+            $connection->quit()->then(function () {
                 echo 'closed.';
             });
         }, 'printf')->then(null, 'printf');
@@ -127,7 +127,7 @@ public function testConnectWithValidAuthCanPingAndClose()
             $connection->ping()->then(function () {
                 echo 'ping.';
             });
-            $connection->close(function ($e) {
+            $connection->quit()->then(function () {
                 echo 'closed.';
             });
         }, 'printf')->then(null, 'printf');

tests/Io/ConnectionTest.php

@@ -56,17 +56,19 @@ public function testConnectTwiceThrowsExceptionForSecondCall()
         $conn->doConnect(function () { });
     }
 
-    /**
-     * @expectedException React\MySQL\Exception
-     * @expectedExceptionMessage Can't send command
-     */
-    public function testCloseWithoutConnectThrows()
+    public function testQuitWithoutConnectRejects()
     {
         $options = $this->getConnectionOptions();
         $loop = \React\EventLoop\Factory::create();
         $conn = new Connection($loop, $options);
 
-        $conn->close(function () { });
+        $conn->quit()->done(
+            $this->expectCallableNever(),
+            function (\Exception $error) {
+                $this->assertInstanceOf('React\MySQL\Exception', $error);
+                $this->assertSame('Can\'t send command', $error->getMessage());
+            }
+        );
     }
 
     public function testQueryWithoutConnectRejects()
@@ -99,7 +101,7 @@ function (\Exception $error) {
         );
     }
 
-    public function testCloseWhileConnectingWillBeQueuedAfterConnection()
+    public function testQuitWhileConnectingWillBeQueuedAfterConnection()
     {
         $this->expectOutputString('connectedclosed');
         $options = $this->getConnectionOptions();
@@ -109,14 +111,34 @@ public function testCloseWhileConnectingWillBeQueuedAfterConnection()
         $conn->doConnect(function ($err) {
             echo $err ? $err : 'connected';
         });
-        $conn->close(function () {
+        $conn->quit()->then(function () {
             echo 'closed';
         });
 
         $loop->run();
     }
 
-    public function testPingAfterConnectWillEmitErrorWhenServerClosesConnection()
+    public function testQuitAfterQuitWhileConnectingWillBeRejected()
+    {
+        $options = $this->getConnectionOptions();
+        $loop = \React\EventLoop\Factory::create();
+        $conn = new Connection($loop, $options);
+
+        $conn->doConnect(function ($err) { });
+        $conn->quit();
+
+        $conn->quit()->done(
+            $this->expectCallableNever(),
+            function (\Exception $error) {
+                $this->assertInstanceOf('React\MySQL\Exception', $error);
+                $this->assertSame('Can\'t send command', $error->getMessage());
+            }
+        );
+
+        $loop->run();
+    }
+
+    public function testConnectWillEmitErrorWhenServerClosesConnection()
     {
         $this->expectOutputString('Connection lost');
 
@@ -142,7 +164,7 @@ public function testPingAfterConnectWillEmitErrorWhenServerClosesConnection()
         $loop->run();
     }
 
-    public function testConnectWillEmitErrorWhenServerClosesConnection()
+    public function testPingAfterConnectWillEmitErrorWhenServerClosesConnection()
     {
         $this->expectOutputString('Connection lost');
 
@@ -172,7 +194,7 @@ function ($err) {
         $loop->run();
     }
 
-    public function testPingAndCloseWhileConnectingWillBeQueuedAfterConnection()
+    public function testPingAndQuitWhileConnectingWillBeQueuedAfterConnection()
     {
         $this->expectOutputString('connectedpingclosed');
         $options = $this->getConnectionOptions();
@@ -187,14 +209,14 @@ public function testPingAndCloseWhileConnectingWillBeQueuedAfterConnection()
         }, function () {
             echo $err;
         });
-        $conn->close(function () {
+        $conn->quit()->then(function () {
             echo 'closed';
         });
 
         $loop->run();
     }
 
-    public function testPingAfterCloseWhileConnectingRejectsImmediately()
+    public function testPingAfterQuitWhileConnectingRejectsImmediately()
     {
         $this->expectOutputString('connectedclosed');
         $options = $this->getConnectionOptions();
@@ -204,7 +226,7 @@ public function testPingAfterCloseWhileConnectingRejectsImmediately()
         $conn->doConnect(function ($err) {
             echo $err ? $err : 'connected';
         });
-        $conn->close(function () {
+        $conn->quit()->then(function () {
             echo 'closed';
         });
 
@@ -217,7 +239,7 @@ public function testPingAfterCloseWhileConnectingRejectsImmediately()
         $loop->run();
     }
 
-    public function testCloseWhileConnectingWithInvalidPassWillNeverFire()
+    public function testQuitWhileConnectingWithInvalidPassWillNeverFire()
     {
         $this->expectOutputString('error');
         $options = $this->getConnectionOptions();
@@ -227,7 +249,7 @@ public function testCloseWhileConnectingWithInvalidPassWillNeverFire()
         $conn->doConnect(function ($err) {
             echo $err ? 'error' : 'connected';
         });
-        $conn->close(function () {
+        $conn->quit()->then(function () {
             echo 'never';
         });
 
@@ -260,7 +282,7 @@ public function testConnectWithValidPass()
         });
 
         $conn->ping()->then(function () use ($loop, $conn) {
-            $conn->close(function ($conn) {
+            $conn->quit()->done(function () use ($conn) {
                 $this->assertEquals($conn::STATE_CLOSED, $conn->getState());
             });
         });

tests/NoResultQueryTest.php

@@ -15,7 +15,7 @@ public function setUp()
         $connection->query('DROP TABLE IF EXISTS book');
         $connection->query($this->getDataTable());
 
-        $connection->close();
+        $connection->quit();
         $loop->run();
     }
 
@@ -28,7 +28,7 @@ public function testUpdateSimpleNonExistentReportsNoAffectedRows()
             $this->assertEquals(0, $command->affectedRows);
         });
 
-        $connection->close();
+        $connection->quit();
         $loop->run();
     }
 
@@ -42,7 +42,7 @@ public function testInsertSimpleReportsFirstInsertId()
             $this->assertEquals(1, $command->insertId);
         });
 
-        $connection->close();
+        $connection->quit();
         $loop->run();
     }
 
@@ -56,7 +56,7 @@ public function testUpdateSimpleReportsAffectedRow()
             $this->assertEquals(1, $command->affectedRows);
         });
 
-        $connection->close();
+        $connection->quit();
         $loop->run();
     }
 }