feat: add shared framework-neutral normalization and presentation helpers for debug adapters.

Author: terabytesoftw

CHANGELOG.md

@@ -9,3 +9,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - feat: add framework-agnostic debug snapshot contracts, strict JSON hydration, and filesystem persistence.
 - fix: bundle toolbar control icons and retry snapshot data while Yii3 finishes its post-response persistence.
+- feat: add shared framework-neutral normalization and presentation helpers for debug adapters.

README.md

@@ -1,6 +1,7 @@
 # Debug Core
 
-Framework-agnostic contracts, snapshots, storage primitives, and complete frontend for PHP debugger adapters.
+Framework-agnostic contracts, snapshots, storage primitives, normalization and presentation helpers, and complete
+frontend for PHP debugger adapters.
 
 This package is the shared engine used by framework-specific integrations. Applications should install an adapter
 instead of requiring this package directly.
@@ -15,10 +16,11 @@ composer require php-forge/debug-core
 
 ## Architecture
 
-The core package owns portable debug data, persistence, the frontend source and compiled files, shared fonts and icons,
-the toolbar data contract, and framework-neutral PHP templates composed with the agnostic `ui-awesome/html` helpers.
-It does not register assets, render responses, inject toolbar markup, or depend on Yii2, Yii3, an application
-container, a view implementation, or a framework request lifecycle.
+The core package owns portable debug data, persistence, normalization and presentation primitives under
+`PHPForge\Debug\Helper`, the frontend source and compiled files, shared fonts and icons, the toolbar data contract, and
+framework-neutral PHP templates composed with the agnostic UI Awesome HTML helpers. It does not register assets,
+render responses, inject toolbar markup, or depend on Yii2, Yii3, an application container, a view implementation, or
+a framework request lifecycle.
 
 Adapters collect framework data, convert it into immutable snapshots, expose toolbar data endpoints, define and
 publish assets through their framework, and render the shared templates with their framework view component. They also

composer.json

@@ -21,7 +21,8 @@
     "require": {
         "php": ">=8.3",
         "ext-mbstring": "*",
-        "ui-awesome/html": "^0.6"
+        "ui-awesome/html": "^0.6",
+        "ui-awesome/html-svg": "^0.6"
     },
     "require-dev": {
         "infection/infection": "^0.34",

src/Helper/Avatar.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Debug\Helper;
+
+use function abs;
+use function crc32;
+use function strtolower;
+
+/**
+ * Derives stable, deterministic avatar colours from arbitrary identifying strings.
+ *
+ * Two debug-panel renderers (mail and queue) display a colored circle next to each item; both used to compute the hue
+ * with the same `abs(crc32(strtolower(...))) % 360` formula. This helper centralises that derivation so the colour
+ * stays consistent across renderers.
+ */
+final class Avatar
+{
+    /**
+     * Fallback hue used when `$seed` is empty.
+     */
+    private const int DEFAULT_HUE = 210;
+
+    /**
+     * Returns a stable hue (`0..359`) for the given seed, or {@see self::DEFAULT_HUE} when the seed is empty.
+     *
+     * Usage example:
+     * ```php
+     * $hue = \PHPForge\Debug\Helper\Avatar::hueFor('Alice');
+     * ```
+     *
+     * @param string $seed Identifying value used to derive the hue.
+     *
+     * @return int Hue in the `0..359` range.
+     */
+    public static function hueFor(string $seed): int
+    {
+        if ($seed === '') {
+            return self::DEFAULT_HUE;
+        }
+
+        return abs(crc32(strtolower($seed))) % 360;
+    }
+}

src/Helper/CellMore.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Debug\Helper;
+
+use UIAwesome\Html\Flow\Div;
+use UIAwesome\Html\Form\Button;
+use UIAwesome\Html\Form\Values\ButtonType;
+
+use function strlen;
+
+/**
+ * Wraps long grid-cell content in a collapsible clamp with an expand/collapse pill toggle.
+ *
+ * The body collapses to a few lines through a CSS max-height clamp — the markup is never truncated server side, so
+ * any cell payload (plain text, highlighted SQL, trace lists) stays intact. The `debug.min.js` `cell-more` delegation
+ * flips the `is-open` state and swaps the toggle label.
+ */
+final class CellMore
+{
+    /**
+     * Row count beyond which a table is worth collapsing.
+     *
+     * Table height tracks the number of rows, not the payload size: a handful of verbose rows reads fine, while many
+     * terse ones still push the page past the viewport.
+     */
+    public const int ROW_THRESHOLD = 12;
+    /**
+     * Source length (bytes) beyond which a cell is worth collapsing.
+     */
+    public const int THRESHOLD = 600;
+
+    /**
+     * Wraps the content only when its source payload is long enough to be worth collapsing.
+     *
+     * The decision reads the raw source rather than the rendered markup, so highlighting or trace lists never tip a
+     * short value over the threshold.
+     *
+     * Usage example:
+     * ```php
+     * \PHPForge\Debug\Helper\CellMore::clamp($highlightedSql, $row->query);
+     * ```
+     *
+     * @param string $content Rendered cell HTML.
+     * @param string $source Raw payload the content was rendered from.
+     *
+     * @return string Original content or collapsible markup when the source exceeds the threshold.
+     */
+    public static function clamp(string $content, string $source): string
+    {
+        return strlen($source) > self::THRESHOLD ? self::wrap($content) : $content;
+    }
+
+    /**
+     * Wraps the rendered cell content in the collapsible clamp container.
+     *
+     * Usage example:
+     * ```php
+     * \PHPForge\Debug\Helper\CellMore::wrap($renderedCellHtml);
+     * ```
+     *
+     * @param string $content Rendered cell HTML to clamp; emitted verbatim inside the body container.
+     *
+     * @return string Collapsible cell markup.
+     */
+    public static function wrap(string $content): string
+    {
+        return Div::tag()
+            ->class('yii-debug-cell-more')
+            ->html(
+                Div::tag()
+                    ->class('yii-debug-cell-more-body')
+                    ->html($content),
+                Button::tag()
+                    ->addAriaAttribute('expanded', 'false')
+                    ->addAttribute('data-yii-debug-toggle', 'cell-more')
+                    ->class('yii-debug-cell-more-toggle')
+                    ->content('[+] Show more')
+                    ->type(ButtonType::BUTTON),
+            )
+            ->render();
+    }
+}

src/Helper/Coerce.php

@@ -0,0 +1,222 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Debug\Helper;
+
+use Stringable;
+
+use function is_array;
+use function is_numeric;
+use function is_scalar;
+use function is_string;
+
+/**
+ * Narrows arbitrary mixed payloads into the typed scalars debug-panel renderers expect.
+ *
+ * Framework callbacks, logger entries, request parameters, and renderer rows remain mixed even though persisted
+ * snapshots use strict JSON DTOs. This helper is limited to those external runtime boundaries; snapshot hydration is
+ * handled by {@see \PHPForge\Debug\Storage\Payload} without scalar coercion.
+ */
+final class Coerce
+{
+    /**
+     * Returns a numeric value as a float or the supplied default.
+     *
+     * Usage example:
+     * ```php
+     * $duration = \PHPForge\Debug\Helper\Coerce::float($payload['duration'] ?? null, 0.0);
+     * ```
+     *
+     * @param mixed $value Value to narrow.
+     * @param float $default Value returned for non-numeric input.
+     *
+     * @return float Numeric value or the configured default.
+     */
+    public static function float(mixed $value, float $default = 0.0): float
+    {
+        return self::floatOrNull($value) ?? $default;
+    }
+
+    /**
+     * Returns the value as a float when it is numeric, `null` otherwise.
+     *
+     * Usage example:
+     * ```php
+     * $duration = \PHPForge\Debug\Helper\Coerce::floatOrNull($payload['duration'] ?? null);
+     * ```
+     *
+     * @param mixed $value Value to narrow.
+     *
+     * @return float|null Numeric value or `null`.
+     */
+    public static function floatOrNull(mixed $value): float|null
+    {
+        return is_numeric($value) ? (float) $value : null;
+    }
+
+    /**
+     * Returns a numeric value as an int or the supplied default.
+     *
+     * Usage example:
+     * ```php
+     * $count = \PHPForge\Debug\Helper\Coerce::int($payload['count'] ?? null);
+     * ```
+     *
+     * @param mixed $value Value to narrow.
+     * @param int $default Value returned for non-numeric input.
+     *
+     * @return int Numeric value or the configured default.
+     */
+    public static function int(mixed $value, int $default = 0): int
+    {
+        return self::intOrNull($value) ?? $default;
+    }
+
+    /**
+     * Returns the value as an int when it is an integer or numeric, `null` otherwise.
+     *
+     * Usage example:
+     * ```php
+     * $statusCode = \PHPForge\Debug\Helper\Coerce::intOrNull($payload['statusCode'] ?? null);
+     * ```
+     *
+     * @param mixed $value Value to narrow.
+     *
+     * @return int|null Numeric value or `null`.
+     */
+    public static function intOrNull(mixed $value): int|null
+    {
+        return is_numeric($value) ? (int) $value : null;
+    }
+
+    /**
+     * Returns a string value or the supplied default.
+     *
+     * Usage example:
+     * ```php
+     * $category = \PHPForge\Debug\Helper\Coerce::string($payload['category'] ?? null, 'application');
+     * ```
+     *
+     * @param mixed $value Value to narrow.
+     * @param string $default Value returned for non-string input.
+     *
+     * @return string String value or the configured default.
+     */
+    public static function string(mixed $value, string $default = ''): string
+    {
+        return is_string($value) ? $value : $default;
+    }
+
+    /**
+     * Returns only the entries of `$data` whose key is a string, preserving order.
+     *
+     * Narrows a mixed/`array<array-key, mixed>` snapshot down to the `array<string, mixed>` shape downstream view-model
+     * normalizers expect.
+     *
+     * Usage example:
+     * ```php
+     * $data = \PHPForge\Debug\Helper\Coerce::stringKeyedArray(['name' => 'debug', 0 => 'ignored']);
+     * ```
+     *
+     * @param array<array-key, mixed> $data Source array with arbitrary keys.
+     *
+     * @return array<string, mixed> Entries whose key was already a string, in original order.
+     */
+    public static function stringKeyedArray(array $data): array
+    {
+        $normalized = [];
+
+        foreach ($data as $key => $value) {
+            if (is_string($key)) {
+                $normalized[$key] = $value;
+            }
+        }
+
+        return $normalized;
+    }
+
+    /**
+     * Returns only the string entries of a raw list, preserving order.
+     *
+     * Usage example:
+     * ```php
+     * $categories = \PHPForge\Debug\Helper\Coerce::stringList(['application', 42, 'database']);
+     * ```
+     *
+     * @param mixed $values Raw list, typically a user-configured category list.
+     *
+     * @return list<string> String entries in original order, possibly empty.
+     */
+    public static function stringList(mixed $values): array
+    {
+        if (!is_array($values)) {
+            return [];
+        }
+
+        $strings = [];
+
+        foreach ($values as $value) {
+            if (is_string($value)) {
+                $strings[] = $value;
+            }
+        }
+
+        return $strings;
+    }
+
+    /**
+     * Returns the value as a string when it is scalar or {@see Stringable}, `null` otherwise.
+     *
+     * Usage example:
+     * ```php
+     * $label = \PHPForge\Debug\Helper\Coerce::stringOrNull($payload['label'] ?? null);
+     * ```
+     *
+     * @param mixed $value Value to narrow.
+     *
+     * @return string|null String representation or `null`.
+     */
+    public static function stringOrNull(mixed $value): string|null
+    {
+        if (is_scalar($value) || $value instanceof Stringable) {
+            return (string) $value;
+        }
+
+        return null;
+    }
+
+    /**
+     * Narrows a raw trace value (as captured by Yii's logger) into the `list<array<string, mixed>>` shape every panel
+     * renderer consumes.
+     *
+     * Each frame keeps only its string-keyed entries; non-array frames are dropped.
+     *
+     * Usage example:
+     * ```php
+     * $frames = \PHPForge\Debug\Helper\Coerce::traceFrames($payload['trace'] ?? null);
+     * ```
+     *
+     * @param mixed $value Raw trace payload.
+     *
+     * @return list<array<string, mixed>> Trace frames normalized to string-keyed maps.
+     */
+    public static function traceFrames(mixed $value): array
+    {
+        if (!is_array($value)) {
+            return [];
+        }
+
+        $frames = [];
+
+        foreach ($value as $frame) {
+            if (!is_array($frame)) {
+                continue;
+            }
+
+            $frames[] = self::stringKeyedArray($frame);
+        }
+
+        return $frames;
+    }
+}