From fa2a806a07ca9279af5a69391d0556098f0cdbb1 Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Thu, 10 Aug 2023 17:17:10 +0200
Subject: [PATCH] [DX] deprecated build shipped debug fuctions, allow using
 custom debug package instead; add local d() and dd() functions (#4759)

---
 composer.json                 | 10 +++++++---
 phpstan.neon                  | 20 ++++++++++++++++++++
 src/functions/node_helper.php | 35 ++++++-----------------------------
 tests/debug_functions.php     | 24 ++++++++++++++++++++++++
 4 files changed, 57 insertions(+), 32 deletions(-)
 create mode 100644 tests/debug_functions.php

diff --git a/composer.json b/composer.json
index 02ccb0f155c..fa0bfd55712 100644
--- a/composer.json
+++ b/composer.json
@@ -43,7 +43,6 @@
         "symfony/process": "^6.3",
         "symplify/easy-parallel": "^11.1",
         "symplify/rule-doc-generator-contracts": "^11.1",
-        "tracy/tracy": "^2.9",
         "webmozart/assert": "^1.11"
     },
     "require-dev": {
@@ -68,13 +67,17 @@
         "symplify/vendor-patches": "^11.2",
         "tomasvotruba/class-leak": "^0.1",
         "tomasvotruba/cognitive-complexity": "^0.1",
+        "tomasvotruba/lines": "0.3.1.72",
         "tomasvotruba/type-coverage": "^0.2",
-        "tomasvotruba/unused-public": "^0.2"
+        "tomasvotruba/unused-public": "^0.2",
+        "tracy/tracy": "^2.9"
     },
     "replace": {
         "rector/rector": "self.version",
         "symfony/polyfill-ctype": "*",
-        "symfony/polyfill-intl-grapheme": "*"
+        "symfony/polyfill-intl-grapheme": "*",
+        "symfony/error-handler": "*",
+        "symfony/var-dumper": "*"
     },
     "autoload": {
         "psr-4": {
@@ -110,6 +113,7 @@
             "rules-tests/Renaming/Rector/Name/RenameClassRector/Source"
         ],
         "files": [
+            "tests/debug_functions.php",
             "stubs/Directory.php",
             "rules-tests/Transform/Rector/FuncCall/FuncCallToMethodCallRector/Source/some_view_function.php",
             "rules-tests/TypeDeclaration/Rector/ClassMethod/ParamTypeByMethodCallTypeRector/Source/FunctionTyped.php"
diff --git a/phpstan.neon b/phpstan.neon
index d5c8c788535..609a5386a28 100644
--- a/phpstan.neon
+++ b/phpstan.neon
@@ -665,3 +665,23 @@ parameters:
 
         # iterable mix
         - '#Property Rector\\Core\\Configuration\\ConfigInitializer\:\:\$rectors \(array<Rector\\Core\\Contract\\Rector\\RectorInterface>\) does not accept array\|iterable<Rector\\Core\\Contract\\Rector\\RectorInterface>#'
+
+        # false positive
+        - '#Parameter \#2 \$colors of method Tracy\\Dumper\\Renderer\:\:renderAsText\(\) expects array, array\|null given#'
+
+        # chicken/egg
+        -
+            message: '#Function "(d|dd)\(\)" cannot be used/left in the code#'
+            path: tests/debug_functions.php
+
+        # debug functions
+        -
+            message: '#Function "function_exists\(\)" cannot be used/left in the code\: use ReflectionProvider\->has\*\(\) instead#'
+            path: tests/debug_functions.php
+
+        -
+            message: '#Do not name "d", shorter than 2 chars#'
+            path: tests/debug_functions.php
+
+        # not relevant
+        - '#Do not use static property#'
diff --git a/src/functions/node_helper.php b/src/functions/node_helper.php
index ad883754d6c..b6e8f23979b 100644
--- a/src/functions/node_helper.php
+++ b/src/functions/node_helper.php
@@ -6,40 +6,17 @@
 use PhpParser\PrettyPrinter\Standard;
 use Tracy\Dumper;
 
-if (! function_exists('dump_with_depth')) {
-    function dump_with_depth(mixed $value, int $depth = 2): void
-    {
-        Dumper::dump($value, [
-            Dumper::DEPTH => $depth,
-        ]);
-    }
-}
-
-if (! function_exists('dn')) {
-    function dn(Node $node, int $depth = 2): void
-    {
-        dump_node($node, $depth);
-    }
-}
-
-
+// @deprecated, use dump() or dd() instead
 if (! function_exists('dump_node')) {
-    /**
-     * @param Node|Node[] $node
-     */
-    function dump_node(Node | array $node, int $depth = 2): void
+    function dump_node(mixed $variable, int $depth = 2): never
     {
-        $nodes = is_array($node) ? $node : [$node];
-
-        foreach ($nodes as $node) {
-            Dumper::dump($node, [
-                Dumper::DEPTH => $depth,
-            ]);
-        }
+        trigger_error(
+            'This function is deprecated, to avoid enforcing of Rector debug package. Use your own favorite debugging package instead'
+        );
+        exit;
     }
 }
 
-
 if (! function_exists('print_node')) {
     /**
      * @param Node|Node[] $node
diff --git a/tests/debug_functions.php b/tests/debug_functions.php
new file mode 100644
index 00000000000..0cfcc410927
--- /dev/null
+++ b/tests/debug_functions.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+use Tracy\Dumper;
+
+// helpful functions to create new rector rules
+
+if (! function_exists('dd')) {
+    function dd(mixed $value, int $depth = 2): never
+    {
+        d($value, $depth);
+        die;
+    }
+}
+
+if (! function_exists('d')) {
+    function d(mixed $value, int $depth = 2): void
+    {
+        Dumper::dump($value, [
+            Dumper::DEPTH => $depth,
+        ]);
+    }
+}