Simplify API, remove ConnectionInterface

README.md

@@ -24,13 +24,13 @@ It is written in pure PHP and does not require any extensions.
 * [Usage](#usage)
   * [MysqlClient](#mysqlclient)
     * [__construct()](#__construct)
-  * [ConnectionInterface](#connectioninterface)
     * [query()](#query)
     * [queryStream()](#querystream)
     * [ping()](#ping)
     * [quit()](#quit)
     * [close()](#close)
-    * [Events](#events)
+    * [error event](#error-event)
+    * [close event](#close-event)
 * [Install](#install)
 * [Tests](#tests)
 * [License](#license)
@@ -68,21 +68,21 @@ The `MysqlClient` is responsible for exchanging messages with your MySQL server
 and keeps track of pending queries.
 
 ```php
-$connection = new React\MySQL\MysqlClient($uri);
+$mysql = new React\MySQL\MysqlClient($uri);
 
-$connection->query(…);
+$mysql->query(…);
 ```
 
-This method immediately returns a "virtual" connection implementing the
-[`ConnectionInterface`](#connectioninterface) that can be used to
-interface with your MySQL database. Internally, it lazily creates the
-underlying database connection only on demand once the first request is
-invoked on this instance and will queue all outstanding requests until
-the underlying connection is ready. This underlying connection will be
-reused for all requests until it is closed. By default, idle connections
-will be held open for 1ms (0.001s) when not used. The next request will
-either reuse the existing connection or will automatically create a new
-underlying connection if this idle time is expired.
+This class represents a connection that is responsible for communicating
+with your MySQL server instance, managing the connection state and sending
+your database queries. Internally, it creates the underlying database
+connection only on demand once the first request is invoked on this
+instance and will queue all outstanding requests until the underlying
+connection is ready. This underlying connection will be reused for all
+requests until it is closed. By default, idle connections will be held
+open for 1ms (0.001s) when not used. The next request will either reuse
+the existing connection or will automatically create a new underlying
+connection if this idle time is expired.
 
 From a consumer side this means that you can start sending queries to the
 database right away while the underlying connection may still be
@@ -100,7 +100,7 @@ longer than the idle period.
 Note that creating the underlying connection will be deferred until the
 first request is invoked. Accordingly, any eventual connection issues
 will be detected once this instance is first used. You can use the
-`quit()` method to ensure that the "virtual" connection will be soft-closed
+`quit()` method to ensure that the connection will be soft-closed
 and no further commands can be enqueued. Similarly, calling `quit()` on
 this instance when not currently connected will succeed immediately and
 will not have to wait for an actual underlying connection.
@@ -200,12 +200,6 @@ here in order to use the [default loop](https://github.com/reactphp/event-loop#l
 This value SHOULD NOT be given unless you're sure you want to explicitly use a
 given event loop instance.
 
-### ConnectionInterface
-
-The `ConnectionInterface` represents a connection that is responsible for
-communicating with your MySQL server instance, managing the connection state
-and sending your database queries.
-
 #### query()
 
 The `query(string $query, array $params = []): PromiseInterface<QueryResult>` method can be used to
@@ -218,8 +212,8 @@ and outstanding queries will be put into a queue to be executed once the
 previous queries are completed.
 
 ```php
-$connection->query('CREATE TABLE test ...');
-$connection->query('INSERT INTO test (id) VALUES (1)');
+$mysql->query('CREATE TABLE test ...');
+$mysql->query('INSERT INTO test (id) VALUES (1)');
 ```
 
 If this SQL statement returns a result set (such as from a `SELECT`
@@ -231,7 +225,7 @@ unknown or known to be too large to fit into memory, you should use the
 [`queryStream()`](#querystream) method instead.
 
 ```php
-$connection->query($query)->then(function (QueryResult $command) {
+$mysql->query($query)->then(function (QueryResult $command) {
     if (isset($command->resultRows)) {
         // this is a response to a SELECT etc. with some rows (0+)
         print_r($command->resultFields);
@@ -254,7 +248,7 @@ You can optionally pass an array of `$params` that will be bound to the
 query like this:
 
 ```php
-$connection->query('SELECT * FROM user WHERE id > ?', [$id]);
+$mysql->query('SELECT * FROM user WHERE id > ?', [$id]);
 ```
 
 The given `$sql` parameter MUST contain a single statement. Support
@@ -275,7 +269,7 @@ into memory. If you know your result set to not exceed a few dozens or
 hundreds of rows, you may want to use the [`query()`](#query) method instead.
 
 ```php
-$stream = $connection->queryStream('SELECT * FROM user');
+$stream = $mysql->queryStream('SELECT * FROM user');
 $stream->on('data', function ($row) {
     echo $row['name'] . PHP_EOL;
 });
@@ -288,7 +282,7 @@ You can optionally pass an array of `$params` that will be bound to the
 query like this:
 
 ```php
-$stream = $connection->queryStream('SELECT * FROM user WHERE id > ?', [$id]);
+$stream = $mysql->queryStream('SELECT * FROM user WHERE id > ?', [$id]);
 ```
 
 This method is specifically designed for queries that return a result set
@@ -303,7 +297,7 @@ rows to a [`WritableStreamInterface`](https://github.com/reactphp/stream#writabl
 like this:
 
 ```php
-$connection->queryStream('SELECT * FROM user')->pipe($formatter)->pipe($logger);
+$mysql->queryStream('SELECT * FROM user')->pipe($formatter)->pipe($logger);
 ```
 
 Note that as per the underlying stream definition, calling `pause()` and
@@ -331,7 +325,7 @@ and outstanding command will be put into a queue to be executed once the
 previous queries are completed.
 
 ```php
-$connection->ping()->then(function () {
+$mysql->ping()->then(function () {
     echo 'OK' . PHP_EOL;
 }, function (Exception $e) {
     echo 'Error: ' . $e->getMessage() . PHP_EOL;
@@ -350,8 +344,8 @@ 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();
+$mysql->query('CREATE TABLE test ...');
+$mysql->quit();
 ```
 
 #### close()
@@ -363,26 +357,21 @@ Unlike the `quit()` method, this method will immediately force-close the
 connection and reject all outstanding commands.
 
 ```php
-$connection->close();
+$mysql->close();
 ```
 
 Forcefully closing the connection will yield a warning in the server logs
 and should generally only be used as a last resort. See also
 [`quit()`](#quit) as a safe alternative.
 
-#### Events
-
-Besides defining a few methods, this interface also implements the
-`EventEmitterInterface` which allows you to react to certain events:
-
-##### error event
+#### error event
 
 The `error` event will be emitted once a fatal error occurs, such as
 when the connection is lost or is invalid.
 The event receives a single `Exception` argument for the error instance.
 
 ```php
-$connection->on('error', function (Exception $e) {
+$mysql->on('error', function (Exception $e) {
     echo 'Error: ' . $e->getMessage() . PHP_EOL;
 });
 ```
@@ -391,12 +380,12 @@ This event will only be triggered for fatal errors and will be followed
 by closing the connection. It is not to be confused with "soft" errors
 caused by invalid SQL queries.
 
-##### close event
+#### close event
 
 The `close` event will be emitted once the connection closes (terminates).
 
 ```php
-$connection->on('close', function () {
+$mysql->on('close', function () {
     echo 'Connection closed' . PHP_EOL;
 });
 ```