From 75e14ca2357de57a2cff86ce7998dbb05cd90b2e Mon Sep 17 00:00:00 2001
From: "steven.lewis" <stevenlewis@gowebprint.com>
Date: Mon, 16 Dec 2024 11:51:56 +0000
Subject: [PATCH] Update 6.x docs to reflect latest changes

---
 docs/getting-started.md | 18 ++++++++++--
 docs/upgrade.md         | 65 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+), 2 deletions(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index 2355244d..6af71c26 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -12,6 +12,7 @@ name, username, password, and driver options. There is one additional
 parameter that allows you to pass attributes to be set after the connection is
 made.
 
+#### Creation using constructor
 ```php
 use Aura\Sql\ExtendedPdo;
 
@@ -23,12 +24,25 @@ $pdo = new ExtendedPdo(
     []  // queries to execute after connection
 );
 ```
+#### Creation using static factory
+```php
+use Aura\Sql\ExtendedPdo;
+
+$pdo = ExtendedPdo::connect(
+    'mysql:host=localhost;dbname=test',
+    'username',
+    'password',
+    [], // driver attributes/options as key-value pairs
+    []  // queries to execute after connection
+);
+```
+
 
 Whereas the native _PDO_ connects on instantiation, _ExtendedPdo_ does not
 connect immediately. Instead, it connects only when you call a method that
 actually needs the connection to the database; e.g., on `query()`.
 
-If you want to force a connection, call the `connect()` method.
+If you want to force a connection, call the `establishConnection()` method.
 
 ```php
 // does not connect to the database
@@ -42,7 +56,7 @@ $pdo = new ExtendedPdo(
 $pdo->exec('SELECT * FROM test');
 
 // explicitly forces a connection
-$pdo->connect();
+$pdo->establishConnection();
 ```
 
 If you want to explicitly force a disconnect, call the `disconnect()` method.
diff --git a/docs/upgrade.md b/docs/upgrade.md
index 80f592b3..f0d423dc 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -1,3 +1,68 @@
+# 6.x Upgrade Notes
+
+Most changes are to provide better compatability with PHP 8.4 and above.
+
+With PHP 8.4 introducing `Pdo::connect()` as a way of creating driver specific connections.
+
+We have introducing our `ExtendedPdo::connect()` which uses the underlining PDO features then with all our
+normal added features.
+
+```php
+// does not connect to the database
+$pdo = ExtendedPdo::connect(
+    'mysql:host=localhost;dbname=test',
+    'username',
+    'password'
+);
+
+// automatically connects
+$pdo->exec('SELECT * FROM test');
+
+// explicitly forces a connection
+$pdo->establishConnection();
+```
+
+# 5.x Upgrade Notes
+
+Most changes are to provide better typing and compatability with PHP 8.1 and above.
+
+## Deprecations
+
+The main change is the deprecation of `ExtendedPdo::connect()` and will be changed in future versions starting with 6.x
+
+Older Code would look like ...
+
+```php
+// does not connect to the database
+$pdo = new ExtendedPdo(
+    'mysql:host=localhost;dbname=test',
+    'username',
+    'password'
+);
+
+// automatically connects
+$pdo->exec('SELECT * FROM test');
+
+// explicitly forces a connection
+$pdo->connect();
+```
+... and now needs to be changed to `ExtendedPdo::establishConnection()`
+
+```php
+// does not connect to the database
+$pdo = new ExtendedPdo(
+    'mysql:host=localhost;dbname=test',
+    'username',
+    'password'
+);
+
+// automatically connects
+$pdo->exec('SELECT * FROM test');
+
+// explicitly forces a connection
+$pdo->establishConnection();
+```
+
 # 3.x Upgrade Notes
 
 The vast majority of changes and breaks from the 2.x version are "under the