@barefootjs/php 0.1.0

package/src/Json.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Barefoot;
+
+/**
+ * Canonical (sorted-key, JS-`JSON.stringify`-parity) JSON encoding, shared by
+ * every engine backend (`TwigBackend`, and future `BladeBackend` et al.).
+ * Extracted from `TwigBackend::defaultJsonEncoder` / `prepareForJson` so the
+ * engine-agnostic runtime (`BarefootJS`) and any backend can depend on one
+ * canonical encoder without depending on a specific template engine.
+ */
+final class Json
+{
+    /**
+     * `sort_keys` parity with the Python backend's `default_json_encoder`
+     * (`sort_keys=True`) / the Xslate backend's `JSON::PP->canonical`: keys
+     * are recursively sorted so output is deterministic. `JSON_UNESCAPED_SLASHES`
+     * matches `JSON.stringify`'s un-escaped `/`. Non-ASCII is `\uXXXX`-escaped
+     * (PHP's default, matching Python's default `ensure_ascii`).
+     */
+    public static function canonicalEncode($data): string
+    {
+        $prepared = self::prepareForJson($data);
+        $json = json_encode($prepared, JSON_UNESCAPED_SLASHES);
+        if ($json === false) {
+            throw new \RuntimeException('encode_json failed: ' . json_last_error_msg());
+        }
+        return $json;
+    }
+
+    /**
+     * Recursively replace non-finite floats with `null` (JSON has no
+     * NaN/Infinity -- matches `JSON.stringify(NaN)` at any depth) and sort
+     * object keys (stdClass or a non-list/assoc array) for canonical,
+     * deterministic output. List arrays are recursed element-wise without
+     * reordering.
+     */
+    private static function prepareForJson($value)
+    {
+        if (is_float($value)) {
+            return (is_nan($value) || is_infinite($value)) ? null : $value;
+        }
+        if ($value instanceof \stdClass) {
+            $vars = get_object_vars($value);
+            ksort($vars, SORT_STRING);
+            $out = new \stdClass();
+            foreach ($vars as $k => $v) {
+                $out->$k = self::prepareForJson($v);
+            }
+            return $out;
+        }
+        if (is_array($value)) {
+            if (array_is_list($value)) {
+                return array_map([self::class, 'prepareForJson'], $value);
+            }
+            $out = [];
+            foreach ($value as $k => $v) {
+                $out[$k] = self::prepareForJson($v);
+            }
+            ksort($out, SORT_STRING);
+            return $out;
+        }
+        return $value;
+    }
+}

package/src/SearchParams.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Barefoot;
+
+/**
+ * Port of packages/adapter-perl/lib/BarefootJS/SearchParams.pm (see also the
+ * Python port packages/adapter-jinja/python/barefootjs/search_params.py).
+ *
+ * Request-scoped SSR view of the query string behind the reactive
+ * `searchParams()` environment signal (router v0.5, #1922). The framework
+ * integration builds one per request from the request URL and threads it
+ * into the template scope as `searchParams`; the compiled template reads it
+ * via `{{ searchParams.get('key') }}`.
+ *
+ * Semantics mirror the browser's `URLSearchParams.get` exactly under the
+ * adapters' `?? ->` lowering: `get()` returns the first value for a key, or
+ * `null` when the key is absent -- Twig's native `??` coalesces both
+ * "undefined" and `null`, so `searchParams.get('sort') ?? 'name'` falls back
+ * only when the key is truly absent, while a present-but-empty value
+ * (`?sort=`) keeps the empty string.
+ */
+final class SearchParams
+{
+    /** @var array<string, list<string>> */
+    private array $values = [];
+
+    public function __construct(string $query = '')
+    {
+        if (str_starts_with($query, '?')) {
+            $query = substr($query, 1);
+        }
+        foreach (preg_split('/[&;]/', $query) as $pair) {
+            if ($pair === '') {
+                continue;
+            }
+            $eq = strpos($pair, '=');
+            if ($eq === false) {
+                $key = $pair;
+                $rawVal = null;
+            } else {
+                $key = substr($pair, 0, $eq);
+                $rawVal = substr($pair, $eq + 1);
+            }
+            $decodedKey = self::decode($key);
+            $decodedVal = $rawVal !== null ? self::decode($rawVal) : '';
+            $this->values[$decodedKey][] = $decodedVal;
+        }
+    }
+
+    /** First value for `$key`, or `null` when the key is absent. A
+     * present-but-empty value returns ''. */
+    public function get(string $key): ?string
+    {
+        $vals = $this->values[$key] ?? null;
+        if (!$vals) {
+            return null;
+        }
+        return $vals[0];
+    }
+
+    /** Percent/`+`-decode a query-string component, mirroring
+     * `URLSearchParams`'s `application/x-www-form-urlencoded` parsing. Never
+     * raises on malformed input -- PHP strings are raw byte sequences, so an
+     * invalid UTF-8 byte run is simply carried through unchanged (the same
+     * lenient behaviour Perl's `utf8::decode` -- which never dies -- gives). */
+    private static function decode(string $s): string
+    {
+        $s = str_replace('+', ' ', $s);
+        return (string) preg_replace_callback(
+            '/%([0-9A-Fa-f]{2})/',
+            static fn (array $m) => chr((int) hexdec($m[1])),
+            $s
+        );
+    }
+}

package/tests/_harness.php

@@ -0,0 +1,164 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Tiny zero-dependency TAP-ish assertion harness shared by every
+ * php/tests/test_*.php file (NOT one of the design doc's 9 test files
+ * itself -- a private support module, mirroring how the Perl port's t/*.t
+ * files share Test::More and the Python port's test_*.py files share
+ * unittest.TestCase; this package intentionally carries no PHPUnit
+ * dependency, so this file is the minimal stand-in).
+ *
+ * Each test file:
+ *   1. `require_once`s this file (guarded so it's a no-op on a second load).
+ *   2. calls `bf_reset()` to start with a clean per-file counter.
+ *   3. calls `bf_test($name, fn)` once per case.
+ *   4. ends with `bf_finish()`, which either `return`s a
+ *      `['pass' => n, 'fail' => n]` summary (when `run.php` is driving,
+ *      signalled by the `BF_RUNNER` constant) or prints a summary and
+ *      `exit()`s with the right code (when the file is run standalone via
+ *      `php test_foo.php`).
+ */
+
+$GLOBALS['__bf_pass'] = 0;
+$GLOBALS['__bf_fail'] = 0;
+$GLOBALS['__bf_failures'] = [];
+$GLOBALS['__bf_skipped'] = false;
+$GLOBALS['__bf_skip_count'] = 0;
+
+function bf_reset(): void
+{
+    $GLOBALS['__bf_pass'] = 0;
+    $GLOBALS['__bf_fail'] = 0;
+    $GLOBALS['__bf_failures'] = [];
+    $GLOBALS['__bf_skipped'] = false;
+    $GLOBALS['__bf_skip_count'] = 0;
+}
+
+function bf_test(string $name, callable $fn): void
+{
+    try {
+        $fn();
+        $GLOBALS['__bf_pass']++;
+        echo "ok - {$name}\n";
+    } catch (\Throwable $e) {
+        $GLOBALS['__bf_fail']++;
+        $GLOBALS['__bf_failures'][] = "{$name}: {$e->getMessage()}";
+        echo "not ok - {$name}: {$e->getMessage()}\n";
+    }
+}
+
+/**
+ * Record one case as VISIBLY skipped (TAP "# SKIP" directive), as opposed
+ * to `bf_test()`'s pass/fail -- used for a per-backend `unsupported`
+ * declaration (spec/template-helpers.md "Adapter status model"), so a
+ * helper with no binding on this backend shows up in the run's output
+ * instead of silently vanishing from the case count.
+ */
+function bf_skip(string $name, string $reason): void
+{
+    $GLOBALS['__bf_skip_count']++;
+    echo "ok - {$name} # SKIP {$reason}\n";
+}
+
+function bf_assert(bool $cond, string $message = 'assertion failed'): void
+{
+    if (!$cond) {
+        throw new \RuntimeException($message);
+    }
+}
+
+function bf_fmt($v): string
+{
+    if ($v === null) {
+        return 'null';
+    }
+    if (is_bool($v)) {
+        return $v ? 'true' : 'false';
+    }
+    if (is_float($v) && is_nan($v)) {
+        return 'NaN';
+    }
+    if (is_scalar($v)) {
+        return var_export($v, true);
+    }
+    if ($v instanceof \stdClass) {
+        return 'object:' . json_encode($v);
+    }
+    return json_encode($v);
+}
+
+function bf_assert_eq($actual, $expected, string $message = ''): void
+{
+    $ok = $actual === $expected;
+    if (!$ok && is_float($actual) && is_float($expected) && is_nan($actual) && is_nan($expected)) {
+        $ok = true;
+    }
+    if (!$ok) {
+        $prefix = $message !== '' ? "{$message}: " : '';
+        throw new \RuntimeException($prefix . 'expected ' . bf_fmt($expected) . ', got ' . bf_fmt($actual));
+    }
+}
+
+function bf_assert_nan($actual, string $message = 'expected NaN'): void
+{
+    bf_assert(is_float($actual) && is_nan($actual), $message . ' (got ' . bf_fmt($actual) . ')');
+}
+
+/** Mark the whole file as skipped (e.g. a golden-vectors fixture or vendor/
+ * dependency isn't available). Distinct from a failing test. */
+function bf_skip_file(string $reason): void
+{
+    echo "skip - {$reason}\n";
+    $GLOBALS['__bf_skipped'] = true;
+}
+
+function bf_finish(): array
+{
+    $pass = $GLOBALS['__bf_pass'];
+    $fail = $GLOBALS['__bf_fail'];
+    $skipped = $GLOBALS['__bf_skipped'];
+    $skipCount = $GLOBALS['__bf_skip_count'];
+    if ($fail > 0) {
+        fwrite(STDERR, "\nFailures:\n");
+        foreach ($GLOBALS['__bf_failures'] as $f) {
+            fwrite(STDERR, "  - {$f}\n");
+        }
+    }
+    $result = ['pass' => $pass, 'fail' => $fail, 'skipped' => $skipped, 'skip_count' => $skipCount];
+    if (defined('BF_RUNNER')) {
+        return $result;
+    }
+    printf(
+        "%s: pass=%d fail=%d%s%s\n",
+        basename($_SERVER['SCRIPT_NAME'] ?? 'test'),
+        $pass,
+        $fail,
+        $skipCount > 0 ? " skip={$skipCount}" : '',
+        $skipped ? ' (skipped)' : ''
+    );
+    exit($fail > 0 ? 1 : 0);
+}
+
+/** Require the engine-agnostic runtime source files directly (no composer
+ * autoload needed). Idempotent.
+ *
+ * This package (`packages/adapter-php`) carries no engine-specific code --
+ * no `naming.php` (Twig's reserved-word set) and no `TwigBackend.php` -- so
+ * every test in this directory either needs no backend at all, or supplies
+ * its own small stub implementing the five-method backend contract
+ * (`encode_json`, `mark_raw`, `materialize`, `render_named`, `ident`). The
+ * one test that needs a REAL engine backend (a live Twig render) is
+ * `packages/adapter-twig/php/tests/test_render.php`, which lives in that
+ * engine adapter's own package and requires this file via a relative path. */
+function bf_require_runtime(): void
+{
+    if (class_exists(\Barefoot\BarefootJS::class)) {
+        return;
+    }
+    require_once __DIR__ . '/../src/Evaluator.php';
+    require_once __DIR__ . '/../src/SearchParams.php';
+    require_once __DIR__ . '/../src/Json.php';
+    require_once __DIR__ . '/../src/BarefootJS.php';
+}

package/tests/run.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Zero-dependency test runner for the engine-agnostic BarefootJS PHP
+ * runtime -- NO PHPUnit. Requires each `test_*.php` file (every one is also
+ * independently runnable via `php test_foo.php`), aggregates each file's
+ * tiny TAP-ish summary, prints a final report, and exits 1 on any failure.
+ *
+ * Usage: `php tests/run.php` from the package root, or
+ * `php packages/adapter-php/tests/run.php` from the repo root.
+ *
+ * `test_render.php` (a real, live Twig render) is NOT in this list -- it's
+ * engine-specific and lives (and runs standalone) in
+ * `packages/adapter-twig/php/tests/test_render.php`.
+ */
+
+define('BF_RUNNER', true);
+
+require_once __DIR__ . '/_harness.php';
+bf_require_runtime();
+
+$testFiles = [
+    'test_helper_vectors.php',
+    'test_eval_vectors.php',
+    'test_evaluator.php',
+    'test_template_primitives.php',
+    'test_query.php',
+    'test_search_params.php',
+    'test_spread_attrs.php',
+    'test_omit.php',
+    'test_props_attr.php',
+    'test_render_child.php',
+];
+
+$results = [];
+$totalPass = 0;
+$totalFail = 0;
+
+foreach ($testFiles as $file) {
+    $path = __DIR__ . '/' . $file;
+    echo "\n== {$file} ==\n";
+    if (!is_file($path)) {
+        fwrite(STDERR, "missing test file: {$file}\n");
+        $results[] = [$file, ['pass' => 0, 'fail' => 1, 'skipped' => false]];
+        $totalFail++;
+        continue;
+    }
+    bf_reset();
+    $result = require $path;
+    if (!is_array($result)) {
+        // A test file that didn't `return bf_finish()` (shouldn't happen,
+        // but don't let a silent misconfiguration hide as a pass).
+        $result = ['pass' => 0, 'fail' => 1, 'skipped' => false];
+        fwrite(STDERR, "{$file} did not return a summary array\n");
+    }
+    $results[] = [$file, $result];
+    $totalPass += $result['pass'];
+    $totalFail += $result['fail'];
+}
+
+echo "\n== Summary ==\n";
+foreach ($results as [$file, $result]) {
+    $flag = !empty($result['skipped']) ? ' (skipped)' : '';
+    $skipCount = $result['skip_count'] ?? 0;
+    $skipSuffix = $skipCount > 0 ? " skip={$skipCount}" : '';
+    printf("%-32s pass=%-4d fail=%-4d%s%s\n", $file, $result['pass'], $result['fail'], $skipSuffix, $flag);
+}
+printf("TOTAL: pass=%d fail=%d\n", $totalPass, $totalFail);
+
+exit($totalFail > 0 ? 1 : 0);

package/tests/test_eval_vectors.php

@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Golden ParsedExpr-evaluator vectors, ported from
+ * packages/adapter-perl/t/eval_vectors.t (see also the Python port's
+ * test_eval_vectors.py).
+ *
+ * Runs packages/adapter-tests/vectors/eval-vectors.json -- generated
+ * from the JS reference evaluator, shared with the Go/Perl/Python
+ * evaluators -- against Evaluator::evaluate(). The evaluator is JS-faithful
+ * by contract, so unlike the helper vectors there are NO PHP-side
+ * divergences here: each case's real ParsedExpr tree, evaluated against its
+ * environment, must reproduce the JS-computed expect exactly.
+ *
+ * A missing corpus file is a LOUD failure (see test_helper_vectors.php's
+ * docstring for why) -- not a silent skip.
+ */
+
+require_once __DIR__ . '/_harness.php';
+bf_require_runtime();
+bf_reset();
+
+use Barefoot\Evaluator;
+
+$VECTORS_PATH = __DIR__ . '/../../adapter-tests/vectors/eval-vectors.json';
+
+if (!is_file($VECTORS_PATH)) {
+    bf_test('golden eval-vectors corpus is present', function () use ($VECTORS_PATH) {
+        bf_assert(false, "eval-vectors.json not found at {$VECTORS_PATH} -- regenerate it (cd packages/adapter-tests && bun run generate:eval-vectors) or check this path after a corpus move");
+    });
+    return bf_finish();
+}
+
+/**
+ * Spec value-compat comparison -- non-finite sentinel hashes, booleans by
+ * TYPE (a boolean-valued JS operator must return a real PHP bool, not a
+ * truthy int), numbers numerically, arrays/objects recursively, strings by
+ * equality.
+ */
+function bfe_match($got, $expect): bool
+{
+    if ($expect === null) {
+        return $got === null;
+    }
+    if (is_array($expect) && array_key_exists('$num', $expect) && count($expect) === 1) {
+        $kind = $expect['$num'];
+        if (is_bool($got) || !(is_int($got) || is_float($got))) {
+            return false;
+        }
+        $g = (float) $got;
+        if ($kind === 'NaN') {
+            return is_nan($g);
+        }
+        return $g === ($kind === 'Infinity' ? INF : -INF);
+    }
+    if (is_bool($expect)) {
+        return is_bool($got) && $got === $expect;
+    }
+    if (is_array($expect) && array_is_list($expect)) {
+        if (!is_array($got) || !array_is_list($got) || count($got) !== count($expect)) {
+            return false;
+        }
+        foreach ($expect as $i => $e) {
+            if (!bfe_match($got[$i] ?? null, $e)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if (is_array($expect)) { // JSON object
+        $gotArr = $got instanceof \stdClass ? get_object_vars($got) : (is_array($got) ? $got : null);
+        if ($gotArr === null || count($gotArr) !== count($expect)) {
+            return false;
+        }
+        foreach ($expect as $k => $v) {
+            if (!array_key_exists($k, $gotArr) || !bfe_match($gotArr[$k], $v)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if ($got === null || is_array($got) || $got instanceof \stdClass) {
+        return false;
+    }
+    // Numeric comparison only when BOTH are real numbers (not a
+    // numeric-looking string) -- e.g. String(42) must return the string
+    // "42", and evaluating it as the number 42 must NOT pass.
+    $wantNum = is_int($expect) || is_float($expect);
+    $gotNum = is_int($got) || is_float($got);
+    if ($wantNum !== $gotNum) {
+        return false;
+    }
+    if ($wantNum) {
+        if (is_int($got) && is_int($expect)) {
+            return $got === $expect;
+        }
+        return (float) $got === (float) $expect;
+    }
+    return $got === $expect;
+}
+
+$doc = json_decode(file_get_contents($VECTORS_PATH), true);
+bf_assert(!empty($doc['cases']), 'eval-vectors.json contains no cases');
+
+foreach ($doc['cases'] as $case) {
+    $note = $case['note'];
+    $expr = $case['expr'];
+    $env = $case['env'] ?? [];
+    $expect = $case['expect'];
+
+    bf_test($note, function () use ($expr, $env, $expect, $note) {
+        $got = Evaluator::evaluate($expr, $env);
+        bf_assert(bfe_match($got, $expect), "{$note}: got " . bf_fmt($got) . ', want ' . bf_fmt($expect));
+    });
+}
+
+return bf_finish();