Add configurable console styles for CLI output, including severity backgrounds, syntax highlighting, and semantic tags. Refactor ConsoleStyler and CodeHighlighter to support overrides via config or environment variable. Update documentation with usage examples.

Author: raffaelecarelle

.phpunit.result.cache

@@ -38,6 +38,7 @@ Supported environment variables:
 - PHP_ERROR_INSIGHT_ROOT: absolute project root to compute relative file paths in the stack (optional)
 - PHP_ERROR_INSIGHT_HOST_ROOT: absolute host project root used to map container paths when opening files via editor links (optional; useful in Docker)
 - PHP_ERROR_INSIGHT_EDITOR: editor URL template for clickable file links, using %file and %line placeholders (e.g. "vscode://file/%file:%line" or "phpstorm://open?file=%file&line=%line")
+- PHP_ERROR_INSIGHT_CONSOLE_COLORS: JSON object to customize console styles (token colors, severity backgrounds, title/suggestions/stack/location).
 
 Configuration examples:
 
@@ -181,6 +182,79 @@ Technical details:
 
 For more details, see docs/sanitizzazione-dati-ai.md.
 
+## Console colors customization (CLI)
+
+You can customize the colors used in the CLI output (syntax highlighting, severity header background, title, AI suggestions, stack trace and locations).
+
+Two ways to configure:
+
+- Environment variable `PHP_ERROR_INSIGHT_CONSOLE_COLORS` containing a JSON object
+- Programmatic via `Config::fromEnvAndArray(['consoleColors' => [...]])`
+
+Structure of the JSON/object:
+
+```json
+{
+  "tokens": {
+    "default": ["white", null, []],
+    "comment": ["white", null, []],
+    "string": ["yellow", null, []],
+    "keyword": ["magenta", null, ["bold"]],
+    "html": ["cyan", null, ["bold"]],
+    "variable": ["cyan", null, []],
+    "function": ["blue", null, ["bold"]],
+    "method": ["green", null, ["underscore"]]
+  },
+  "severity": {
+    "error": "red",
+    "warning": "yellow",
+    "info": "blue"
+  },
+  "styles": {
+    "title": ["white", null, ["bold"]],
+    "suggestion": ["green", null, []],
+    "stack": ["yellow", null, []],
+    "location": ["blue", null, []],
+    "gutter_hl": ["white", "red", ["bold"]],
+    "gutter_num": ["gray", null, []],
+    "gutter_sep": ["gray", null, []]
+  }
+}
+```
+
+Notes:
+- Each style uses the form `[fg, bg, options[]]`. `fg` and `bg` accept Symfony Console color names (e.g., "white", "yellow", "red", "blue", "cyan", "magenta", "gray"), and `options` can include `bold`, `underscore`, `blink`, `reverse`, `conceal`.
+- `tokens` overrides the syntax highlighter palette for these categories: `default`, `comment`, `string`, `keyword`, `html`, `variable`, `function`, `method`.
+- `severity` maps `error|warning|info` to a background color name for the header badge with the severity label.
+- `styles` lets you tweak semantic tags used by the renderer: `title` (error message), `suggestion` (AI suggestions label and items), `stack` (stack trace lines when rendered in compact mode), `location` (file:line), `gutter_hl` (current line number in code excerpts), `gutter_num` (non-current line numbers), and `gutter_sep` (the vertical separator).
+- Any key you omit falls back to sensible defaults.
+
+Examples
+
+- Via environment variable:
+
+```bash
+export PHP_ERROR_INSIGHT_CONSOLE_COLORS='{
+  "severity": {"error":"magenta","warning":"yellow","info":"cyan"},
+  "styles": {"title":["white",null,["bold"]],"suggestion":["cyan",null,[]]},
+  "tokens": {"keyword":["magenta",null,["bold"]],"string":["green",null,[]]}
+}'
+```
+
+- Via code:
+
+```php
+use PhpErrorInsight\Config;
+
+$config = Config::fromEnvAndArray([
+    'consoleColors' => [
+        'severity' => [ 'error' => 'magenta', 'warning' => 'yellow', 'info' => 'blue' ],
+        'styles' => [ 'title' => ['white', null, ['bold']], 'suggestion' => ['cyan', null, []] ],
+        'tokens' => [ 'keyword' => ['magenta', null, ['bold']], 'string' => ['green', null, []] ],
+    ],
+]);
+```
+
 ## Development
 
 This project uses several development tools to maintain code quality. Use the following composer scripts for easy access to these tools:

README.md

@@ -5,7 +5,7 @@
 // Minimal example demonstrating PHP Error Explainer
 // Run with: php examples/vanilla/index.php
 // Optional AI config (env):
-//   PHP_ERROR_INSIGHT_BACKEND=none|local|api|openai|anthropic|google|gemini
+// called   PHP_ERROR_INSIGHT_BACKEND=none|local|api|openai|anthropic|google|gemini
 //   PHP_ERROR_INSIGHT_MODEL=llama3:instruct|gpt-4o-mini|claude-3-5-sonnet-20240620|gemini-1.5-flash|...
 //   PHP_ERROR_INSIGHT_API_URL=http://localhost:11434 (Ollama) | https://api.openai.com/v1/chat/completions (OpenAI) | https://api.anthropic.com/v1/messages (Anthropic) | https://generativelanguage.googleapis.com/v1/models (Google Gemini)
 //   PHP_ERROR_INSIGHT_API_KEY=sk-... (OpenAI) | api-key (Anthropic) | api-key (Google Gemini)
@@ -34,4 +34,5 @@
 trigger_error((string) "function called.", E_USER_NOTICE);
 trigger_error("function called.", E_USER_DEPRECATED);
 trigger_error("function called.", E_USER_WARNING);
+@trigger_error((string) "Should skipped.", E_USER_NOTICE); //should skip error
 throw new Exception("exception thrown.");

examples/vanilla/index.php

@@ -6,6 +6,7 @@
 
 use function array_key_exists;
 use function in_array;
+use function is_array;
 
 final class Config
 {
@@ -41,6 +42,31 @@ final class Config
 
     public ?string $editorUrl = null; // template like "vscode://file/%file:%line" or "phpstorm://open?file=%file&line=%line"
 
+    /**
+     * Console colors and styles configuration.
+     * Structure example:
+     * [
+     *   'tokens' => [ 'default' => ['white', null, []], ... ],
+     *   'styles' => [
+     *       'yellow' => ['yellow', null, []],
+     *       'green' => ['green', null, []],
+     *       'blue' => ['blue', null, []],
+     *       'dim' => ['gray', null, []],
+     *       'boldwhite' => ['white', null, ['bold']],
+     *       'gutter_hl' => ['white', 'red', ['bold']],
+     *       'gutter_num' => ['gray', null, []],
+     *       'gutter_sep' => ['gray', null, []],
+     *       'title' => ['white', null, ['bold']],
+     *       'suggestion' => ['green', null, []],
+     *       'stack' => ['yellow', null, []],
+     *       'location' => ['blue', null, []]
+     *   ]
+     * ].
+     *
+     * @var array<string, mixed>|null
+     */
+    public ?array $consoleColors = null;
+
     /**
      * @param array<string, mixed> $options
      */
@@ -93,6 +119,10 @@ public function __construct(array $options = [])
         if (array_key_exists('editorUrl', $options)) {
             $this->editorUrl = null !== $options['editorUrl'] ? (string) $options['editorUrl'] : null;
         }
+
+        if (array_key_exists('consoleColors', $options)) {
+            $this->consoleColors = is_array($options['consoleColors']) ? $options['consoleColors'] : null;
+        }
     }
 
     /**
@@ -113,6 +143,16 @@ public static function fromEnvAndArray(array $options = []): self
             'projectRoot' => self::getEnvVar('PHP_ERROR_INSIGHT_ROOT') ?: null,
             'hostProjectRoot' => self::getEnvVar('PHP_ERROR_INSIGHT_HOST_ROOT') ?: null,
             'editorUrl' => self::getEnvVar('PHP_ERROR_INSIGHT_EDITOR') ?: null,
+            'consoleColors' => (function (): ?array {
+                $raw = self::getEnvVar('PHP_ERROR_INSIGHT_CONSOLE_COLORS');
+                if (false === $raw || '' === $raw || '0' === $raw) {
+                    return null;
+                }
+
+                $decoded = json_decode($raw, true);
+
+                return is_array($decoded) ? $decoded : null;
+            })(),
         ];
         // Options override env
         $merged = array_merge($env, $options);

src/Config.php

@@ -53,9 +53,24 @@ final class CodeHighlighter
      *   pe-tok-string, pe-tok-comment, pe-tok-keyword, pe-tok-default, pe-tok-html
      *   plus: pe-tok-variable, pe-tok-function, pe-tok-method
      */
-    public function registerStyles(OutputFormatterInterface $formatter, string $theme = self::THEME_DEFAULT): void
+    /**
+     * @param array<string, array{0?:string,1?:string|null,2?:array<string>}>|null $overrides
+     */
+    public function registerStyles(OutputFormatterInterface $formatter, string $theme = self::THEME_DEFAULT, ?array $overrides = null): void
     {
         $palette = $this->paletteFor($theme);
+        if (is_array($overrides)) {
+            // Merge overrides into palette (shallow per key)
+            foreach ($overrides as $k => $spec) {
+                if (is_array($spec)) {
+                    $palette[$k] = [
+                        $spec[0] ?? ($palette[$k][0] ?? 'white'),
+                        $spec[1] ?? ($palette[$k][1] ?? null),
+                        $spec[2] ?? ($palette[$k][2] ?? []),
+                    ];
+                }
+            }
+        }
 
         $formatter->setStyle('pe-tok-string', new OutputFormatterStyle(
             $palette['string'][0] ?? 'green',

src/Internal/CodeHighlighter.php

@@ -7,6 +7,9 @@
 use Symfony\Component\Console\Formatter\OutputFormatterInterface;
 use Symfony\Component\Console\Formatter\OutputFormatterStyle;
 
+use function is_array;
+use function is_string;
+
 /**
  * ConsoleStyler defines style tags and helps produce tagged strings.
  *
@@ -16,19 +19,71 @@ final class ConsoleStyler
 {
     /**
      * Register our custom styles into a Symfony Output formatter.
+     *
+     * @param array<string,mixed>|null $config styles override structure (Config::$consoleColors)
      */
-    public function registerStyles(OutputFormatterInterface $formatter): void
+    public function registerStyles(OutputFormatterInterface $formatter, ?array $config = null): void
     {
-        $formatter->setStyle('pe-yellow', new OutputFormatterStyle('yellow'));
-        $formatter->setStyle('pe-green', new OutputFormatterStyle('green'));
-        $formatter->setStyle('pe-blue', new OutputFormatterStyle('blue'));
-        $formatter->setStyle('pe-dim', new OutputFormatterStyle('gray'));
-        $formatter->setStyle('pe-boldwhite', new OutputFormatterStyle('white', null, ['bold']));
-        $formatter->setStyle('pe-header-red', new OutputFormatterStyle('white', 'red', ['bold']));
-        $formatter->setStyle('pe-header-yellow', new OutputFormatterStyle('white', 'yellow', ['bold']));
-        $formatter->setStyle('pe-header-blue', new OutputFormatterStyle('white', 'blue', ['bold']));
-        $formatter->setStyle('pe-gutter-hl', new OutputFormatterStyle('white', 'red', ['bold']));
+        $styles = is_array($config) && isset($config['styles']) && is_array($config['styles']) ? $config['styles'] : [];
+
+        // Helper to read [fg, bg, options[]]
+        $spec = static function (array $styles, string $key, array $def): array {
+            $v = $styles[$key] ?? null;
+            if (!is_array($v)) {
+                return $def;
+            }
+
+            return [
+                (string) ($v[0] ?? $def[0]),
+                null !== ($v[1] ?? null) ? (string) $v[1] : ($def[1] ?? null),
+                is_array($v[2] ?? null) ? $v[2] : ($def[2] ?? []),
+            ];
+        };
+
+        // Core text styles (defaults preserve current behavior)
+        [$fg, $bg, $opt] = $spec($styles, 'yellow', ['yellow', null, []]);
+        $formatter->setStyle('pe-yellow', new OutputFormatterStyle($fg, $bg, $opt));
+        [$fg, $bg, $opt] = $spec($styles, 'green', ['green', null, []]);
+        $formatter->setStyle('pe-green', new OutputFormatterStyle($fg, $bg, $opt));
+        [$fg, $bg, $opt] = $spec($styles, 'blue', ['blue', null, []]);
+        $formatter->setStyle('pe-blue', new OutputFormatterStyle($fg, $bg, $opt));
+        [$fg, $bg, $opt] = $spec($styles, 'dim', ['gray', null, []]);
+        $formatter->setStyle('pe-dim', new OutputFormatterStyle($fg, $bg, $opt));
+        [$fg, $bg, $opt] = $spec($styles, 'boldwhite', ['white', null, ['bold']]);
+        $formatter->setStyle('pe-boldwhite', new OutputFormatterStyle($fg, $bg, $opt));
 
+        // Title, Suggestion, Stack, Location semantic tags (new; default map to old colors)
+        [$fg, $bg, $opt] = $spec($styles, 'title', ['white', null, ['bold']]);
+        $formatter->setStyle('pe-title', new OutputFormatterStyle($fg, $bg, $opt));
+        [$fg, $bg, $opt] = $spec($styles, 'suggestion', ['green', null, []]);
+        $formatter->setStyle('pe-suggestion', new OutputFormatterStyle($fg, $bg, $opt));
+        [$fg, $bg, $opt] = $spec($styles, 'stack', ['yellow', null, []]);
+        $formatter->setStyle('pe-stack', new OutputFormatterStyle($fg, $bg, $opt));
+        [$fg, $bg, $opt] = $spec($styles, 'location', ['blue', null, []]);
+        $formatter->setStyle('pe-location', new OutputFormatterStyle($fg, $bg, $opt));
+
+        // Gutter styles
+        [$fg, $bg, $opt] = $spec($styles, 'gutter_hl', ['white', 'red', ['bold']]);
+        $formatter->setStyle('pe-gutter-hl', new OutputFormatterStyle($fg, $bg, $opt));
+        [$fg, $bg, $opt] = $spec($styles, 'gutter_num', ['gray', null, []]);
+        $formatter->setStyle('pe-gutter-num', new OutputFormatterStyle($fg, $bg, $opt));
+        [$fg, $bg, $opt] = $spec($styles, 'gutter_sep', ['gray', null, []]);
+        $formatter->setStyle('pe-gutter-sep', new OutputFormatterStyle($fg, $bg, $opt));
+
+        // Severity backgrounds: build tags like pe-header-<color>
+        $sev = is_array($config) && isset($config['severity']) && is_array($config['severity']) ? $config['severity'] : [];
+        $bgColors = ['red', 'yellow', 'blue'];
+        foreach (['error', 'warning', 'info'] as $k) {
+            $v = $sev[$k] ?? null;
+            if (is_string($v) && '' !== $v) {
+                $bgColors[] = strtolower($v);
+            }
+        }
+
+        $bgColors = array_values(array_unique($bgColors));
+        foreach ($bgColors as $c) {
+            $formatter->setStyle('pe-header-' . $c, new OutputFormatterStyle('white', $c, ['bold']));
+        }
     }
 
     private function tag(string $name, string $s): string
@@ -82,4 +137,49 @@ public function gutterHighlight(string $s): string
     {
         return $this->tag('pe-gutter-hl', $s);
     }
+
+    /**
+     * Default gutter line number (non-highlighted lines).
+     */
+    public function gutterNumber(string $s): string
+    {
+        return $this->tag('pe-gutter-num', $s);
+    }
+
+    /**
+     * Gutter vertical separator style.
+     */
+    public function gutterSeparator(string $s): string
+    {
+        return $this->tag('pe-gutter-sep', $s);
+    }
+
+    // Convenience wrappers for semantic styles
+    public function title(string $s): string
+    {
+        return $this->tag('pe-title', $s);
+    }
+
+    public function suggestion(string $s): string
+    {
+        return $this->tag('pe-suggestion', $s);
+    }
+
+    public function stack(string $s): string
+    {
+        return $this->tag('pe-stack', $s);
+    }
+
+    public function location(string $s): string
+    {
+        return $this->tag('pe-location', $s);
+    }
+
+    /**
+     * Bold white text on named background color (e.g., 'red','yellow','blue', ...).
+     */
+    public function headerOnBgName(string $bgName, string $s): string
+    {
+        return $this->tag('pe-header-' . strtolower($bgName), $s);
+    }
 }