#77 chore: Deprecate legacy methods in ConnectionInterface

src/Connection.php

@@ -1222,11 +1222,11 @@ public function getCacheSize(): int
      * An internal wrapper to dbsafeString, used to process a complete array of parameters
      * as used by prepared statements.
      *
-     * @param array<array-key, BackedEnum|EscapeableParameterInterface|scalar|null> $params
+     * @param array<array-key, BackedEnum|EscapeableParameterInterface|scalar|Stringable|null> $params
      * @param list<bool>|false $escapes An array of boolean for each param, used to block the escaping of html-special chars.
      *                                  If not passed, all params will be cleaned.
      *
-     * @return list<scalar|null>
+     * @return list<scalar|Stringable|null>
      *
      * @see Db::dbsafeString($string, $htmlSpecialChars = true)
      */
@@ -1246,6 +1246,10 @@ private function dbsafeParams(array $params, array | false $escapes = []): array
                 continue;
             }
 
+            if ($param instanceof EscapeableParameterInterface) {
+                continue;
+            }
+
             if ($escapes !== false) {
                 if (isset($escapes[$key])) {
                     $param = $this->dbsafeString($param, $escapes[$key], false);
@@ -1263,7 +1267,11 @@ private function dbsafeParams(array $params, array | false $escapes = []): array
     /**
      * Makes a string db-safe.
      *
-     * @return ($input is float ? float : ($input is int ? int : ($input is bool ? int<0,1> : ($input is null ? null : ($input is scalar ? string : mixed)))))
+     * @template T
+     *
+     * @param T $input
+     *
+     * @return ($input is float ? float : ($input is int ? int : ($input is bool ? int<0,1> : ($input is null ? null : ($input is scalar ? string : ($input is Stringable ? string : T))))))
      * @deprecated we need to get rid of this
      */
     public function dbsafeString(mixed $input, bool $htmlSpecialChars = true, bool $addSlashes = true): mixed
@@ -1285,6 +1293,10 @@ public function dbsafeString(mixed $input, bool $htmlSpecialChars = true, bool $
             return $input;
         }
 
+        if ($input instanceof Stringable) {
+            return (string) $input;
+        }
+
         // escape special chars
         if (is_scalar($input) && $htmlSpecialChars) {
             $input = html_entity_decode((string) $input, ENT_COMPAT, 'UTF-8');

src/ConnectionInterface.php

@@ -43,7 +43,7 @@ interface ConnectionInterface extends DoctrineConnectionInterface
      * @throws QueryException
      * @return array<int, array<string, mixed>>
      *
-     * @see fetchAllAssociative
+     * @deprecated Use {@see self::fetchAllAssociative()} instead.
      */
     public function getPArray(string $query, array $params = [], ?int $start = null, ?int $end = null, bool $cache = true, array $escapes = []): array;
 
@@ -61,7 +61,7 @@ public function getPArray(string $query, array $params = [], ?int $start = null,
      * @throws QueryException
      * @return array<string, mixed>
      *
-     * @see fetchAssociative
+     * @deprecated Use {@see self::fetchAssociative()} instead.
      */
     public function getPRow(string $query, array $params = [], int $number = 0, bool $cache = true, array $escapes = []): array;
 
@@ -108,7 +108,8 @@ public function getGenerator(string $query, array $params = [], int $chunkSize =
      * @param list<bool> $escapes An array of booleans for each param, used to block the escaping of html-special chars.
      *                            If not passed, all params will be cleaned.
      * @throws QueryException
-     * @see executeStatement
+     *
+     * @deprecated Use {@see self::executeStatement()} instead.
      */
     public function _pQuery(string $query, array $params = [], array $escapes = []): bool;
 

src/EscapeableParameterInterface.php

@@ -13,8 +13,14 @@
 
 namespace Artemeon\Database;
 
+use Stringable;
+
 interface EscapeableParameterInterface
 {
     public function isEscape(): bool;
+
+    /**
+     * @return scalar|Stringable|null
+     */
     public function getValue(): mixed;
 }