Improve documentation

Author: Riimu

src/Connection/Connection.php

@@ -3,22 +3,100 @@
 namespace Simply\Database\Connection;
 
 /**
- * Connection.
+ * Interface for database connections that provide basic query functionality to an SQL database.
  * @author Riikka Kalliomäki <[email protected]>
  * @copyright Copyright (c) 2018 Riikka Kalliomäki
  * @license http://opensource.org/licenses/mit-license.php MIT License
  */
 interface Connection
 {
+    /** Ascending sorting order for select queries. */
     public const ORDER_ASCENDING = 1;
+
+    /** Descending sorting order for select queries. */
     public const ORDER_DESCENDING = 2;
 
+    /**
+     * Returns the underlying PDO connection to the database.
+     * @return \PDO The underlying PDO connection to the database
+     */
     public function getConnection(): \PDO;
-    public function insert(string $table, array $values, string & $primaryKey = null): \PDOStatement;
-    public function select(array $fields, string $table, array $where, array $orderBy = [], int $limit = null): \PDOStatement;
+
+    /**
+     * Inserts a row the database with given column values.
+     * @param string $table Name of the table to insert
+     * @param array $values Associative array of column values for the insert
+     * @param string|null $primaryKey Name of automatic primary key column that will be overwritten with its value.
+     * @return \PDOStatement The resulting PDO statement after executing the query
+     */
+    public function insert(string $table, array $values, & $primaryKey = null): \PDOStatement;
+
+    /**
+     * Selects rows from the database.
+     *
+     * The conditions provided to the query must be an associative array of columns and expected values. Any scalar
+     * value and null are supported for equal comparison. If an array is provided as an value for the column, then
+     * the value must by any of the provided values in the array, i.e. an "IN" SQL comparison. Null is also supported
+     * as one of the values in the array.
+     *
+     * The sorting order provides list of columns to sort by in order of importance with the appropriate sorting
+     * direction. Note that the limit argument is ignore if no sorting columns have been provided, as the order of
+     * rows is undefined.
+     *
+     * @param string[] $fields List of fields to select from the database
+     * @param string $table The name of the table to select
+     * @param array $where Conditions for the select query
+     * @param int[] $orderBy Associative array of columns to sort by and the sorting direction for each column
+     * @param int|null $limit Maximum number of rows to return on sorted statement
+     * @return \PDOStatement The resulting PDO statement after executing the query
+     */
+    public function select(
+        array $fields,
+        string $table,
+        array $where,
+        array $orderBy = [],
+        int $limit = null
+    ): \PDOStatement;
+
+    /**
+     * Updates rows in the database.
+     * @param string $table The table to update
+     * @param array $values Associative array of columns and values to update
+     * @param array $where Conditions for the updated row, similar to select queries
+     * @return \PDOStatement The resulting PDO statement after executing the query
+     */
     public function update(string $table, array $values, array $where): \PDOStatement;
+
+    /**
+     * Deletes rows from the database.
+     * @param string $table The table where to delete rows
+     * @param array $where Conditions for the delete query, similar to select query
+     * @return \PDOStatement The resulting PDO statement after executing the query
+     */
     public function delete(string $table, array $where): \PDOStatement;
+
+    /**
+     * Executes an arbitrary SQL query in the database.
+     * @param string $sql The SQL query to execute
+     * @param array $parameters Array of parameters to pass to the query
+     * @return \PDOStatement The resulting PDO statement after executing the query
+     */
     public function query(string $sql, array $parameters = []): \PDOStatement;
+
+    /**
+     * Returns an escaped table name aliased to the given alias.
+     * @param string $table The name of the table to escape
+     * @param string $alias The alias for the table or empty string for no alias
+     * @return string The escaped table name for an SQL query
+     */
     public function formatTable(string $table, string $alias = ''): string;
+
+    /**
+     * Returns a comma separated list of escaped field names from given table aliased with given prefix.
+     * @param string[] $fields List of fields to escape
+     * @param string $table The name or alias of the table for the fields
+     * @param string $prefix Prefix to use for each field in the alias
+     * @return string Comma separated list of escaped fields
+     */
     public function formatFields(array $fields, string $table = '', string $prefix = ''): string;
 }

src/Connection/MySqlConnection.php

@@ -5,16 +5,20 @@
 use Simply\Database\Connection\Provider\ConnectionProvider;
 
 /**
- * MySqlConnection.
+ * Provides the basic functionality to operate on a MySQL database.
  * @author Riikka Kalliomäki <[email protected]>
  * @copyright Copyright (c) 2018 Riikka Kalliomäki
  * @license http://opensource.org/licenses/mit-license.php MIT License
  */
 class MySqlConnection implements Connection
 {
-    /** @var ConnectionProvider */
+    /** @var ConnectionProvider The provider for the PDO connection */
     private $provider;
 
+    /**
+     * MySqlConnection constructor.
+     * @param ConnectionProvider $provider The provider for the PDO connection
+     */
     public function __construct(ConnectionProvider $provider)
     {
         $this->provider = $provider;
@@ -25,7 +29,7 @@ public function getConnection(): \PDO
         return $this->provider->getConnection();
     }
 
-    public function insert(string $table, array $values, string & $primaryKey = null): \PDOStatement
+    public function insert(string $table, array $values, & $primaryKey = null): \PDOStatement
     {
         $parameters = [];
         $result = $this->query($this->formatQuery([
@@ -40,8 +44,13 @@ public function insert(string $table, array $values, string & $primaryKey = null
         return $result;
     }
 
-    public function select(array $fields, string $table, array $where, array $orderBy = [], int $limit = null): \PDOStatement
-    {
+    public function select(
+        array $fields,
+        string $table,
+        array $where,
+        array $orderBy = [],
+        int $limit = null
+    ): \PDOStatement {
         $parameters = [];
 
         return $this->query($this->formatQuery([
@@ -113,6 +122,12 @@ public function formatTable(string $table, string $alias = ''): string
         return $this->escapeIdentifier($table);
     }
 
+    /**
+     * Formats the conditions for the SQL query.
+     * @param array $conditions The conditions for the SQL query
+     * @param array $parameters Array of parameters to fill
+     * @return string Formatted conditions for the query
+     */
     private function formatConditions(array $conditions, array & $parameters): string
     {
         if (!$conditions) {
@@ -129,10 +144,11 @@ private function formatConditions(array $conditions, array & $parameters): strin
     }
 
     /**
-     * @param string $field
-     * @param mixed $value
-     * @param array $parameters
-     * @return string
+     * Formats a single condition for the SQL query.
+     * @param string $field The name of the field
+     * @param mixed $value Expected value for the fields
+     * @param array $parameters Array of parameters to fill
+     * @return string The formatted condition for the query
      */
     private function formatClause(string $field, $value, array & $parameters): string
     {
@@ -164,12 +180,23 @@ private function formatClause(string $field, $value, array & $parameters): strin
         return "$escaped = ?";
     }
 
+    /**
+     * Formats a list of parenthesis enclosed parameters for an SQL query.
+     * @param array $values List of values
+     * @param array $parameters Array of parameters to fill
+     * @return string The formatted parenthesis enclosed list of parameter placeholders
+     */
     private function formatParameters(array $values, array & $parameters): string
     {
         array_push($parameters, ... array_values($values));
         return sprintf('(%s)', implode(', ', array_fill(0, \count($values), '?')));
     }
 
+    /**
+     * Formats the order clause for a select query.
+     * @param array $order The order for the select query
+     * @return string The formatted ORDER BY clause for the query
+     */
     private function formatOrder(array $order): string
     {
         $clauses = [];
@@ -181,6 +208,11 @@ private function formatOrder(array $order): string
         return implode(', ', $clauses);
     }
 
+    /**
+     * Returns the appropriate SQL sorting order for the sorting constant.
+     * @param int $order The sorting constant
+     * @return string The SQL representation for the given sorting order
+     */
     private function formatDirection(int $order): string
     {
         if ($order === self::ORDER_ASCENDING) {
@@ -194,6 +226,12 @@ private function formatDirection(int $order): string
         throw new \InvalidArgumentException('Invalid sorting direction');
     }
 
+    /**
+     * Formats the LIMIT clause for a select query.
+     * @param int|null $limit The maximum number of rows to return or null for no limit
+     * @param array $parameters Array of parameters to fill
+     * @return string The formatted LIMIT clause for the select query
+     */
     private function formatLimit(?int $limit, array & $parameters): string
     {
         if ($limit === null) {
@@ -204,6 +242,12 @@ private function formatLimit(?int $limit, array & $parameters): string
         return '?';
     }
 
+    /**
+     * Formats value assignments in UPDATE query.
+     * @param array $values Associate array of columns and values
+     * @param array $parameters Array of parameters to fill
+     * @return string The formatted list of assignments for the UPDATE query
+     */
     private function formatAssignments(array $values, array & $parameters): string
     {
         if (!$values) {
@@ -220,11 +264,21 @@ private function formatAssignments(array $values, array & $parameters): string
         return implode(', ', $assignments);
     }
 
+    /**
+     * Escapes a MySQL query identifier.
+     * @param string $identifier The identifier to escape
+     * @return string The escaped identifier
+     */
     private function escapeIdentifier(string $identifier): string
     {
         return "`$identifier`";
     }
 
+    /**
+     * Formats an arbitrary SQL query based on given clauses.
+     * @param array $clauses Associative array of SQL clauses and their contents
+     * @return string The complete formatted SQL query
+     */
     private function formatQuery(array $clauses): string
     {
         $parts = [];
@@ -254,10 +308,11 @@ public function query(string $sql, array $parameters = []): \PDOStatement
     }
 
     /**
-     * @param \PDOStatement $query
-     * @param int|string $name
-     * @param mixed $value
-     * @return bool
+     * Binds an SQL query parameter to the PDO statement fo the query
+     * @param \PDOStatement $query The PDO statement for binding the value
+     * @param int|string $name The name of the placeholder
+     * @param mixed $value The value to bind
+     * @return bool True if the binding was successful, false if not
      */
     private function bindQueryParameter(\PDOStatement $query, $name, $value): bool
     {

src/Connection/Provider/ConnectionProvider.php

@@ -3,12 +3,16 @@
 namespace Simply\Database\Connection\Provider;
 
 /**
- * ConnectionProvider.
+ * Interface for objects that can initialize and provide the PDO instance for database connectors.
  * @author Riikka Kalliomäki <[email protected]>
  * @copyright Copyright (c) 2018 Riikka Kalliomäki
  * @license http://opensource.org/licenses/mit-license.php MIT License
  */
 interface ConnectionProvider
 {
+    /**
+     * Provides the active PDO connection and initializes it if necessary.
+     * @return \PDO An active PDO connection
+     */
     public function getConnection(): \PDO;
-}
+}

src/Connection/Provider/GenericConnectionProvider.php

@@ -3,19 +3,35 @@
 namespace Simply\Database\Connection\Provider;
 
 /**
- * LazyConnectionProvider.
+ * A generic lazy loading connector that can take any kind of PDO data source name.
  * @author Riikka Kalliomäki <[email protected]>
  * @copyright Copyright (c) 2018 Riikka Kalliomäki
  * @license http://opensource.org/licenses/mit-license.php MIT License
  */
 class GenericConnectionProvider implements ConnectionProvider
 {
+    /** @var string The data source name for the PDO connection */
     private $dsn;
+
+    /** @var string The username for the PDO connection */
     private $username;
+
+    /** @var string The password for the PDO connection */
     private $password;
+
+    /** @var array Initial PDO options provided when initializing the connection */
     private $options;
+
+    /** @var \PDO The active PDO connection */
     private $pdo;
 
+    /**
+     * GenericConnectionProvider constructor.
+     * @param string $dsn The data source name for the PDO connection
+     * @param string $username The username for the PDO connection
+     * @param string $password The password for the PDO connection
+     * @param array $options Initial PDO options provided when initializing the connection
+     */
     public function __construct(string $dsn, string $username, string $password, array $options)
     {
         $this->dsn = $dsn;
@@ -26,13 +42,17 @@ public function __construct(string $dsn, string $username, string $password, arr
 
     public function getConnection(): \PDO
     {
-        if (empty($this->pdo)) {
+        if (!isset($this->pdo)) {
             $this->pdo = $this->initializeConnection();
         }
 
         return $this->pdo;
     }
 
+    /**
+     * Initializes the PDO connection when first requested.
+     * @return \PDO The initialized PDO connection.
+     */
     protected function initializeConnection(): \PDO
     {
         return new \PDO($this->dsn, $this->username, $this->password, $this->options);