PDO according to 8.4 changes and feedbacks from @pmjones

.gitignore

@@ -1,2 +1,3 @@
 composer.lock
 vendor/*
+.phpunit.result.cache

docs/getting-started.md

@@ -42,7 +42,7 @@ 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 `establishConnection()` method.
+If you want to force a connection, call the `lazyConnect()` method.
 
 ```php
 // does not connect to the database
@@ -56,7 +56,7 @@ $pdo = new ExtendedPdo(
 $pdo->exec('SELECT * FROM test');
 
 // explicitly forces a connection
-$pdo->establishConnection();
+$pdo->lazyConnect();
 ```
 
 If you want to explicitly force a disconnect, call the `disconnect()` method.

docs/upgrade.md

@@ -2,10 +2,7 @@
 
 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.
+BC Break : With PHP 8.4 introducing `Pdo::connect()` as a way of creating driver specific connections.
 
 ```php
 // does not connect to the database
@@ -19,7 +16,7 @@ $pdo = ExtendedPdo::connect(
 $pdo->exec('SELECT * FROM test');
 
 // explicitly forces a connection
-$pdo->establishConnection();
+$pdo->lazyConnect();
 ```
 
 # 5.x Upgrade Notes
@@ -46,7 +43,7 @@ $pdo->exec('SELECT * FROM test');
 // explicitly forces a connection
 $pdo->connect();
 ```
-... and now needs to be changed to `ExtendedPdo::establishConnection()`
+... and now needs to be changed to `ExtendedPdo::lazyConnect()`
 
 ```php
 // does not connect to the database
@@ -60,7 +57,7 @@ $pdo = new ExtendedPdo(
 $pdo->exec('SELECT * FROM test');
 
 // explicitly forces a connection
-$pdo->establishConnection();
+$pdo->lazyConnect();
 ```
 
 # 3.x Upgrade Notes
@@ -298,4 +295,3 @@ underlying PDO instance to make those methods available, if they exist.
 
 - When dumping an ExtendedPdo object, the username and password are omitted. This
 should help keep unexpected output of stack traces from revealing credentials.
-

src/AbstractExtendedPdo.php

@@ -105,7 +105,7 @@ abstract class AbstractExtendedPdo extends PDO implements ExtendedPdoInterface
      */
     public function __call(string $name, array $arguments)
     {
-        $this->establishConnection();
+        $this->lazyConnect();
 
         if (! method_exists($this->pdo, $name)) {
             $class = get_class($this);
@@ -127,7 +127,7 @@ public function __call(string $name, array $arguments)
      */
     public function beginTransaction(): bool
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         $this->profiler->start(__FUNCTION__);
         $result = $this->pdo->beginTransaction();
         $this->profiler->finish();
@@ -145,7 +145,7 @@ public function beginTransaction(): bool
      */
     public function commit(): bool
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         $this->profiler->start(__FUNCTION__);
         $result = $this->pdo->commit();
         $this->profiler->finish();
@@ -158,7 +158,7 @@ public function commit(): bool
      *
      * @return void
      */
-    abstract public function establishConnection(): void;
+    abstract public function lazyConnect(): void;
 
     /**
      *
@@ -177,7 +177,7 @@ abstract public function disconnect(): void;
      */
     public function errorCode(): ?string
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         return $this->pdo->errorCode();
     }
 
@@ -190,7 +190,7 @@ public function errorCode(): ?string
      */
     public function errorInfo(): array
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         return $this->pdo->errorInfo();
     }
 
@@ -207,7 +207,7 @@ public function errorInfo(): array
      */
     public function exec(string $statement): int|false
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         $this->profiler->start(__FUNCTION__);
         $affectedRows = $this->pdo->exec($statement);
         $this->profiler->finish($statement);
@@ -493,7 +493,7 @@ public function getProfiler(): ProfilerInterface
      */
     public function inTransaction(): bool
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         $this->profiler->start(__FUNCTION__);
         $result = $this->pdo->inTransaction();
         $this->profiler->finish();
@@ -525,7 +525,7 @@ public function isConnected(): bool
      */
     public function lastInsertId(?string $name = null): string|false
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         $this->profiler->start(__FUNCTION__);
         $result = $this->pdo->lastInsertId($name);
         $this->profiler->finish();
@@ -550,7 +550,7 @@ public function lastInsertId(?string $name = null): string|false
      */
     public function perform(string $statement, array $values = []): PDOStatement
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         $sth = $this->prepareWithValues($statement, $values);
         $this->profiler->start(__FUNCTION__);
         $sth->execute();
@@ -574,7 +574,7 @@ public function perform(string $statement, array $values = []): PDOStatement
      */
     public function prepare(string $query, array $options = []): PDOStatement|false
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         $sth = $this->pdo->prepare($query, $options);
         return $sth;
     }
@@ -610,7 +610,7 @@ public function prepareWithValues(string $statement, array $values = []): PDOSta
             return $this->prepare($statement);
         }
 
-        $this->establishConnection();
+        $this->lazyConnect();
 
         // rebuild the statement and values
         $parser = clone $this->parser;
@@ -645,7 +645,7 @@ public function prepareWithValues(string $statement, array $values = []): PDOSta
      */
     public function query(string $query, ?int $fetchMode = null, mixed ...$fetch_mode_args): PDOStatement|false
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         $this->profiler->start(__FUNCTION__);
         $sth = $this->pdo->query($query, $fetchMode, ...$fetch_mode_args);
         $this->profiler->finish($sth->queryString);
@@ -670,9 +670,9 @@ public function query(string $query, ?int $fetchMode = null, mixed ...$fetch_mod
      */
     public function quote(string|int|array|float|null $value, int $type = self::PARAM_STR): string|false
     {
-        $this->establishConnection();
+        $this->lazyConnect();
 
-        $value = $value ?? '';
+        $value = $value ?? "";
 
         // non-array quoting
         if (! is_array($value)) {
@@ -697,7 +697,7 @@ public function quote(string|int|array|float|null $value, int $type = self::PARA
      */
     public function quoteName(string $name): string
     {
-        if (!str_contains($name, '.')) {
+        if (! str_contains($name, '.')) {
             return $this->quoteSingleName($name);
         }
 
@@ -742,7 +742,7 @@ public function quoteSingleName(string $name): string
      */
     public function rollBack(): bool
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         $this->profiler->start(__FUNCTION__);
         $result = $this->pdo->rollBack();
         $this->profiler->finish();
@@ -945,7 +945,7 @@ protected function newParser(string $driver): ParserInterface
     {
         $class = 'Aura\Sql\Parser\\' . ucfirst($driver) . 'Parser';
         if (! class_exists($class)) {
-            $class = 'Aura\Sql\Parser\SqliteParser';
+            $class = 'Aura\Sql\Parser\SqliteParser';        
         }
         return new $class();
     }
@@ -992,7 +992,7 @@ protected function setQuoteName(string $driver): void
      */
     public function getAttribute(int $attribute): bool|int|string|array|null
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         return $this->pdo->getAttribute($attribute);
     }
 
@@ -1006,7 +1006,7 @@ public function getAttribute(int $attribute): bool|int|string|array|null
      */
     public function setAttribute(int $attribute, mixed $value): bool
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         return $this->pdo->setAttribute($attribute, $value);
     }
 }

src/DecoratedPdo.php

@@ -44,14 +44,23 @@ public function __construct(PDO $pdo, ?ProfilerInterface $profiler = null)
         $this->setQuoteName($driver);
     }
 
+    public static function connect(
+        string $dsn,
+        ?string $username = null,
+        ?string $password = null,
+        ?array $options = []
+    ): static {
+        return new static(\PDO::connect($dsn, $username, $password, $options));
+    }
+
     /**
      *
      * Connects to the database.
      *
      * @return void
      *
      */
-    public function establishConnection(): void
+    public function lazyConnect(): void
     {
         // already connected
     }

src/ExtendedPdo.php

@@ -77,7 +77,7 @@ public function __construct(
         $this->setProfiler($profiler ?? new Profiler());
 
         // retain a query parser
-        $parts = explode(':', $dsn);
+        $parts = explode(":", $dsn);
         $parser = $this->newParser($parts[0]);
         $this->setParser($parser);
 
@@ -89,11 +89,9 @@ public static function connect(
         string $dsn,
         ?string $username = null,
         ?string $password = null,
-        ?array $options = [],
-        array $queries = [],
-        ?ProfilerInterface $profiler = null
+        ?array $options = []
     ): static {
-        return new static($dsn, $username, $password, $options ?? [], $queries, $profiler);
+        return new static($dsn, $username, $password, $options);
     }
 
     /**
@@ -102,7 +100,7 @@ public static function connect(
      *
      * @return void
      */
-    public function establishConnection(): void
+    public function lazyConnect(): void
     {
         if ($this->pdo) {
             return;
@@ -111,7 +109,7 @@ public function establishConnection(): void
         // connect
         $this->profiler->start(__FUNCTION__);
         list($dsn, $username, $password, $options, $queries) = $this->args;
-        $this->pdo = PDO::connect($dsn, $username, $password, $options);
+        $this->pdo = new PDO($dsn, $username, $password, $options);
         $this->profiler->finish();
 
         // connection-time queries
@@ -150,7 +148,7 @@ public function __debugInfo(): array
                 '****',
                 $this->args[3],
                 $this->args[4],
-            ]
+            ],
         ];
     }
 
@@ -163,7 +161,7 @@ public function __debugInfo(): array
      */
     public function getPdo(): PDO
     {
-        $this->establishConnection();
+        $this->lazyConnect();
         return $this->pdo;
     }
 }

src/ExtendedPdoInterface.php

@@ -28,7 +28,7 @@ interface ExtendedPdoInterface extends PdoInterface
      * Connects to the database.
      *
      */
-    public function establishConnection(): void;
+    public function lazyConnect(): void;
 
     /**
      *

src/PdoInterface.php

@@ -42,6 +42,29 @@ public function beginTransaction(): bool;
      */
     public function commit(): bool;
 
+    /**
+     *
+     * Introduced in 6.x due to PHP 8.4 change. This is a BC break for Aura.Sql.
+     *
+     * @param string $dsn The Data Source Name, or DSN, contains the information required to connect to the database.
+     *
+     * @param string | null $username  The user name for the DSN string. This parameter is optional for some PDO drivers.
+     *
+     * @param string | null $password The password for the DSN string. This parameter is optional for some PDO drivers.
+     *
+     * @param array | null $options  A key=>value array of driver-specific connection options.
+     *
+     * @return \PDO Returns an instance of a generic PDO instance.
+     *
+     * @see https://www.php.net/manual/en/pdo.connect.php
+     */
+    public static function connect(
+        string $dsn,
+        ?string $username = null,
+        #[\SensitiveParameter] ?string $password = null,
+        ?array $options = null
+    ): static;
+
     /**
      *
      * Gets the most recent error code.
@@ -83,6 +106,15 @@ public function exec(string $statement): int|false;
      */
     public function getAttribute(int $attribute): bool|int|string|array|null;
 
+    /**
+     *
+     * Returns all currently available PDO drivers.
+     *
+     * @return array
+     *
+     */
+    public static function getAvailableDrivers(): array;
+
     /**
      *
      * Is a transaction currently active?
@@ -178,13 +210,4 @@ public function rollBack(): bool;
      *
      */
     public function setAttribute(int $attribute, mixed $value): bool;
-
-    /**
-     *
-     * Returns all currently available PDO drivers.
-     *
-     * @return array
-     *
-     */
-    public static function getAvailableDrivers(): array;
 }