feat: tell the developer how to see warning detail

Without displayDetailsOnTestsThatTriggerWarnings PHPUnit prints only a
count — 'Warnings: 11' — which is visible but not actionable. The first
warning of a run now carries the pointer to --display-warnings and the
config setting.

Once per run, not per finding: tests run with processIsolation, so each
test is a separate process and a static flag cannot track 'first'. A
marker file keyed to the project and the hour serves as the shared
signal.

Author: imorland

php-packages/testing/src/integration/RepeatedQueryDetector.php

@@ -117,6 +117,49 @@ private static function isWorthCounting(string $sql): bool
         return (bool) preg_match('/^\s*(select|insert|update|delete)\b/i', $sql);
     }
 
+    /**
+     * A pointer, appended to the first warning of a run, explaining how to see
+     * the detail.
+     *
+     * PHPUnit only prints warning messages when the phpunit config sets
+     * `displayDetailsOnTestsThatTriggerWarnings`; without it the run reports a
+     * bare count. Since that is the default in most extensions, the first
+     * warning has to carry its own instructions — and only the first, or it
+     * repeats on every finding.
+     *
+     * Tests usually run with `processIsolation`, so "first" cannot be tracked
+     * in memory: each test is a fresh process. A marker file next to the
+     * findings log gives one hint per run instead of one per process.
+     */
+    public static function hintOnce(): string
+    {
+        $hint = "\n\nRun with --display-warnings, or set"
+            ."\ndisplayDetailsOnTestsThatTriggerWarnings=\"true\" in your phpunit config, to see"
+            ."\nwhich queries these were.";
+
+        // Keyed to the project and to the hour, so every isolated test process
+        // in a run agrees on what "first" means without needing cleanup that a
+        // per-test process can't reliably perform. A later run gets a fresh
+        // hint; a run straddling the hour boundary may hint twice, which is a
+        // fair trade for not carrying state between processes.
+        $marker = sprintf(
+            '%s/flarum-repeated-queries-hinted-%s',
+            sys_get_temp_dir(),
+            md5((string) realpath('.').gmdate('YmdH'))
+        );
+
+        // `x` mode succeeds only for whoever gets there first.
+        $handle = @fopen($marker, 'x');
+
+        if ($handle === false) {
+            return '';
+        }
+
+        fclose($handle);
+
+        return $hint;
+    }
+
     /**
      * Record a finding for tooling to pick up after the run.
      *

php-packages/testing/src/integration/TestCase.php

@@ -408,10 +408,15 @@ private function reportRepeatedQueries(ServerRequestInterface $request, array $q
             // Raised as a PHP warning: PHPUnit surfaces these against the test
             // that triggered them (with `displayDetailsOnTestsThatTriggerWarnings`
             // it prints the detail) without failing the run.
+            //
+            // Without that setting PHPUnit reports only a count — "Warnings: 11"
+            // — so the first warning of the run says how to see the rest.
+            // Otherwise the default experience is a number with no next step.
             trigger_error(sprintf(
-                "%s repeated queries for the same few values — consider memoising.\n%s",
+                "%s repeated queries for the same few values — consider memoising.\n%s%s",
                 $where,
-                RepeatedQueryDetector::describe($wasteful)
+                RepeatedQueryDetector::describe($wasteful),
+                RepeatedQueryDetector::hintOnce()
             ), E_USER_WARNING);
         }