Highlight Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tempest/highlight
   

   Add to composer.json if using Laravel's autoloader:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Tempest\\Highlight\\": "vendor/tempest/highlight/src/"
       }
   }
   

   Run composer dump-autoload.

2. First Usage:

   use Tempest\Highlight\Highlighter;
   
   $highlighter = new Highlighter();
   $highlighted = $highlighter->parse('<?php echo "Hello"; ?>', 'php');
   echo $highlighted;
   

3. Key Classes:

   • Highlighter: Core class for parsing and rendering.
   • Renderer\HtmlRenderer: Default HTML renderer (extend for custom output).
   • Language\LanguageManager: Registers and manages language definitions.

First Use Case: Laravel Blade Integration

Add a Blade directive to highlight code snippets:

// app/Providers/AppServiceProvider.php
use Tempest\Highlight\Highlighter;

public function boot()
{
    Blade::directive('highlight', function ($expression) {
        $highlighter = new Highlighter();
        $language = $expression ?? 'text';
        return "<?php echo (new \\Tempest\\Highlight\\Highlighter())->parse(" . $expression . ", '{$language}'); ?>";
    });
}

Usage in Blade:

@highlight('return $this->parse($code, $language);', 'php')

Implementation Patterns

1. Language-Specific Highlighting

• Default Languages: PHP, JavaScript, CSS, HTML, Markdown, Bash, etc. (see supported languages).
• Custom Languages:

  $highlighter->registerLanguage(new \Tempest\Highlight\Language\CustomLanguage('custom', $rules));
  

2. Renderer Customization

Extend Renderer\AbstractRenderer for custom output (e.g., JSON, ANSI for CLI):

use Tempest\Highlight\Renderer\AbstractRenderer;

class JsonRenderer extends AbstractRenderer {
    public function renderToken(Token $token): string {
        return json_encode([
            'text' => $token->getText(),
            'type' => $token->getType(),
        ]);
    }
}

Register it:

$highlighter->setRenderer(new JsonRenderer());

3. Theming

• Built-in Themes: default, github, monokai, catppuccin, etc.
• Custom Themes:

  $highlighter->setTheme('custom', [
      'keyword' => '#ff0000',
      'string' => '#00ff00',
  ]);
  

4. Performance Optimization

• Caching Parsed Code:

  $cache = new \Symfony\Component\Cache\Adapter\FilesystemAdapter();
  $highlighter->setCache($cache);
  

• Disable Gutter for Non-Web Contexts:

  $highlighter->setGutter(false);
  

5. Integration with Laravel Ecosystem

• API Responses:

  return response()->json([
      'code' => $highlighter->parse($request->code, $request->language),
  ]);
  

• Markdown Parsing (e.g., with spatie/laravel-markdown):

  $markdown = Markdown::parse("# Code Example\n```php\n<?php echo 'Hello'; ?>\n```");
  $highlighted = $highlighter->parse($markdown->getContent(), 'php');
  

6. CLI Usage

Highlight code in Artisan commands or terminal output:

use Symfony\Component\Console\Style\SymfonyStyle;

$io = new SymfonyStyle($input, $output);
$io->text($highlighter->parse($code, 'bash', 'terminal'));

Gotchas and Tips

1. Common Pitfalls

• Language Auto-Detection:

  • The package does not auto-detect languages. Always specify the language explicitly (e.g., 'php', 'javascript').
  • Use a fallback language for unknown types:

    $highlighter->setFallbackLanguage('text');
    

• Whitespace Sensitivity:

  • Preserve indentation in code snippets. Avoid trimming input code unless intentional:

    $highlighter->setTrimCode(false);
    

• Blade Template Conflicts:

  • If using with Blade, escape dynamic code to avoid syntax errors:

    @highlight(e('<?php echo $dynamic_code; ?>'), 'php')
    

• Terminal Output:

  • Ensure ANSI escape sequences are supported in your terminal. For non-ANSI terminals, use a fallback renderer:

    $highlighter->setRenderer(new \Tempest\Highlight\Renderer\HtmlRenderer());
    

2. Debugging Tips

• Inspect Tokens: Enable debug mode to see tokenized output:

  $highlighter->setDebug(true);
  $tokens = $highlighter->tokenize('<?php echo 1; ?>', 'php');
  dd($tokens);
  

• Language-Specific Issues:

  • Check the language definitions for edge cases (e.g., PHP heredoc syntax).
  • Extend a language class to override rules:

    use Tempest\Highlight\Language\PhpLanguage;
    
    class CustomPhpLanguage extends PhpLanguage {
        protected function getRules(): array {
            return array_merge(parent::getRules(), [
                // Add custom rules here
            ]);
        }
    }
    $highlighter->registerLanguage(new CustomPhpLanguage());
    

• Performance Bottlenecks:

  • Profile with phpbench (included in the package). Common optimizations:
    • Disable gutter for non-web contexts.
    • Cache parsed results in production.

3. Configuration Quirks

• Theme Variables:

  • Themes support variables (e.g., $background). Use setThemeVariables to override:

    $highlighter->setThemeVariables('catppuccin', [
        'background' => '#1e1e2e',
    ]);
    

• Line Numbers:

  • Gutter (line numbers) is enabled by default. Disable with:

    $highlighter->setGutter(false);
    

  • Customize gutter style via theme variables:

    $highlighter->setThemeVariables('default', [
        'gutter' => [
            'background' => '#f0f0f0',
            'color' => '#333',
        ],
    ]);
    

• Fallback Behavior:

  • If a language isn’t found, the package falls back to text. Set a custom fallback:

    $highlighter->setFallbackLanguage('markdown');
    

4. Extension Points

• Add a New Language:

  1. Create a class extending Tempest\Highlight\Language\AbstractLanguage.
  2. Define token rules in getRules().
  3. Register it:

     $highlighter->registerLanguage(new CustomLanguage());
     

• Custom Renderers:

  • Extend AbstractRenderer and implement renderToken(). Example for ANSI output:

    class AnsiRenderer extends AbstractRenderer {
        public function renderToken(Token $token): string {
            $styles = $this->getStyle($token->getType());
            return "\033[{$styles}m{$token->getText()}\033[0m";
        }
    }
    

• Hooks for Post-Processing:

  • Use the postProcess method to modify output:

    $highlighter->setPostProcess(function ($html) {
        return str_replace('<span class="keyword">', '<strong>', $html);
    });
    

5. Laravel-Specific Tips

• Service Provider Binding: Bind the highlighter to the container for dependency injection:

  // app/Providers/AppServiceProvider.php
  public function register()
  {
      $this->app->singleton(Highlighter::class, function ($app) {
          return new Highlighter();
      });
  }
  

  Usage in controllers:

  use Tempest\Highlight\Highlighter;
  
  public function showCode(Highlighter $highlighter) {
      return $highlighter->parse($request->code, $request->language);
  }
  

• Caching Highlighted Code: Use Laravel’s cache to store highlighted snippets:

  $cacheKey = "highlighted_{$language}_{md5($code)}";
  $highlighted = cache()->remember($cacheKey, now