Docblock Documentation

Author: tlmcclatchey

src/ConnectionManager.php

@@ -6,10 +6,10 @@
  * facilitating the execution of queries and type conversion through registered type converters.
  *
  * @package CommonPHP
- * @subpackage DatabaseManager
+ * @subpackage DatabaseEngine
  * @author Timothy McClatchey <timothy@commonphp.org>
  * @copyright 2024 CommonPHP.org
- * @license    http://opensource.org/licenses/MIT MIT License
+ * @license http://opensource.org/licenses/MIT MIT License
  * @noinspection PhpUnused
  */
 
@@ -22,6 +22,7 @@
 use CommonPHP\DatabaseEngine\Exceptions\ConnectionNotRegisteredException;
 use CommonPHP\DatabaseEngine\Exceptions\DatabaseEngineException;
 use CommonPHP\DatabaseEngine\Exceptions\EmptyConnectionNameException;
+use CommonPHP\DatabaseEngine\Exceptions\EmptyTypeNameException;
 use CommonPHP\DatabaseEngine\Exceptions\ResultNotReadException;
 use CommonPHP\DatabaseEngine\Support\TypeConversionProvider;
 use CommonPHP\DatabaseEngine\TypeConverters\BoolTypeConverter;
@@ -51,6 +52,7 @@ final class ConnectionManager
      * Registers default type converters if not already supported by the provided TypeConversionProvider.
      *
      * @param TypeConversionProvider|null $typeConversionProvider The type conversion provider to use. A new instance is created if null is passed.
+     * @throws EmptyTypeNameException
      */
     public function __construct(?TypeConversionProvider $typeConversionProvider = null)
     {

src/Contracts/AbstractEnumTypeConverter.php

@@ -1,19 +1,47 @@
 <?php
 
+/**
+ * Implements conversion logic for PHP 8.1+ enumeration types to and from database representations.
+ * This abstract class defines the functionality to serialize enum instances for storage in a database
+ * and deserialize stored values back into enum instances. It ensures that only instances of the specified
+ * enum class are handled, throwing exceptions if conversion fails due to type mismatches or unrecognized values.
+ *
+ * @package CommonPHP
+ * @subpackage DatabaseEngine
+ * @author Timothy McClatchey <timothy@commonphp.org>
+ * @copyright 2024 CommonPHP.org
+ * @license http://opensource.org/licenses/MIT MIT License
+ * @noinspection PhpUnused
+ * @noinspection PhpMixedReturnTypeCanBeReducedInspection
+ */
+
 namespace CommonPHP\DatabaseEngine\Contracts;
 
 use BackedEnum;
 use CommonPHP\DatabaseEngine\Exceptions\EnumDoesNotExistException;
 use CommonPHP\DatabaseEngine\Exceptions\TypeDecodingFailedException;
 use CommonPHP\DatabaseEngine\Exceptions\TypeEncodingFailedException;
 use CommonPHP\DatabaseEngine\Support\TypeConversionProvider;
+use Override;
 use UnitEnum;
 
 class AbstractEnumTypeConverter implements TypeConverterContract
 {
-    /** @var string|UnitEnum|BackedEnum */
+    /**
+     * The fully qualified class name of the enum this converter handles.
+     * It must be a valid enumeration class, either a UnitEnum or BackedEnum.
+     *
+     * @var string|UnitEnum|BackedEnum
+     */
     private string|UnitEnum|BackedEnum $enumClass;
 
+    /**
+     * Initializes a new instance of the AbstractEnumTypeConverter for a specific enum class.
+     * Verifies the existence of the enum class, throwing an exception if the class does not exist.
+     *
+     * @param string $enumClass The fully qualified class name of the enum to be handled.
+     * @throws EnumDoesNotExistException If the specified enum class does not exist.
+     */
     public function __construct(string $enumClass)
     {
         if (!enum_exists($enumClass))
@@ -23,7 +51,16 @@ public function __construct(string $enumClass)
         $this->enumClass = $enumClass;
     }
 
-    #[\Override] final function encode(mixed $data): mixed
+    /**
+     * Encodes an enum instance into a database-storable representation.
+     * Currently, this method converts backed enums to their scalar values, ensuring the data is
+     * compatible for database storage. It validates that the provided data matches the expected enum type.
+     *
+     * @param mixed $data The enum instance to encode.
+     * @return mixed The encoded value suitable for database storage.
+     * @throws TypeEncodingFailedException If encoding fails due to a type mismatch.
+     */
+    #[Override] final function encode(mixed $data): mixed
     {
         $typeName = TypeConversionProvider::getTypeOf($data);
         if ($typeName !== $this->enumClass)
@@ -33,7 +70,15 @@ public function __construct(string $enumClass)
         return $data->name;
     }
 
-    #[\Override] final function decode(mixed $data): mixed
+    /**
+     * Decodes a database-stored value back into an enum instance.
+     * It iterates through the enum cases to find a match for the stored value, returning the corresponding enum case.
+     *
+     * @param mixed $data The database-stored value to decode.
+     * @return mixed The corresponding enum instance, if a match is found.
+     * @throws TypeDecodingFailedException If decoding fails because the stored value does not match any enum case.
+     */
+    #[Override] final function decode(mixed $data): mixed
     {
         foreach (($this->enumClass)::cases() as $case)
         {

src/Contracts/BuildableQueryContract.php

@@ -1,10 +1,31 @@
 <?php
 
+/**
+ * Defines the contract for buildable query objects within the CommonPHP Database Engine.
+ * Implementors of this interface are capable of constructing a Query object, which encapsulates
+ * an SQL statement and its associated parameters. This interface facilitates a standardized approach
+ * to dynamically building and executing database queries across various components of the database engine.
+ *
+ * @package CommonPHP
+ * @subpackage DatabaseEngine
+ * @author Timothy McClatchey <timothy@commonphp.org>
+ * @copyright 2024 CommonPHP.org
+ * @license http://opensource.org/licenses/MIT MIT License
+ * @noinspection PhpUnused
+ */
+
 namespace CommonPHP\DatabaseEngine\Contracts;
 
 use CommonPHP\DatabaseEngine\Query;
 
 interface BuildableQueryContract
 {
+    /**
+     * Constructs and returns a Query object.
+     * This method allows implementing classes to define their own logic for building a query,
+     * encapsulating the specifics of query construction within the implementing class.
+     *
+     * @return Query The constructed Query object.
+     */
     function build(): Query;
 }

src/Contracts/ConnectorContract.php

@@ -1,5 +1,18 @@
 <?php
 
+/**
+ * Specifies the essential functionalities that any database connector within the CommonPHP Database Engine must provide.
+ * This includes capabilities for executing queries against a database and retrieving the last insert ID after an insert operation.
+ * The interface ensures a consistent approach to database interactions, allowing for flexible integration of various database engines.
+ *
+ * @package CommonPHP
+ * @subpackage DatabaseEngine
+ * @author Timothy McClatchey <timothy@commonphp.org>
+ * @copyright 2024 CommonPHP.org
+ * @license http://opensource.org/licenses/MIT MIT License
+ * @noinspection PhpUnused
+ */
+
 namespace CommonPHP\DatabaseEngine\Contracts;
 
 use CommonPHP\DatabaseEngine\Query;
@@ -8,6 +21,22 @@
 
 interface ConnectorContract
 {
+    /**
+     * Retrieves the last insert ID generated by the last INSERT operation.
+     * This method is essential for obtaining auto-generated keys after data insertion, providing a way to reference newly created entities.
+     *
+     * @return string|int The last insert ID as a string or integer, depending on the database's handling of such IDs.
+     */
     function getLastInsertId(): string|int;
+
+    /**
+     * Executes a given query using this connector, utilizing the provided TypeConversionProvider for any necessary type conversions.
+     * This method serves as a bridge between the application's logic and the underlying database engine, facilitating the execution of both simple
+     * and complex queries while ensuring type safety and conversion consistency.
+     *
+     * @param TypeConversionProvider $typeConversionProvider The provider to use for type conversion during query execution.
+     * @param Query|BuildableQueryContract $query The query to execute, which can be a raw Query object or an object that builds to a Query.
+     * @return Result The result of the query execution, encapsulated within a Result object.
+     */
     function execute(TypeConversionProvider $typeConversionProvider, Query|BuildableQueryContract $query): Result;
 }

src/Contracts/TypeConverterContract.php

@@ -1,9 +1,43 @@
 <?php
 
+/**
+ * Defines the contract for type converters within the CommonPHP Database Engine.
+ * Type converters are responsible for transforming PHP data types to their corresponding database types and vice versa.
+ * This interface ensures a standardized approach to type conversion across different database implementations, enabling
+ * the seamless integration of custom data types and enhancing the overall flexibility and robustness of database interactions.
+ *
+ * Implementing this contract requires providing methods for both encoding (PHP to database) and decoding (database to PHP)
+ * operations, catering to the diverse needs of data persistence and retrieval within the application.
+ *
+ * @package CommonPHP
+ * @subpackage DatabaseEngine
+ * @author Timothy McClatchey <timothy@commonphp.org>
+ * @copyright 2024 CommonPHP.org
+ * @license http://opensource.org/licenses/MIT MIT License
+ * @noinspection PhpUnused
+ */
+
 namespace CommonPHP\DatabaseEngine\Contracts;
 
 interface TypeConverterContract
 {
+    /**
+     * Encodes a PHP data type into a format suitable for database storage.
+     * This method is designed to convert PHP types into their database-specific representations, ensuring that
+     * data is correctly stored in a way that maintains its integrity and type information.
+     *
+     * @param mixed $data The PHP data to be encoded for the database.
+     * @return mixed The data in a database-compatible format.
+     */
     function encode(mixed $data): mixed;
+
+    /**
+     * Decodes a database data type back into its corresponding PHP type.
+     * This process allows for the retrieval of data from the database and its conversion into PHP types, facilitating
+     * the easy manipulation and use of database data within PHP applications.
+     *
+     * @param mixed $data The data retrieved from the database to be decoded into a PHP type.
+     * @return mixed The PHP representation of the data.
+     */
     function decode(mixed $data): mixed;
 }

src/Exceptions/ColumnNotFoundException.php

@@ -1,13 +1,31 @@
 <?php
 
+/**
+ * Exception thrown when a requested column is not found within a result set.
+ * It provides details about the missing column and available columns, aiding in debugging and validation of result processing.
+ *
+ * @package CommonPHP
+ * @subpackage DatabaseEngine
+ * @author Timothy McClatchey <timothy@commonphp.org>
+ * @copyright 2024 CommonPHP.org
+ * @license http://opensource.org/licenses/MIT MIT License
+ * @noinspection PhpUnused
+ */
+
 namespace CommonPHP\DatabaseEngine\Exceptions;
 
 use Throwable;
 
 class ColumnNotFoundException extends DatabaseEngineException
 {
-    public function __construct(string $name, array $names, int $code = 0, ?Throwable $previous = null)
+    /**
+     * Initializes a new instance of ColumnNotFoundException.
+     * @param string $name The name of the missing column.
+     * @param array $names An array of available column names for reference.
+     * @param ?Throwable $previous The previous throwable used for exception chaining.
+     */
+    public function __construct(string $name, array $names, ?Throwable $previous = null)
     {
-        parent::__construct('The column `'.$name.'` is not defined in the result ('.implode(', ', $names).')', $code, $previous);
+        parent::__construct('The column `'.$name.'` is not defined in the result ('.implode(', ', $names).')', 1201, $previous);
     }
-}
+}

src/Exceptions/ConnectionAlreadyDefinedException.php

@@ -1,13 +1,30 @@
 <?php
 
+/**
+ * Exception thrown when attempting to define a database connection that already exists.
+ * This prevents overwriting existing connections, ensuring connection management integrity.
+ *
+ * @package CommonPHP
+ * @subpackage DatabaseEngine
+ * @author Timothy McClatchey <timothy@commonphp.org>
+ * @copyright 2024 CommonPHP.org
+ * @license http://opensource.org/licenses/MIT MIT License
+ * @noinspection PhpUnused
+ */
+
 namespace CommonPHP\DatabaseEngine\Exceptions;
 
 use Throwable;
 
 class ConnectionAlreadyDefinedException extends DatabaseEngineException
 {
-    public function __construct(string $name, int $code = 0, ?Throwable $previous = null)
+    /**
+     * Initializes a new instance of ConnectionAlreadyDefinedException.
+     * @param string $name The name of the connection attempted to be defined again.
+     * @param ?Throwable $previous The previous throwable used for exception chaining.
+     */
+    public function __construct(string $name, ?Throwable $previous = null)
     {
-        parent::__construct('Could not use the connection name `'.$name.'` because it already exists', $code, $previous);
+        parent::__construct('Could not use the connection name `'.$name.'` because it already exists', 1202, $previous);
     }
-}
+}

src/Exceptions/ConnectionNotRegisteredException.php

@@ -1,13 +1,30 @@
 <?php
 
+/**
+ * Exception thrown when a requested database connection name is not registered within the connection manager.
+ * This highlights issues with connection configuration or naming mismatches in the application.
+ *
+ * @package CommonPHP
+ * @subpackage DatabaseEngine
+ * @author Timothy McClatchey <timothy@commonphp.org>
+ * @copyright 2024 CommonPHP.org
+ * @license http://opensource.org/licenses/MIT MIT License
+ * @noinspection PhpUnused
+ */
+
 namespace CommonPHP\DatabaseEngine\Exceptions;
 
 use Throwable;
 
 class ConnectionNotRegisteredException extends DatabaseEngineException
 {
-    public function __construct(string $name, int $code = 0, ?Throwable $previous = null)
+    /**
+     * Initializes a new instance of ConnectionNotRegisteredException.
+     * @param string $name The name of the unregistered connection.
+     * @param ?Throwable $previous The previous throwable used for exception chaining.
+     */
+    public function __construct(string $name, ?Throwable $previous = null)
     {
-        parent::__construct('There is no connection with the name `'.$name.'`', $code, $previous);
+        parent::__construct('There is no connection with the name `'.$name.'`', 1203, $previous);
     }
-}
+}

src/Exceptions/DatabaseEngineException.php

@@ -1,14 +1,33 @@
 <?php
 
+/**
+ * Represents the base exception class for all database engine-related errors within CommonPHP.
+ * This class serves as a foundation for more specific database exceptions, providing a unified
+ * structure for error handling and reporting across the database engine components.
+ *
+ * @package CommonPHP
+ * @subpackage DatabaseEngine
+ * @author Timothy McClatchey <timothy@commonphp.org>
+ * @copyright 2024 CommonPHP.org
+ * @license http://opensource.org/licenses/MIT MIT License
+ * @noinspection PhpUnused
+ */
+
 namespace CommonPHP\DatabaseEngine\Exceptions;
 
 use Exception;
 use Throwable;
 
 class DatabaseEngineException extends Exception
 {
-    public function __construct(string $message = "", int $code = 0, ?Throwable $previous = null)
+    /**
+     * Initializes a new instance of the DatabaseEngineException.
+     * @param string $message The error message.
+     * @param int $code The exception code, default is 1200 for the base database engine exception.
+     * @param ?Throwable $previous The previous throwable used for exception chaining.
+     */
+    public function __construct(string $message = "", int $code = 1200, ?Throwable $previous = null)
     {
         parent::__construct($message, $code, $previous);
     }
-}
+}