WIP on connection management

src/Custom.php

@@ -18,6 +18,7 @@ class Custom
      * @param array $parameters The parameters for the query
      * @param PDO $pdo The database connection on which the query should be run
      * @return PDOStatement The result of executing the query
+     * @throws DocumentException If the query execution is unsuccessful
      */
     public static function runQuery(string $query, array $parameters, PDO $pdo): PDOStatement
     {
@@ -28,8 +29,9 @@ class Custom
             $stmt->bindValue($key, $value);
         }
         if ($debug) echo '<pre>SQL: ' . $stmt->queryString . '</pre>';
-        $stmt->execute();
-        return $stmt;
+        if ($stmt->execute()) return $stmt;
+        $keyword = explode(' ', $query, 2)[0];
+        throw new DocumentException("Error executing $keyword statement: " . $stmt->errorCode());
     }
 
     /**
@@ -87,8 +89,12 @@ class Custom
      */
     public static function nonQuery(string $query, array $parameters, ?PDO $pdo = null): void
     {
-        $stmt = self::runQuery($query, $parameters, $pdo ?? Configuration::dbConn());
-        if ($stmt->errorCode()) throw new DocumentException('Error executing command: ' . $stmt->errorCode());
+        try {
+            $stmt = self::runQuery($query, $parameters, is_null($pdo) ? $actualPDO = Configuration::dbConn() : $pdo);
+            $stmt = null;
+        } finally {
+            if (isset($actualPDO)) $actualPDO = null;
+        }
     }
 
     /**
@@ -105,9 +111,6 @@ class Custom
     public static function scalar(string $query, array $parameters, Mapper $mapper, ?PDO $pdo = null): mixed
     {
         $stmt = self::runQuery($query, $parameters, $pdo ?? Configuration::dbConn());
-        if ($stmt->errorCode()) {
-            throw new DocumentException('Error retrieving scalar value: ' . $stmt->errorCode());
-        }
         if ($stmt->rowCount() > 0) {
             $first = $stmt->fetch(PDO::FETCH_NUM);
             return $first ? $mapper->map($first) : false;

src/DocumentList.php

@@ -13,16 +13,16 @@ use PDOStatement;
  *
  * @template TDoc The domain class for items returned by this list
  */
-readonly class DocumentList
+class DocumentList
 {
     /**
      * Constructor
      *
-     * @param PDO $pdo The database connection against which the query was opened
-     * @param PDOStatement $result The result of the query
+     * @param PDO|null $pdo The database connection against which the query was opened
+     * @param PDOStatement|null $result The result of the query
      * @param Mapper<TDoc> $mapper The mapper to deserialize JSON
      */
-    private function __construct(private PDO $pdo, private PDOStatement $result, private Mapper $mapper) { }
+    private function __construct(private ?PDO $pdo, private ?PDOStatement $result, private Mapper $mapper) { }
 
     /**
      * Construct a new document list
@@ -35,12 +35,8 @@ readonly class DocumentList
      */
     public static function create(string $query, array $parameters, Mapper $mapper): static
     {
-        $pdo  = Configuration::dbConn();
-        $stmt = Custom::runQuery($query, $parameters, $pdo);
-        if ($stmt->errorCode()) {
-            throw new DocumentException('Error retrieving data: ' . $stmt->errorCode());
-        }
-        return new static($pdo, $stmt, $mapper);
+        $pdo = Configuration::dbConn();
+        return new static($pdo, Custom::runQuery($query, $parameters, $pdo), $mapper);
     }
 
     /**
@@ -53,5 +49,7 @@ readonly class DocumentList
         if ($this->result) {
             while ($row = $this->result->fetch(PDO::FETCH_ASSOC)) yield $this->mapper->map($row);
         }
+        $this->result = null;
+        $this->pdo    = null;
     }
 }