From a093d87df088d86b01a8e676239950cd31d39d25 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20L=C3=BCck?= <christian@clue.engineering>
Date: Tue, 18 Oct 2022 09:26:51 +0200
Subject: [PATCH] Change default charset encoding to `utf8mb4` for full UTF-8
 support

---
 README.md                 | 18 ++++++++----------
 src/Factory.php           | 20 +++++++++-----------
 tests/ResultQueryTest.php |  2 +-
 3 files changed, 18 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 6b1c147..6fe2343 100644
--- a/README.md
+++ b/README.md
@@ -175,11 +175,10 @@ authentication. You can explicitly pass a custom timeout value in seconds
 $factory->createConnection('localhost?timeout=0.5');
 ```
 
-By default, the connection uses the `utf8` charset encoding. Note that
-MySQL's `utf8` encoding (also known as `utf8mb3`) predates what is now
-known as UTF-8 and for historical reasons doesn't support emojis and
-other characters. If you want full UTF-8 support, you can pass the
-charset encoding like this:
+By default, the connection provides full UTF-8 support (using the
+`utf8mb4` charset encoding). This should usually not be changed for most
+applications nowadays, but for legacy reasons you can change this to use
+a different ASCII-compatible charset encoding like this:
 
 ```php
 $factory->createConnection('localhost?charset=utf8mb4');
@@ -291,11 +290,10 @@ timeout) like this:
 $factory->createLazyConnection('localhost?idle=0.1');
 ```
 
-By default, the connection uses the `utf8` charset encoding. Note that
-MySQL's `utf8` encoding (also known as `utf8mb3`) predates what is now
-known as UTF-8 and for historical reasons doesn't support emojis and
-other characters. If you want full UTF-8 support, you can pass the
-charset encoding like this:
+By default, the connection provides full UTF-8 support (using the
+`utf8mb4` charset encoding). This should usually not be changed for most
+applications nowadays, but for legacy reasons you can change this to use
+a different ASCII-compatible charset encoding like this:
 
 ```php
 $factory->createLazyConnection('localhost?charset=utf8mb4');
diff --git a/src/Factory.php b/src/Factory.php
index 1ccee7e..dea8c6d 100644
--- a/src/Factory.php
+++ b/src/Factory.php
@@ -143,11 +143,10 @@ public function __construct(LoopInterface $loop = null, ConnectorInterface $conn
      * $factory->createConnection('localhost?timeout=0.5');
      * ```
      *
-     * By default, the connection uses the `utf8` charset encoding. Note that
-     * MySQL's `utf8` encoding (also known as `utf8mb3`) predates what is now
-     * known as UTF-8 and for historical reasons doesn't support emojis and
-     * other characters. If you want full UTF-8 support, you can pass the
-     * charset encoding like this:
+     * By default, the connection provides full UTF-8 support (using the
+     * `utf8mb4` charset encoding). This should usually not be changed for most
+     * applications nowadays, but for legacy reasons you can change this to use
+     * a different ASCII-compatible charset encoding like this:
      *
      * ```php
      * $factory->createConnection('localhost?charset=utf8mb4');
@@ -183,7 +182,7 @@ public function createConnection(
                 isset($parts['user']) ? rawurldecode($parts['user']) : 'root',
                 isset($parts['pass']) ? rawurldecode($parts['pass']) : '',
                 isset($parts['path']) ? rawurldecode(ltrim($parts['path'], '/')) : '',
-                isset($args['charset']) ? $args['charset'] : 'utf8'
+                isset($args['charset']) ? $args['charset'] : 'utf8mb4'
             );
         } catch (\InvalidArgumentException $e) {
             return \React\Promise\reject($e);
@@ -363,11 +362,10 @@ public function createConnection(
      * $factory->createLazyConnection('localhost?idle=0.1');
      * ```
      *
-     * By default, the connection uses the `utf8` charset encoding. Note that
-     * MySQL's `utf8` encoding (also known as `utf8mb3`) predates what is now
-     * known as UTF-8 and for historical reasons doesn't support emojis and
-     * other characters. If you want full UTF-8 support, you can pass the
-     * charset encoding like this:
+     * By default, the connection provides full UTF-8 support (using the
+     * `utf8mb4` charset encoding). This should usually not be changed for most
+     * applications nowadays, but for legacy reasons you can change this to use
+     * a different ASCII-compatible charset encoding like this:
      *
      * ```php
      * $factory->createLazyConnection('localhost?charset=utf8mb4');
diff --git a/tests/ResultQueryTest.php b/tests/ResultQueryTest.php
index 80e6892..2375a52 100644
--- a/tests/ResultQueryTest.php
+++ b/tests/ResultQueryTest.php
@@ -361,7 +361,7 @@ public function testSelectCharsetDefaultsToUtf8()
         $connection->query('SELECT @@character_set_client')->then(function (QueryResult $command) {
             $this->assertCount(1, $command->resultRows);
             $this->assertCount(1, $command->resultRows[0]);
-            $this->assertSame('utf8', reset($command->resultRows[0]));
+            $this->assertSame('utf8mb4', reset($command->resultRows[0]));
         });
 
         $connection->quit();