ci: add manual speed-matrix workflow for hot-path A/B benchmarks

Run from the Actions tab, or: gh workflow run speed-matrix.yml. Never runs on push.

- Benchmarks 17 optimization candidates for the SmartString output path: encode fast paths, SmartArray __get shapes, property typing, output idioms
- Covers PHP 8.1-8.5 on Linux x64/ARM, Windows x64, macOS Intel/ARM (~25 cells)
- Reports B-vs-A ratios from interleaved same-process runs, so noisy shared runners still compare fairly; within 5% reads as a tie
- Refuses to time any encoder that isn't byte-identical to htmlspecialchars across a 106k-string corpus (invalid UTF-8, noncharacters, every 2-byte string)
- Summary job merges all cells into one grid on the run page
- Inputs narrow the run: os, php, jit, iteration scale, test ids
- No Windows ARM cell: php.net ships no ARM64 Windows builds

Author: daveedis

.github/scripts/speed-corpus.php

@@ -0,0 +1,180 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Correctness corpus for encoding fast-path candidates.
+ *
+ * Any alternative encoder must produce byte-identical output to
+ * htmlspecialchars($s, ENT_QUOTES|ENT_SUBSTITUTE|ENT_DISALLOWED|ENT_HTML5, 'UTF-8')
+ * for every string this corpus generates. speed-probe.php runs this gate before
+ * timing anything; a future PHPUnit test can wrap it when a fast path ships.
+ *
+ * Corpus derived from the adversarial verifier run of 2026-07-18 (~91k entries):
+ * empty string, all 256 single bytes, ALL 65,536 two-byte strings, every byte at
+ * head/mid/tail of clean ASCII, valid multibyte incl. emoji and combining marks,
+ * all 66 Unicode noncharacters, overlongs, surrogate halves, truncated sequences,
+ * stray continuation bytes, the five specials in context, long strings with a bad
+ * byte at head/middle/tail, whitespace combos, and 40,000 seeded fuzz strings.
+ *
+ * No extension requirements: UTF-8 is encoded by hand (mbstring may be absent),
+ * fuzz uses a fixed mt_srand seed so every run tests the identical corpus.
+ */
+
+const SPEED_CORPUS_FLAGS = ENT_QUOTES | ENT_SUBSTITUTE | ENT_DISALLOWED | ENT_HTML5;
+
+/**
+ * Encode a code point to UTF-8 bytes without mbstring.
+ */
+function speed_corpus_u8(int $cp): string
+{
+    if ($cp < 0x80) {
+        return chr($cp);
+    }
+    if ($cp < 0x800) {
+        return chr(0xC0 | $cp >> 6) . chr(0x80 | $cp & 0x3F);
+    }
+    if ($cp < 0x10000) {
+        return chr(0xE0 | $cp >> 12) . chr(0x80 | ($cp >> 6) & 0x3F) . chr(0x80 | $cp & 0x3F);
+    }
+    return chr(0xF0 | $cp >> 18) . chr(0x80 | ($cp >> 12) & 0x3F) . chr(0x80 | ($cp >> 6) & 0x3F) . chr(0x80 | $cp & 0x3F);
+}
+
+/**
+ * Build the full corpus. ~91k strings, a few MB; generate once per process.
+ *
+ * @return string[]
+ */
+function speed_corpus(): array
+{
+    $corpus = [''];
+
+    // All 256 single bytes
+    for ($b = 0; $b <= 0xFF; $b++) {
+        $corpus[] = chr($b);
+    }
+
+    // ALL 65,536 two-byte strings (partial multibyte, C1-as-latin1, etc.)
+    for ($a = 0; $a <= 0xFF; $a++) {
+        $ca = chr($a);
+        for ($b = 0; $b <= 0xFF; $b++) {
+            $corpus[] = $ca . chr($b);
+        }
+    }
+
+    // Each byte at head / mid / tail of clean ASCII (position sensitivity)
+    for ($b = 0; $b <= 0xFF; $b++) {
+        $corpus[] = "Hello " . chr($b) . " World";
+        $corpus[] = chr($b) . " leading";
+        $corpus[] = "trailing " . chr($b);
+    }
+
+    // Valid multibyte UTF-8: 2/3/4-byte sequences, emoji, combining marks, BOM, zero-width
+    $mb = ["caf\u{E9}", "\u{4E2D}\u{6587}", "\u{1F600}\u{1F4A9}", "e\u{0301}", "\u{FEFF}",
+           "\u{00A0}", "\u{2028}\u{2029}", "\u{FFFD}", "\u{10FFFF}", "\u{E000}", "\u{200B}"];
+    foreach ($mb as $s) {
+        $corpus[] = $s;
+        $corpus[] = "pre $s post";
+    }
+
+    // Noncharacters: U+FDD0..U+FDEF, and U+xFFFE/U+xFFFF in every plane
+    for ($cp = 0xFDD0; $cp <= 0xFDEF; $cp++) {
+        $corpus[] = speed_corpus_u8($cp) . " tail";
+    }
+    for ($plane = 0; $plane <= 0x10; $plane++) {
+        $corpus[] = "a" . speed_corpus_u8($plane * 0x10000 + 0xFFFE);
+        $corpus[] = "a" . speed_corpus_u8($plane * 0x10000 + 0xFFFF);
+    }
+
+    // Invalid UTF-8: overlongs, surrogate halves (CESU-8), truncations, stray continuations
+    $invalid = [
+        "\xC0\xAF", "\xC1\xBF",                 // overlong '/'
+        "\xE0\x80\xAF", "\xF0\x80\x80\xAF",     // more overlongs
+        "\xED\xA0\x80", "\xED\xBF\xBF",         // surrogate halves
+        "\xF4\x90\x80\x80",                     // > U+10FFFF
+        "\xC3", "\xE2\x82", "\xF0\x9F\x98",     // truncated sequences
+        "\x80", "\xBF", "\x80\x80\x80",         // stray continuations
+        "\xFE", "\xFF", "\xFF\xFE\xFD",
+        "ok\xC3\x28bad",                        // invalid continuation
+    ];
+    foreach ($invalid as $s) {
+        $corpus[] = $s;
+        $corpus[] = "text $s text";
+    }
+
+    // The five specials in various contexts
+    foreach (['&', '<', '>', '"', "'"] as $sp) {
+        $corpus[] = $sp;
+        $corpus[] = "a{$sp}b";
+        $corpus[] = str_repeat($sp, 50);
+    }
+    $corpus[] = '<script>alert("x&y\'z")</script>';
+    $corpus[] = '&amp; already encoded &#39;';
+
+    // Long strings, bad byte at head / middle / tail (gate must not miss by position)
+    $clean1k  = str_repeat('The quick brown fox jumps over the lazy dog. ', 23);
+    $corpus[] = $clean1k;
+    $corpus[] = "<" . $clean1k;
+    $corpus[] = substr($clean1k, 0, 500) . "\x00" . substr($clean1k, 500);
+    $corpus[] = $clean1k . "\xE9";
+    $corpus[] = $clean1k . speed_corpus_u8(0xFDD0);
+
+    // Whitespace combos: \t \n \v \f \r
+    $corpus[] = "a\tb\nc\x0Bd\x0Ce\rf";
+    $corpus[] = "\t\n\x0C\r";
+    $corpus[] = "\x0B";
+
+    // Fuzz: 20,000 random-byte strings + 20,000 ASCII-biased (fast path's home turf).
+    // Fixed seed: every run, every platform, tests the identical corpus.
+    mt_srand(20260718);
+    for ($i = 0; $i < 20000; $i++) {
+        $len = mt_rand(0, 64);
+        $s   = '';
+        for ($j = 0; $j < $len; $j++) {
+            $s .= chr(mt_rand(0, 255));
+        }
+        $corpus[] = $s;
+    }
+    for ($i = 0; $i < 20000; $i++) {
+        $len = mt_rand(0, 64);
+        $s   = '';
+        for ($j = 0; $j < $len; $j++) {
+            $s .= mt_rand(0, 30) === 0 ? chr(mt_rand(0, 255)) : chr(mt_rand(0x20, 0x7E));
+        }
+        $corpus[] = $s;
+    }
+
+    return $corpus;
+}
+
+/**
+ * Assert an encoder is byte-identical to the reference over the whole corpus.
+ *
+ * @param callable $encoder  fn(string): string
+ * @param string[] $corpus   result of speed_corpus() (pass in to reuse across encoders)
+ * @return array{count: int, fail: int, samples: string[]}  samples = first 5 mismatches as hex
+ */
+function speed_corpus_assert(callable $encoder, array $corpus): array
+{
+    $fail    = 0;
+    $samples = [];
+    foreach ($corpus as $s) {
+        $want = htmlspecialchars($s, SPEED_CORPUS_FLAGS, 'UTF-8');
+        $got  = $encoder($s);
+        if ($got !== $want) {
+            $fail++;
+            if (count($samples) < 5) {
+                $samples[] = sprintf('input=%s want=%s got=%s', bin2hex($s), bin2hex($want), bin2hex($got));
+            }
+        }
+    }
+    return ['count' => count($corpus), 'fail' => $fail, 'samples' => $samples];
+}
+
+// Standalone self-check: the reference must agree with itself, and the corpus
+// must be a sane size. Run: php speed-corpus.php
+if (PHP_SAPI === 'cli' && realpath($_SERVER['SCRIPT_FILENAME'] ?? '') === __FILE__) {
+    $corpus = speed_corpus();
+    $result = speed_corpus_assert(static fn(string $s): string => htmlspecialchars($s, SPEED_CORPUS_FLAGS, 'UTF-8'), $corpus);
+    printf("PHP %s | corpus=%d fail=%d (self-check)\n", PHP_VERSION, $result['count'], $result['fail']);
+    exit($result['fail'] === 0 && $result['count'] > 90000 ? 0 : 1);
+}

.github/scripts/speed-merge.php

@@ -0,0 +1,93 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Merge per-cell speed-probe JSON artifacts into one comparison grid.
+ *
+ *     php speed-merge.php probes/*.json >> "$GITHUB_STEP_SUMMARY"
+ *
+ * Rows = tests, columns = cells (os/arch php), values = "B vs A" ratio.
+ * Ratio > 1.00 means the B side (the candidate) is faster; >= 1.05 bold,
+ * <= 0.95 flagged as a regression. CORPUS_FAIL and missing cells are called out.
+ */
+
+$files = array_slice($argv, 1);
+if ($files === []) {
+    fwrite(STDERR, "Usage: php speed-merge.php probe-*.json\n");
+    exit(1);
+}
+
+$cells = []; // label => decoded json
+foreach ($files as $file) {
+    $data = json_decode((string)file_get_contents($file), true);
+    if (!is_array($data) || !isset($data['php'], $data['os'], $data['tests'])) {
+        fwrite(STDERR, "skipping unreadable probe file: $file\n");
+        continue;
+    }
+    $phpShort = preg_replace('/^(\d+\.\d+)\..*$/', '$1', $data['php']);
+    $arch     = str_contains((string)$data['arch'], 'arm') || str_contains((string)$data['arch'], 'aarch') ? 'arm' : 'x64';
+    $label    = strtolower($data['os']) . "-$arch $phpShort";
+    $cells[$label] = $data;
+}
+if ($cells === []) {
+    fwrite(STDERR, "no valid probe files\n");
+    exit(1);
+}
+ksort($cells);
+
+// Collect the union of test ids in first-seen order, and A/B labels for the legend
+$testIds = [];
+$legend  = [];
+foreach ($cells as $data) {
+    foreach ($data['tests'] as $id => $t) {
+        if (!in_array($id, $testIds, true)) {
+            $testIds[] = $id;
+            $legend[$id] = [$t['a_label'] ?? '?', $t['b_label'] ?? '?'];
+        }
+    }
+}
+
+echo "## Speed matrix: B-vs-A ratios (>1.00 = candidate faster)\n\n";
+
+// Corpus status line: any failure anywhere is a headline, not a footnote
+$corpusBad = [];
+foreach ($cells as $label => $data) {
+    foreach (($data['corpus']['encoders'] ?? []) as $fn => $ok) {
+        if (!$ok) {
+            $corpusBad[] = "$label:$fn";
+        }
+    }
+}
+echo $corpusBad === []
+    ? "Correctness: every encoder byte-identical on every cell.\n\n"
+    : "**CORRECTNESS FAILURES: " . implode(', ', $corpusBad) . "** - affected timings withheld.\n\n";
+
+// Grid
+echo '| test |';
+foreach (array_keys($cells) as $label) {
+    echo " $label |";
+}
+echo "\n|---|" . str_repeat('---|', count($cells)) . "\n";
+foreach ($testIds as $id) {
+    echo "| $id |";
+    foreach ($cells as $data) {
+        $t = $data['tests'][$id] ?? null;
+        if ($t === null) {
+            echo ' - |';
+        } elseif (($t['verdict'] ?? '') === 'CORPUS_FAIL') {
+            echo ' **FAIL** |';
+        } else {
+            $r    = (float)$t['ratio'];
+            $text = sprintf('%.2fx', $r);
+            echo ' ' . ($r >= 1.05 ? "**$text**" : ($r <= 0.95 ? "$text (slower)" : $text)) . ' |';
+        }
+    }
+    echo "\n";
+}
+
+// Legend
+echo "\n<details><summary>Test legend (A vs B)</summary>\n\n";
+foreach ($legend as $id => [$a, $b]) {
+    echo "- **$id**: $a vs $b\n";
+}
+echo "\n</details>\n";