Add PDO adapter + Symfony DBAL-style prepared statement API (fully BC)

legacy/Connection.php

@@ -1,11 +1,11 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Nip\Database;
 
 /**
- * Class Connection
- * @package Nip\Database
- * @deprecated use \Nip\Database\Connections\Connection
+ * @deprecated Use \Nip\Database\Connections\Connection instead.
  */
 class Connection extends \Nip\Database\Connections\Connection
 {

legacy/Manager.php

@@ -1,49 +1,39 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Nip\Database;
 
 use Nip\Database\Connections\Connection;
 
 /**
- * Class Manager.
- * @deprecated use \Nip\Database\DatabaseManager
+ * @deprecated Use \Nip\Database\DatabaseManager instead.
  */
 class Manager extends DatabaseManager
 {
-    /**
-     * @param $config
-     *
-     * @return Connection
-     */
-    public function newConnectionFromConfig($config)
+    public function newConnectionFromConfig(mixed $config): Connection
     {
-        $connection = $this->createNewConnection(
+        return $this->createNewConnection(
             $config->adapter,
             $config->host,
             $config->user,
             $config->password,
             $config->name
         );
-
-        return $connection;
     }
 
-    /**
-     * @param $adapter
-     * @param $host
-     * @param $user
-     * @param $password
-     * @param $database
-     *
-     * @return Connection
-     */
-    public function createNewConnection($adapter, $host, $user, $password, $database)
-    {
+    public function createNewConnection(
+        string $adapter,
+        string $host,
+        string $user,
+        string $password,
+        string $database
+    ): Connection {
         try {
             $connection = $this->newConnection();
 
-            $adapter = $connection->newAdapter($adapter);
-            $connection->setAdapter($adapter);
+            $adapterInstance = $connection->newAdapter($adapter);
+            $connection->setAdapter($adapterInstance);
 
             $connection->connect($host, $user, $password, $database);
             $this->initNewConnection($connection);
@@ -59,20 +49,14 @@ public function createNewConnection($adapter, $host, $user, $password, $database
         return $connection;
     }
 
-    /**
-     * @param $connection
-     */
-    public function initNewConnection($connection)
+    public function initNewConnection(Connection $connection): void
     {
         if ($this->getBootstrap()->getDebugBar()->isEnabled()) {
             $this->getBootstrap()->getDebugBar()->initDatabaseAdapter($connection->getAdapter());
         }
     }
 
-    /**
-     * @return Connection
-     */
-    public function newConnection()
+    public function newConnection(): Connection
     {
         return new Connection(false);
     }

src/Adapters/AbstractAdapter.php

@@ -1,30 +1,34 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Nip\Database\Adapters;
 
 use Nip\Database\Adapters\Profiler\Profiler;
 
 /**
- * Class AbstractAdapter.
+ * Base adapter: wraps the driver-specific query() call with optional profiling.
+ *
  * @package Nip\Database\Adapters
  */
 abstract class AbstractAdapter
 {
-    /**
-     * @var null|Profiler
-     */
-    protected $_profiler = null;
+    protected ?Profiler $_profiler = null;
 
     /**
-     * Executes SQL query
+     * Execute a SQL string, optionally recording a profiling entry.
      *
-     * @param string $sql
-     * @return mixed
+     * Triggers a PHP warning and returns false when the underlying driver
+     * reports an error – this preserves the legacy behaviour so that callers
+     * that check the return value continue to work.
      */
-    public function execute($sql)
+    public function execute(string $sql): mixed
     {
+        $profile = null;
+
         if ($this->hasProfiler()) {
-            if ($profile = $this->getProfiler()->start()) {
+            $profile = $this->getProfiler()->start();
+            if ($profile !== null) {
                 $profile->setName($sql);
                 $profile->setAdapter($this);
             }
@@ -38,71 +42,56 @@ public function execute($sql)
 
         if ($result !== false) {
             return $result;
-        } else {
-            trigger_error($this->error() . " [$sql]", E_USER_WARNING);
         }
 
+        trigger_error($this->error() . " [$sql]", E_USER_WARNING);
+
         return false;
     }
 
-    /**
-     * @return bool
-     */
-    public function hasProfiler()
+    public function hasProfiler(): bool
     {
-        return is_object($this->_profiler);
+        return $this->_profiler instanceof Profiler;
     }
 
-    /**
-     * @return Profiler|null
-     */
-    public function getProfiler()
+    public function getProfiler(): ?Profiler
     {
         return $this->_profiler;
     }
 
-    /**
-     * @param Profiler $profiler
-     */
-    public function setProfiler($profiler)
+    public function setProfiler(Profiler $profiler): void
     {
         $this->_profiler = $profiler;
     }
 
-    /**
-     * @param string $sql
-     */
-    abstract public function query($sql);
+    /** Execute a raw SQL string against the driver. */
+    abstract public function query(string $sql): mixed;
 
-    abstract public function error();
+    abstract public function error(): string;
 
-    public function newProfiler()
+    public function newProfiler(): Profiler
     {
-        $profiler = new Profiler();
-
-        return $profiler;
+        return new Profiler();
     }
 
-    abstract public function quote($value);
+    abstract public function quote(mixed $value): int|float|string;
 
-    abstract public function cleanData($data);
+    abstract public function cleanData(mixed $data): mixed;
 
     abstract public function connect(
-        $host = false,
-        $user = false,
-        $password = false,
-        $database = false,
-        $newLink = false
-    );
+        string $host = '',
+        string $user = '',
+        string $password = '',
+        string $database = '',
+        bool $newLink = false
+    ): mixed;
 
-    /**
-     * @param string $table
-     */
-    abstract public function describeTable($table);
+    abstract public function describeTable(string $table): array|false;
 
-    abstract public function disconnect();
+    abstract public function disconnect(): void;
 
-    abstract public function lastInsertID();
+    abstract public function lastInsertID(): int|string;
 
-    abstract public function affectedRows();
+    abstract public function affectedRows(): int;
 }
+

src/Adapters/AdapterInterface.php

@@ -1,38 +1,74 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Nip\Database\Adapters;
 
 /**
- * Interface AdapterInterface
+ * Contract for a low-level database adapter.
+ *
+ * All methods that interact with the underlying driver are declared here so
+ * that higher-level components (Connection, Query, Result) can program against
+ * this interface rather than a concrete driver class.
+ *
  * @package Nip\Database\Adapters
  */
 interface AdapterInterface
 {
-    public function execute($sql);
+    /** Execute a raw SQL string and return the driver result resource or false. */
+    public function execute(string $sql): mixed;
 
-    public function lastInsertID();
+    /** Return the auto-increment ID produced by the most recent INSERT. */
+    public function lastInsertID(): int|string;
 
-    public function affectedRows();
+    /** Return the number of rows affected by the most recent DML statement. */
+    public function affectedRows(): int;
 
-    public function numRows($result);
+    /** Return the number of rows in a result resource. */
+    public function numRows(mixed $result): int;
 
-    public function fetchArray($result);
+    /** Fetch the next row as a numeric array, or null when exhausted. */
+    public function fetchArray(mixed $result): ?array;
 
-    public function fetchAssoc($result);
+    /** Fetch the next row as an associative array, or null when exhausted. */
+    public function fetchAssoc(mixed $result): ?array;
 
-    public function fetchObject($result);
+    /** Fetch the next row as a \stdClass object, or null when exhausted. */
+    public function fetchObject(mixed $result): ?object;
 
-    public function result($result, $row, $field);
+    /** Return a single field value from a result resource. */
+    public function result(mixed $result, int $row, string $field): mixed;
 
-    public function freeResults($result);
+    /** Release the memory associated with a result resource. */
+    public function freeResults(mixed $result): void;
 
-    public function describeTable($table);
+    /**
+     * Return column/index metadata for the given table.
+     *
+     * @return array{fields: array<string, array<string, mixed>>, indexes: array<string, array<string, mixed>>}|false
+     */
+    public function describeTable(string $table): array|false;
 
-    public function quote($value);
+    /**
+     * Quote a scalar value for safe embedding in a SQL string.
+     *
+     * Prefer using parameterised queries where possible; this method exists
+     * as a fallback for the legacy query-builder.
+     */
+    public function quote(mixed $value): int|float|string;
 
-    public function cleanData($data);
+    /**
+     * Escape a raw string value so it is safe to use inside a quoted SQL literal.
+     *
+     * @param mixed $data
+     * @return mixed
+     */
+    public function cleanData(mixed $data): mixed;
 
-    public function error();
+    /** Return the error message produced by the most recent failed statement. */
+    public function error(): string;
 
-    public function disconnect();
+    /** Close the underlying driver connection. */
+    public function disconnect(): void;
 }
+