Rename some methods and classes and improve documention

Author: bancer

README.md

@@ -63,7 +63,7 @@ use NativeSQLMapperTrait;
 
 ```php
 $ArticlesTable = $this->fetchTable(ArticlesTable::class);
-$stmt = $ArticlesTable->prepareSQL("
+$stmt = $ArticlesTable->prepareNativeStatement("
     SELECT
         id     AS Articles__id,
         title  AS Articles__title
@@ -72,7 +72,7 @@ $stmt = $ArticlesTable->prepareSQL("
 ");
 $stmt->bindValue('title', 'My Article Title');
 /** @var \App\Model\Entity\Article[] $entities */
-$entities = $ArticlesTable->fromNativeQuery($stmt)->all();
+$entities = $ArticlesTable->mapNativeStatement($stmt)->all();
 ```
 
 `$entities` now contains hydrated `Article` entities based on the SQL result.
@@ -82,7 +82,7 @@ $entities = $ArticlesTable->fromNativeQuery($stmt)->all();
 ## 🔁 hasMany Example Using Minimalistic SQL
 
 ```php
-$stmt = $ArticlesTable->prepareSQL("
+$stmt = $ArticlesTable->prepareNativeStatement("
     SELECT
         a.id        AS Articles__id,
         title       AS Articles__title,
@@ -93,7 +93,7 @@ $stmt = $ArticlesTable->prepareSQL("
     LEFT JOIN comments AS c
         ON a.id=c.article_id
 ");
-$entities = $ArticlesTable->fromNativeQuery($stmt)->all();
+$entities = $ArticlesTable->mapNativeStatement($stmt)->all();
 ```
 `$entities` now contains an array of Article objects with Comment objects as children.
 
@@ -114,7 +114,7 @@ Notice that `FROM` and `JOIN` clauses may use short or long aliases or no aliase
 
 ```php
 $ArticlesTable = $this->fetchTable(ArticlesTable::class);
-$stmt = $ArticlesTable->prepareSQL("
+$stmt = $ArticlesTable->prepareNativeStatement("
     SELECT
         Articles.id     AS Articles__id,
         Articles.title  AS Articles__title,
@@ -126,7 +126,7 @@ $stmt = $ArticlesTable->prepareSQL("
     LEFT JOIN tags AS Tags
         ON Tags.id=ArticlesTags.tag_id
 ");
-$entities = $ArticlesTable->fromNativeQuery($stmt)->all();
+$entities = $ArticlesTable->mapNativeStatement($stmt)->all();
 ```
 You can find more examples in tests - https://github.com/bancer/native-sql-mapper/tree/develop/tests/TestCase/ORM.
 

composer.json

@@ -30,8 +30,17 @@
     "minimum-stability": "stable",
     "scripts": {
         "all-tests": [
+            "echo '------------------------------------------'",
+            "echo '---           PHPSTAN TESTS            ---'",
+            "echo '------------------------------------------'",
             "@phpstan",
+            "echo '------------------------------------------'",
+            "echo '---           PHPCS TESTS              ---'",
+            "echo '------------------------------------------'",
             "@phpcs",
+            "echo '------------------------------------------'",
+            "echo '---           PHPUNIT TESTS            ---'",
+            "echo '------------------------------------------'",
             "@phpunit"
         ],
         "ci-tests": [
@@ -42,7 +51,8 @@
         "phpstan": "vendor/bin/phpstan analyse -c phpstan.neon",
         "phpcs": "vendor/bin/phpcs --standard=PSR12 -p src tests",
         "phpunit": "vendor/bin/phpunit tests",
-        "phpunit-coverage": "XDEBUG_MODE=coverage vendor/bin/phpunit tests --coverage-text"
+        "phpunit-coverage": "XDEBUG_MODE=coverage vendor/bin/phpunit tests --coverage-text",
+        "phpunit-coverage-html": "XDEBUG_MODE=coverage vendor/bin/phpunit tests --coverage-html coverage/"
     },
     "config": {
         "allow-plugins": {

src/ORM/StatementQuery.php src/ORM/NativeQueryResultMapper.phpsrc/ORM/StatementQuery.php renamed to src/ORM/NativeQueryResultMapper.php

@@ -7,17 +7,53 @@
 use Cake\Database\StatementInterface;
 use Cake\ORM\Table;
 
-class StatementQuery
+/**
+ * Wrapper around a prepared SQL statement that executes it
+ * and hydrates the result set into CakePHP entities using
+ * a mapping strategy inferred from column aliases.
+ *
+ * This class is created via `prepareNativeStatement()` and
+ * `mapNativeStatement()` in the `NativeSQLMapperTrait`.
+ */
+class NativeQueryResultMapper
 {
+    /**
+     * The root table used to determine entity classes,
+     * associations, and hydration rules.
+     *
+     * @var \Cake\ORM\Table
+     */
     protected Table $rootTable;
+
+    /**
+     * The prepared PDO statement to be executed.
+     *
+     * @var \Cake\Database\StatementInterface
+     */
     protected StatementInterface $stmt;
+
+    /**
+     * Whether the statement has already been executed.
+     *
+     * @var bool
+     */
     protected bool $isExecuted;
 
     /**
-     * @var mixed[]|null
+     * Custom mapping strategy used to hydrate entities.
+     * If null, a MappingStrategy will be automatically built
+     * based on detected column aliases.
+     *
+     * @var array<string,mixed>|null
      */
     protected $mapStrategy = null;
 
+    /**
+     * Constructor.
+     *
+     * @param \Cake\ORM\Table $rootTable The root table instance.
+     * @param \Cake\Database\StatementInterface $stmt The prepared statement.
+     */
     public function __construct(Table $rootTable, StatementInterface $stmt)
     {
         $this->rootTable = $rootTable;
@@ -26,21 +62,26 @@ public function __construct(Table $rootTable, StatementInterface $stmt)
     }
 
     /**
-     * Provide a custom mapping strategy.
+     * Provide a custom mapping strategy instead of relying
+     * on automatic alias inference.
+     *
+     * The structure must match the output of MappingStrategy::toArray().
      *
-     * @param mixed[] $strategy
+     * @param array<string,mixed> $strategy Mapping configuration.
      * @return $this
      */
-    public function mapStrategy(array $strategy): self
+    public function setMappingStrategy(array $strategy): self
     {
         $this->mapStrategy = $strategy;
         return $this;
     }
 
     /**
-     * Execute and hydrate results.
+     * Execute the SQL statement if not executed yet, fetch all rows,
+     * build (or use) the mapping strategy, and hydrate the result set
+     * into entities.
      *
-     * @return \Cake\Datasource\EntityInterface[]
+     * @return \Cake\Datasource\EntityInterface[] Hydrated entity list.
      */
     public function all(): array
     {
@@ -64,10 +105,17 @@ public function all(): array
     }
 
     /**
-     * Extracts aliases of the columns from the query's result set.
+     * Extract column aliases used in the SQL result set.
+     *
+     * Each column must follow `{Alias}__{column}` format.
+     * Throws UnknownAliasException if the alias format is invalid.
+     *
+     * @param array<int,array<string,mixed>|mixed> $rows Result set rows.
+     * @return string[] Sorted list of unique aliases.
      *
-     * @param mixed[] $rows Result set rows.
-     * @return string[]
+     * @throws \InvalidArgumentException If the first row is not an array.
+     * @throws \Bancer\NativeQueryMapper\ORM\UnknownAliasException
+     *         If a column does not follow expected alias format.
      */
     protected function extractAliases(array $rows): array
     {

src/ORM/NativeSQLMapperTrait.php

@@ -6,24 +6,57 @@
 
 use Cake\Database\StatementInterface;
 
+/**
+ * NativeSQLMapperTrait
+ *
+ * Provides convenience functions for working with native SQL queries in
+ * CakePHP Table classes. It allows preparing raw SQL statements using
+ * the table's connection driver and wrapping executed statements in a
+ * NativeQueryResultMapper object, enabling automatic entity and association
+ * mapping based on CakePHP-style column aliases.
+ */
 trait NativeSQLMapperTrait
 {
     /**
-     * Create a StatementQuery wrapper for a prepared statement.
+     * Wrap a prepared statement in a NativeQueryResultMapper, enabling the
+     * mapping of native SQL result sets into fully hydrated entities.
      *
-     * @param \Cake\Database\StatementInterface $stmt
-     * @return \Bancer\NativeQueryMapper\ORM\StatementQuery
+     * Typically used after calling prepareNativeStatement() and binding
+     * the statement parameters.
+     *
+     * Example:
+     * ```php
+     * $stmt = $ArticlesTable->prepareNativeStatement("
+     *     SELECT id AS Articles__id FROM articles
+     * ");
+     * $entities = $ArticlesTable->mapNativeStatement($stmt)->all();
+     * ```
+     *
+     * @param \Cake\Database\StatementInterface $stmt Prepared statement.
+     * @return \Bancer\NativeQueryMapper\ORM\NativeQueryResultMapper Wrapper for ORM-level mapping of native results.
      */
-    public function fromNativeQuery(StatementInterface $stmt): StatementQuery
+    public function mapNativeStatement(StatementInterface $stmt): NativeQueryResultMapper
     {
-        return new StatementQuery($this, $stmt);
+        return new NativeQueryResultMapper($this, $stmt);
     }
 
     /**
-     * @param string $stmt
-     * @return \Cake\Database\StatementInterface
+     * Prepare a native SQL statement using the table's database
+     * connection driver. This provides direct access to low-level PDO-style
+     * prepared statements while still using the CakePHP connection.
+     *
+     * Example:
+     * ```php
+     * $stmt = $ArticlesTable->prepareNativeStatement("
+     *     SELECT id AS Articles__id FROM articles WHERE title = :title
+     * ");
+     * $stmt->bindValue('title', 'Example');
+     * ```
+     *
+     * @param string $stmt Raw SQL string to prepare.
+     * @return \Cake\Database\StatementInterface Prepared statement ready for parameter binding and execution.
      */
-    public function prepareSQL(string $stmt): StatementInterface
+    public function prepareNativeStatement(string $stmt): StatementInterface
     {
         return $this->getConnection()->getDriver()->prepare($stmt);
     }