Fix #94: Add a middleware handler to control dumps' output destinatio…

…n, add `dump` function

CHANGELOG.md

@@ -1,8 +1,9 @@
 # Yii VarDumper
 
-## 1.6.1 under development
+## 1.7.0 under development
 
-- no changes in this release.
+- Enh #94: Add a middleware handler to control dumps' output destination (@xepozz)
+- New #94: Add `dump` function (@xepozz)
 
 ## 1.6.0 June 30, 2023
 

README.md

@@ -48,6 +48,8 @@ For convenience, you can use the functions:
 ```php
 // Prints variables:
 d($variable, /* Further variables to dump. */);
+// The same as above
+dump($variable, /* Further variables to dump. */);
 
 // Prints variables and terminate the current script:
 dd($variable, /* Further variables to dump. */);

src/Handler/EchoHandler.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\VarDumper\Handler;
+
+use Yiisoft\VarDumper\HandlerInterface;
+use Yiisoft\VarDumper\VarDumper;
+
+final class EchoHandler implements HandlerInterface
+{
+    public function handle(mixed $variable, int $depth, bool $highlight = false): void
+    {
+        $varDumper = VarDumper::create($variable);
+        $output = $varDumper->asString($depth);
+
+        if ($highlight) {
+            $result = highlight_string("<?php\n" . $output, true);
+            $output = preg_replace('/&lt;\\?php<br \\/>/', '', $result, 1);
+        }
+
+        echo $output;
+    }
+}

src/HandlerInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\VarDumper;
+
+interface HandlerInterface
+{
+    public function handle(mixed $variable, int $depth, bool $highlight = false): void;
+}

src/VarDumper.php

@@ -14,13 +14,12 @@
 use ReflectionException;
 use ReflectionObject;
 use Yiisoft\Arrays\ArrayableInterface;
+use Yiisoft\VarDumper\Handler\EchoHandler;
 
 use function array_keys;
 use function gettype;
-use function highlight_string;
 use function method_exists;
 use function next;
-use function preg_replace;
 use function spl_object_id;
 use function str_repeat;
 use function strtr;
@@ -47,6 +46,8 @@ final class VarDumper
     public const VAR_TYPE_ARRAY = 'array';
     public const VAR_TYPE_OBJECT = 'object';
     public const VAR_TYPE_RESOURCE = 'resource';
+    private static ?HandlerInterface $defaultHandler = null;
+
     /**
      * @var string[] Variables using in closure scope.
      */
@@ -65,6 +66,16 @@ private function __construct(private mixed $variable)
     {
     }
 
+    public static function setDefaultHandler(HandlerInterface $handler): void
+    {
+        self::$defaultHandler = $handler;
+    }
+
+    public static function getDefaultHandler(): HandlerInterface
+    {
+        return self::$defaultHandler ??= new EchoHandler();
+    }
+
     /**
      * @param mixed $variable Variable to dump.
      *
@@ -89,7 +100,7 @@ public static function create(mixed $variable): self
      */
     public static function dump(mixed $variable, int $depth = 10, bool $highlight = true): void
     {
-        echo self::create($variable)->asString($depth, $highlight);
+        self::getDefaultHandler()->handle($variable, $depth, $highlight);
     }
 
     /**
@@ -120,16 +131,9 @@ public function withOffset(string $offset): self
      *
      * @return string The string representation of the variable.
      */
-    public function asString(int $depth = 10, bool $highlight = false): string
+    public function asString(int $depth = 10): string
     {
-        $output = $this->dumpInternal($this->variable, true, $depth, 0);
-
-        if ($highlight) {
-            $result = highlight_string("<?php\n" . $output, true);
-            $output = preg_replace('/&lt;\\?php<br \\/>/', '', $result, 1);
-        }
-
-        return $output;
+        return $this->dumpInternal($this->variable, true, $depth, 0);
     }
 
     /**

src/functions.php

@@ -42,3 +42,19 @@ function dd(mixed ...$variables): void
         die(0);
     }
 }
+
+if (!function_exists('dump')) {
+    /**
+     * Prints variables and terminate the current script.
+     *
+     * @param mixed ...$variables Variables to be dumped.
+     *
+     * @see d()
+     *
+     * @psalm-suppress MixedAssignment
+     */
+    function dump(mixed ...$variables): void
+    {
+        d(...$variables);
+    }
+}