feat: Enhance EchoMigrateController and ExtendableNestedSetsBehavior class with improved documentation and type hints for better test coverage and clarity. (#80)

Author: terabytesoftw

tests/support/stub/EchoMigrateController.php

@@ -6,9 +6,26 @@
 
 use yii\console\controllers\MigrateController;
 
+/**
+ * Console migrate controller stub that echoes output for testing.
+ *
+ * Provides a stub implementation of the {@see MigrateController} for use in test environments, overriding the
+ * {@see stdout()} method to directly echo output instead of writing to the console output stream.
+ *
+ * This class is intended for use in automated tests where migration output needs to be captured or asserted without
+ * relying on the Yii Console output infrastructure.
+ *
+ * Key features:
+ * - Designed for use in migration-related test scenarios.
+ * - Overrides {@see stdout()} to echo output for test assertions.
+ * - Simplifies output handling in test environments.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 final class EchoMigrateController extends MigrateController
 {
-    public function stdout($string)
+    public function stdout($string): bool
     {
         echo $string;
 

tests/support/stub/ExtendableNestedSetsBehavior.php

@@ -5,28 +5,61 @@
 namespace yii2\extensions\nestedsets\tests\support\stub;
 
 use yii\db\ActiveRecord;
+use yii\db\Exception;
 use yii2\extensions\nestedsets\NestedSetsBehavior;
+use yii2\extensions\nestedsets\NodeContext;
 
 /**
+ * Extensible Nested Sets Behavior stub for testing method exposure and call tracking.
+ *
+ * Provides a test double for {@see NestedSetsBehavior} exposing protected methods and tracking their invocation for
+ * unit testing purposes.
+ *
+ * This class enables direct invocation of internal behavior logic and records method calls, supporting fine-grained
+ * assertions in test scenarios.
+ *
+ * It also allows manual manipulation of internal state for advanced test coverage.
+ *
+ * Key features:
+ * - Allows manual state manipulation (node, operation).
+ * - Exposes protected methods for direct testing.
+ * - Supports cache invalidation tracking.
+ * - Tracks method invocations for assertion.
+ *
  * @phpstan-template T of ActiveRecord
  *
  * @phpstan-extends NestedSetsBehavior<T>
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
  */
 final class ExtendableNestedSetsBehavior extends NestedSetsBehavior
 {
     /**
+     * Tracks method calls for assertions.
+     *
      * @phpstan-var array<string, bool>
      */
     public array $calledMethods = [];
+
+    /**
+     * Indicates if the cache invalidation method was called.
+     */
     public bool $invalidateCacheCalled = false;
 
+    /**
+     * @throws Exception if an unexpected error occurs during execution.
+     */
     public function exposedBeforeInsertNode(int $value, int $depth): void
     {
         $this->calledMethods['beforeInsertNode'] = true;
 
         $this->beforeInsertNode($value, $depth);
     }
 
+    /**
+     * @throws Exception if an unexpected error occurs during execution.
+     */
     public function exposedBeforeInsertRootNode(): void
     {
         $this->calledMethods['beforeInsertRootNode'] = true;
@@ -38,7 +71,7 @@ public function exposedMoveNode(ActiveRecord $node, int $value, int $depth): voi
     {
         $this->calledMethods['moveNode'] = true;
 
-        $context = new \yii2\extensions\nestedsets\NodeContext(
+        $context = new NodeContext(
             $node,
             0,
             0,