feat: Enhance Active Record models and queries with detailed documentation and strict validation rules for nested sets behavior. (#79)

Author: terabytesoftw

tests/support/model/ExtendableMultipleTree.php

@@ -8,14 +8,38 @@
 use yii2\extensions\nestedsets\tests\support\stub\ExtendableNestedSetsBehavior;
 
 /**
+ * Active Record model for testing multiple tree support with nested sets behavior extension.
+ *
+ * This class demonstrates a scenario where a model attaches the {@see ExtendableNestedSetsBehavior} to enable
+ * hierarchical data structure operations with support for multiple trees.
+ *
+ * The model provides tree structure functionality through the behavior properties and methods, allowing for nested sets
+ * model implementation on Active Record instances with a tree attribute.
+ *
+ * The model is designed for testing property resolution and behavior integration in scenarios involving multiple tree
+ * columns.
+ *
+ * It ensures proper type inference and property access when behaviors are attached to Yii Active Record models with a
+ * tree context.
+ *
+ * Key features:
+ * - Behavior attachment for hierarchical data structures with multiple tree support.
+ * - Nested sets model functionality for tree operations.
+ * - Property resolution testing for behavior integration.
+ * - Static analysis validation for behavior property access.
+ * - Table mapping with the `multiple_tree` table.
+ *
  * @phpstan-property int $depth
  * @phpstan-property int $id
  * @phpstan-property int $lft
  * @phpstan-property int $rgt
  * @phpstan-property int $tree
  * @phpstan-property string $name
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
  */
-class ExtendableMultipleTree extends ActiveRecord
+final class ExtendableMultipleTree extends ActiveRecord
 {
     public function behaviors(): array
     {
@@ -28,11 +52,11 @@ public function behaviors(): array
     }
 
     /**
-     * @phpstan-return ExtendableMultipleTreeQuery<static>
+     * @phpstan-return ExtendableMultipleTreeQuery<self>
      */
     public static function find(): ExtendableMultipleTreeQuery
     {
-        return new ExtendableMultipleTreeQuery(static::class);
+        return new ExtendableMultipleTreeQuery(self::class);
     }
 
     public function rules(): array

tests/support/model/ExtendableMultipleTreeQuery.php

@@ -8,21 +8,28 @@
 use yii2\extensions\nestedsets\NestedSetsQueryBehavior;
 
 /**
+ * Active Query class for {@see ExtendableMultipleTree} with nested sets query behavior support.
+ *
+ * Provides an Active Query implementation tailored for the {@see ExtendableMultipleTree} model, enabling integration
+ * with the {@see NestedSetsQueryBehavior} for hierarchical data operations in multiple tree scenarios.
+ *
+ * This class attaches the nested sets query behavior to facilitate tree traversal and structure queries on models
+ * representing multiple tree hierarchies.
+ *
+ * Key features:
+ * - Attaches {@see NestedSetsQueryBehavior} for nested sets operations.
+ * - Designed for use with {@see ExtendableMultipleTree} in test environments.
+ * - Supports hierarchical queries for models with multiple tree columns.
+ *
  * @template T of ExtendableMultipleTree
  *
  * @extends ActiveQuery<T>
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
  */
 final class ExtendableMultipleTreeQuery extends ActiveQuery
 {
-    /**
-     * @phpstan-param class-string<T> $modelClass
-     * @phpstan-param array<string, mixed> $config
-     */
-    public function __construct(string $modelClass, array $config = [])
-    {
-        parent::__construct($modelClass, $config);
-    }
-
     public function behaviors(): array
     {
         return [

tests/support/model/MultipleTree.php

@@ -8,12 +8,36 @@
 use yii2\extensions\nestedsets\NestedSetsBehavior;
 
 /**
+ * Active Record model for testing multiple tree support with nested sets behavior.
+ *
+ * This class attaches the {@see NestedSetsBehavior} to enable hierarchical data structure operations with support for
+ * multiple trees.
+ *
+ * The model provides tree structure functionality through the behavior properties and methods, allowing for nested sets
+ * model implementation on Active Record instances with a tree attribute.
+ *
+ * The model is designed for testing property resolution and behavior integration in scenarios involving multiple tree
+ * columns.
+ *
+ * It ensures proper type inference and property access when behaviors are attached to Yii Active Record models with a
+ * tree context.
+ *
+ * Key features:
+ * - Behavior attachment for hierarchical data structures with multiple tree support.
+ * - Nested sets model functionality for tree operations.
+ * - Property resolution testing for behavior integration.
+ * - Static analysis validation for behavior property access.
+ * - Table mapping with the `multiple_tree` table.
+ *
  * @phpstan-property int $depth
  * @phpstan-property int $id
  * @phpstan-property int $lft
  * @phpstan-property int $rgt
  * @phpstan-property int $tree
  * @phpstan-property string $name
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
  */
 class MultipleTree extends ActiveRecord
 {

tests/support/model/MultipleTreeQuery.php

@@ -8,9 +8,25 @@
 use yii2\extensions\nestedsets\NestedSetsQueryBehavior;
 
 /**
+ * Active Query class for {@see MultipleTree} with nested sets query behavior support.
+ *
+ * Provides an Active Query implementation tailored for the {@see MultipleTree} model, enabling integration with the
+ * {@see NestedSetsQueryBehavior} for hierarchical data operations in multiple tree scenarios.
+ *
+ * This class attaches the nested sets query behavior to facilitate tree traversal and structure queries on models
+ * representing multiple tree hierarchies.
+ *
+ * Key features:
+ * - Attaches {@see NestedSetsQueryBehavior} for nested sets operations.
+ * - Designed for use with {@see MultipleTree} in test environments.
+ * - Supports hierarchical queries for models with multiple tree columns.
+ *
  * @template T of MultipleTree
  *
  * @extends ActiveQuery<T>
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
  */
 final class MultipleTreeQuery extends ActiveQuery
 {

tests/support/model/Tree.php

@@ -8,11 +8,32 @@
 use yii2\extensions\nestedsets\NestedSetsBehavior;
 
 /**
+ * Active Record model for testing single tree support with nested sets behavior.
+ *
+ * This class attaches the {@see NestedSetsBehavior} to enable hierarchical data structure operations for a single tree.
+ *
+ * The model provides tree structure functionality through the behavior properties and methods, allowing for nested sets
+ * model implementation on Active Record instances.
+ *
+ * The model is designed for testing property resolution and behavior integration in scenarios involving a single tree.
+ *
+ * It ensures proper type inference and property access when behaviors are attached to Yii Active Record models.
+ *
+ * Key features:
+ * - Behavior attachment for hierarchical data structures with single tree support.
+ * - Nested sets model functionality for tree operations.
+ * - Property resolution testing for behavior integration.
+ * - Static analysis validation for behavior property access.
+ * - Table mapping with the `tree` table.
+ *
  * @phpstan-property int $depth
  * @phpstan-property int $id
  * @phpstan-property int $lft
  * @phpstan-property int $rgt
  * @phpstan-property string $name
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
  */
 class Tree extends ActiveRecord
 {

tests/support/model/TreeQuery.php

@@ -8,9 +8,26 @@
 use yii2\extensions\nestedsets\NestedSetsQueryBehavior;
 
 /**
- * @template T of Tree
+ * Active Query class for {@see Tree} and {@see TreeWithStrictValidation} with nested sets query behavior support.
+ *
+ * Provides an Active Query implementation tailored for the {@see Tree} and {@see TreeWithStrictValidation} models,
+ * enabling integration with the {@see NestedSetsQueryBehavior} for hierarchical data operations in single tree
+ * scenarios.
+ *
+ * This class attaches the nested sets query behavior to facilitate tree traversal and structure queries on models
+ * representing single tree hierarchies.
+ *
+ * Key features:
+ * - Attaches {@see NestedSetsQueryBehavior} for nested sets operations.
+ * - Designed for use with {@see Tree} and {@see TreeWithStrictValidation} in test environments.
+ * - Supports hierarchical queries for models with single tree columns.
+ *
+ * @template T of Tree|TreeWithStrictValidation
  *
  * @extends ActiveQuery<T>
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
  */
 final class TreeQuery extends ActiveQuery
 {

tests/support/model/TreeWithStrictValidation.php

@@ -4,15 +4,64 @@
 
 namespace yii2\extensions\nestedsets\tests\support\model;
 
+use yii\db\ActiveRecord;
+use yii2\extensions\nestedsets\NestedSetsBehavior;
+
 /**
+ * Active Record model for testing strict validation rules with nested sets behavior.
+ *
+ * This class attaches the {@see NestedSetsBehavior} to enable hierarchical data structure operations for a single tree,
+ * with additional strict validation rules applied to the name attribute.
+ *
+ * The model is designed for testing property resolution, behavior integration, and validation scenarios involving a
+ * single tree with custom validation requirements.
+ *
+ * It ensures proper type inference and property access when behaviors are attached to Yii Active Record models, and
+ * enforces strict validation for the name property, including required, minimum length, and pattern constraints.
+ *
+ * Key features:
+ * - Behavior attachment for hierarchical data structures with single tree support.
+ * - Nested sets model functionality for tree operations.
+ * - Property resolution testing for behavior integration.
+ * - Static analysis validation for behavior property access.
+ * - Strict validation rules for the name attribute (required, minimum length, pattern).
+ * - Table mapping with the `tree` table.
+ *
  * @phpstan-property int $depth
  * @phpstan-property int $id
  * @phpstan-property int $lft
  * @phpstan-property int $rgt
  * @phpstan-property string $name
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
  */
-final class TreeWithStrictValidation extends Tree
+final class TreeWithStrictValidation extends ActiveRecord
 {
+    public function behaviors(): array
+    {
+        return [
+            'nestedSetsBehavior' => NestedSetsBehavior::class,
+        ];
+    }
+
+    /**
+     * @phpstan-return TreeQuery<self>
+     */
+    public static function find(): TreeQuery
+    {
+        return new TreeQuery(self::class);
+    }
+
+    public function isTransactional($operation): bool
+    {
+        if ($operation === ActiveRecord::OP_DELETE) {
+            return false;
+        }
+
+        return parent::isTransactional($operation);
+    }
+
     public function rules(): array
     {
         return [
@@ -21,4 +70,19 @@ public function rules(): array
             ['name', 'match', 'pattern' => '/^[A-Z]/', 'message' => 'Name must start with an uppercase letter.'],
         ];
     }
+
+    public static function tableName(): string
+    {
+        return '{{%tree}}';
+    }
+
+    /**
+     * @phpstan-return array<string, int>
+     */
+    public function transactions(): array
+    {
+        return [
+            self::SCENARIO_DEFAULT => self::OP_ALL,
+        ];
+    }
 }