docs for all structs

Author: Smoren

qrm/ActiveRecord/ActiveRecordTrait.php

@@ -6,6 +6,11 @@
 
 use app\qrm\Base\QueryRelationManagerException;
 
+/**
+ * Trait ActiveRecordTrait
+ * Trait для упрощения построения запросов с помощью QueryRelationManager
+ * @package app\qrm\ActiveRecord
+ */
 trait ActiveRecordTrait
 {
     /**

qrm/ActiveRecord/QueryRelationDataProvider.php

@@ -9,6 +9,11 @@
 use yii\db\Connection;
 use yii\db\Query;
 
+/**
+ * Class QueryRelationDataProvider
+ * DataProvider для запросов QueryRelationManager
+ * @package app\qrm\ActiveRecord
+ */
 class QueryRelationDataProvider extends BaseDataProvider
 {
     /**

qrm/ActiveRecord/QueryRelationManager.php

@@ -18,12 +18,13 @@
 class QueryRelationManager extends QueryRelationManagerBase
 {
     /**
-     * @param string $relationName
-     * @param string $relationAlias
-     * @param string|null $parentAlias
-     * @param string $joinType
-     * @param string|null $extraJoinCondition
-     * @param array|null $extraJoinParams
+     * Подключение отношения таблицы к запросу, используя данные из модели ActiveRecord
+     * @param string $relationName имя отношения, прописанное в модели ActiveRecord
+     * @param string $relationAlias псевдоним присоединяемой таблицы
+     * @param string|null $parentAlias псевдоним таблицы, к которой очуществляется присоединение (по умолчанию — основная таблица запроса)
+     * @param string $joinType тип присоединения ("inner", "left", "right")
+     * @param string|null $extraJoinCondition дополнительные условия присоединения
+     * @param array|null $extraJoinParams динамические значения дополнительных условий присодинения
      * @return $this
      * @throws QueryRelationManagerException
      */
@@ -106,7 +107,7 @@ protected function createQuery(): QueryWrapperInterface
 
     /**
      * Возвращает список полей таблицы
-     * @param string $className
+     * @param string $className имя класса ORM-модели
      * @return array
      * @throws QueryRelationManagerException
      */
@@ -125,7 +126,7 @@ protected function getTableFields(string $className): array
 
     /**
      * Возвращает поля первичного ключа таблицы
-     * @param string $className
+     * @param string $className имя класса ORM-модели
      * @return array
      * @throws QueryRelationManagerException
      */

qrm/ActiveRecord/QueryWrapper.php

@@ -7,9 +7,15 @@
 
 use app\qrm\Base\QueryWrapperInterface;
 
+/**
+ * Class QueryWrapper
+ * Класс-обертка для ActiveQuery
+ * @package app\qrm\ActiveRecord
+ */
 class QueryWrapper implements QueryWrapperInterface
 {
     /**
+     * Объект ActiveQuery
      * @var \yii\db\Query
      */
     protected $query;

qrm/Base/Helpers/JoinCondition.php

@@ -3,47 +3,71 @@
 
 namespace app\qrm\Base\Helpers;
 
-
+/**
+ * Class JoinCondition
+ * Класс-хранилище данных join-отношения
+ * @package app\qrm\Base\Helpers
+ */
 class JoinCondition
 {
+    /**
+     * Отношение "один к одному"
+     */
     const TYPE_SINGLE = 1;
+
+    /**
+     * Отношение "один ко многим"
+     */
     const TYPE_MULTIPLE = 2;
 
     /**
-     * @var int
+     * @var int тип отношения (1 — "один к одному" или 2 — "один ко многим")
      */
     public $type;
 
     /**
-     * @var Table
+     * @var Table присоединяемая таблица
      */
     public $table;
 
     /**
-     * @var Table
+     * @var Table таблица, к которой осуществляется присоединение
      */
     public $joinTo;
 
     /**
-     * @var array
+     * @var array основное условие присоединения
+     * ["поле присоединяемой таблицы" => "поле таблицы, к которой осуществляется присоединение", ...]
      */
     public $joinCondition;
 
     /**
-     * @var string
+     * @var string способ присоединения ("inner", "left", "right")
      */
     public $joinType;
 
     /**
-     * @var string
+     * @var string дополнительное условие присоединения
+     * Например: "and some_field = :some_value"
      */
     public $extraJoinCondition;
 
     /**
-     * @var array
+     * @var array значения параметров дополнительного условия присоединения
+     * Например: [":some_value" => "123", ...]
      */
     public $extraJoinParams;
 
+    /**
+     * JoinCondition constructor.
+     * @param int $type тип отношения (1 — "один к одному" или 2 — "один ко многим")
+     * @param Table $table таблица, к которой осуществляется присоединение
+     * @param Table $joinTo таблица, к которой осуществляется присоединение
+     * @param array $joinCondition основное условие присоединения
+     * @param string $joinType способ присоединения ("inner", "left", "right")
+     * @param string|null $extraJoinCondition string дополнительное условие присоединения
+     * @param array $extraJoinParams значения параметров дополнительного условия присоединения
+     */
     public function __construct(
         int $type, Table $table, Table $joinTo, array $joinCondition,
         string $joinType = 'left', ?string $extraJoinCondition = null, array $extraJoinParams = []
@@ -58,6 +82,10 @@ public function __construct(
         $this->extraJoinParams = $extraJoinParams;
     }
 
+    /**
+     * Возвращает часть SQL-запроса, содержащую условия присоединения таблицы
+     * @return string
+     */
     public function stringify(): string
     {
         $joins = [];

qrm/Base/Helpers/JoinConditionManager.php renamed to qrm/Base/Helpers/JoinConditionCollection.php

@@ -6,20 +6,26 @@
 
 use app\qrm\Base\QueryRelationManagerException;
 
-class JoinConditionManager
+/**
+ * Class JoinConditionManager
+ * Класс-коллекция объектов условий присоединения
+ * @package app\qrm\Base\Helpers
+ */
+class JoinConditionCollection
 {
     /**
-     * @var JoinCondition[]
+     * @var JoinCondition[] карта объектов условий присоединения по псевдониму присоединяемой таблицы
      */
     protected $mapByJoinAs = [];
 
     /**
-     * @var JoinCondition[][]
+     * @var JoinCondition[][] катра спика объектов условий присоединения по псевдониму таблицы, к которой осуществляется присоединение
      */
     protected $matrixByJoinTo = [];
 
     /**
-     * @param JoinCondition $condition
+     * Добавление объекта условия присоединения таблицы
+     * @param JoinCondition $condition условие присоединения таблицы
      * @return $this
      * @throws QueryRelationManagerException
      */
@@ -42,7 +48,8 @@ public function add(JoinCondition $condition): self
     }
 
     /**
-     * @param string $joinAs
+     * Получение объекта условия присоединения таблицы по ее псевдониму в запросе
+     * @param string $joinAs псевдоним присоединяемой таблицы
      * @return JoinCondition
      * @throws QueryRelationManagerException
      */
@@ -55,7 +62,8 @@ public function byJoinAs(string $joinAs): JoinCondition
     }
 
     /**
-     * @param string $joinTo
+     * Получение списка объекта условий присоединения таблиц по псевдониму таблицы, к которой осуществляется присоединение
+     * @param string $joinTo псевдоним таблицы, к которой осуществляется присоединение
      * @return JoinCondition[]
      */
     public function byJoinTo(string $joinTo): array
@@ -67,7 +75,8 @@ public function byJoinTo(string $joinTo): array
     }
 
     /**
-     * @param callable $callback
+     * Перебор коллекции
+     * @param callable $callback функция, которая будет запущена для каждого элемента коллекции с передачей оного в качестве аргумента
      * @return $this
      */
     public function each(callable $callback): self

qrm/Base/Helpers/Table.php

@@ -6,56 +6,62 @@
 
 use app\qrm\Base\QueryRelationManagerException;
 
+/**
+ * Class Table
+ * Класс-хранилище данных о таблице, которая участвует в запросе
+ * @package app\qrm\Base\Helpers
+ */
 class Table
 {
     /**
-     * @var string
+     * @var string ORM-класс, представляющий таблицу
      */
     public $className;
 
     /**
-     * @var string
+     * @var string имя таблицы в БД
      */
     public $name;
 
     /**
-     * @var string
+     * @var string псевдоним таблицы в запросе
      */
     public $alias;
 
     /**
-     * @var string[]
+     * @var string[] поля первичного ключа таблицы
      */
     public $primaryKey;
 
     /**
-     * @var string
+     * @var string поле-контейнер у родительского элемента, в который будет помещен элемент этой таблицы
      */
     public $containerFieldAlias;
 
     /**
-     * @var array
+     * @var array карта полей таблицы ["`псевдонимТаблицы`.`имяПоля`" => "псевдонимТаблицы_имяПоля", ...]
      */
     protected $fieldMap = [];
 
     /**
-     * @var array
+     * @var array обратная карта полей таблицы ["псевдонимТаблицы_имяПоля" => "имяПоля"]
      */
     protected $fieldMapReverse = [];
 
     /**
-     * @var array
+     * @var array обратная карта полей, составляющих первичный ключ таблицы
+     * Пример: ["псевдонимТаблицы_имяПоля" => "имяПоля"]
      */
     protected $pkFieldMapReverse = [];
 
     /**
      * Table constructor.
-     * @param string $className
-     * @param string $name
-     * @param string $alias
-     * @param array $fields
-     * @param array $primaryKey
-     * @param string $containerFieldAlias
+     * @param string $className ORM-класс, представляющий таблицу
+     * @param string $name имя таблицы в БД
+     * @param string $alias псевдоним таблицы в запросе
+     * @param array $fields список имен полей таблицы
+     * @param array $primaryKey поля первичного ключа таблицы
+     * @param string $containerFieldAlias поле-контейнер у родительского элемента, в который будет помещен элемент этой таблицы
      * @throws QueryRelationManagerException
      */
     public function __construct(
@@ -84,6 +90,7 @@ public function __construct(
     }
 
     /**
+     * Возвращает карту полей таблицы ["`псевдонимТаблицы`.`имяПоля`" => "псевдонимТаблицы_имяПоля", ...]
      * @return string[]
      */
     public function getFieldMap(): array
@@ -92,7 +99,8 @@ public function getFieldMap(): array
     }
 
     /**
-     * @param string $fieldPrefixed
+     * Возвращает имя поля по его имени с префиксом
+     * @param string $fieldPrefixed имя поля с префиксом (псевдонимом таблицы)
      * @return string
      */
     public function getField(string $fieldPrefixed): string
@@ -101,6 +109,7 @@ public function getField(string $fieldPrefixed): string
     }
 
     /**
+     * Возвращает строку, состоящую из полей первичного ключа таблицы, разделенных дефисом
      * @return string
      */
     public function stringifyPrimaryKey(): string
@@ -109,12 +118,21 @@ public function stringifyPrimaryKey(): string
     }
 
     /**
-     * @param array $row
-     * @param JoinConditionManager $conditionManager
-     * @return array
+     * Получение данных из кортежа, представляющего из себя строку из результата запроса к БД
+     * @param array $row строка из результата запроса SELECT
+     * @param JoinConditionCollection $conditionCollection коллекция условий запроса
+     * @return array [
+     *  "данные из строки, соотвествующие таблице",
+     *  "значения полей первичного ключа через дефис",
+     *  "псевдоним этой таблицы",
+     *  "псевдоним таблицы, к которой осуществляется присоединение",
+     *  "значения полей внешнего ключа через дефис",
+     *  "поле-контейнер у родительского элемента, в который будет помещен элемент этой таблицы",
+     *  "тип отношения к родительской таблице (1 — "один к одному" или 2 — "один ко многим")"
+     * ]
      * @throws QueryRelationManagerException
      */
-    public function getDataFromRow(array $row, JoinConditionManager $conditionManager): array
+    public function getDataFromRow(array $row, JoinConditionCollection $conditionCollection): array
     {
         $item = [];
 
@@ -125,7 +143,7 @@ public function getDataFromRow(array $row, JoinConditionManager $conditionManage
         }
 
         /** @var JoinCondition $cond */
-        foreach($conditionManager->byJoinTo($this->alias) as $cond) {
+        foreach($conditionCollection->byJoinTo($this->alias) as $cond) {
             switch($cond->type) {
                 case JoinCondition::TYPE_MULTIPLE:
                     $item[$cond->table->containerFieldAlias] = [];
@@ -141,7 +159,7 @@ public function getDataFromRow(array $row, JoinConditionManager $conditionManage
         $primaryKeyValue = $this->stringifyPrimaryKeyValue($row);
 
         try {
-            $cond = $conditionManager->byJoinAs($this->alias);
+            $cond = $conditionCollection->byJoinAs($this->alias);
             $joinTo = $cond->joinTo;
             $aliasTo = $joinTo->alias;
             $foreignKeyValue = $joinTo->stringifyPrimaryKeyValue($row);
@@ -157,6 +175,7 @@ public function getDataFromRow(array $row, JoinConditionManager $conditionManage
     }
 
     /**
+     * Получение списка полей первичного ключа таблицы с префиксом-псевдонимом таблицы через точку
      * @return array
      */
     public function getPrimaryKeyForSelect(): array
@@ -170,7 +189,8 @@ public function getPrimaryKeyForSelect(): array
     }
 
     /**
-     * @param array $row
+     * Получение значений полей первичного ключа таблицы в виде строки через дефис
+     * @param array $row строка из результата запроса SELECT
      * @return string
      * @throws QueryRelationManagerException
      */