Add establishConnection() for interoperability with future versions

docs/getting-started.md

@@ -28,7 +28,11 @@ 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.
+
+> Previous `connect()` method has been deprecated due to the introduction of 
+> ```PDO::connect()``` in [PHP 8.4](https://www.php.net/releases/8.4/en.php#pdo_driver_specific_subclasses), 
+> so we encourage users to use `establishConnection()` instead.
 
 ```php
 // does not connect to the database
@@ -42,7 +46,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.

docs/upgrade.md

@@ -1,3 +1,44 @@
+# 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

src/ExtendedPdo.php

@@ -89,6 +89,8 @@ public function __construct(
      *
      * Connects to the database.
      *
+     * @deprecated use establishConnection() as future versions will be using establishConnection()
+     *
      * @return void
      */
     public function connect(): void
@@ -109,6 +111,17 @@ public function connect(): void
         }
     }
 
+    /**
+     *
+     * alias of connect() for interoperability with future versions Aura.Sql
+     *
+     * @return void
+     */
+    public function establishConnection(): void
+    {
+        $this->connect();
+    }
+
     /**
      *
      * Disconnects from the database.