Highlight Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require carteni/highlight-bundle
   

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       Carteni\HighlightBundle\CarteniHighlightBundle::class => ['all' => true],
   ];
   

3. Publish Configuration (optional):

   php bin/console carteni:highlight:install
   

   This generates config/packages/carteni_highlight.yaml with default settings.

4. First Use Case: Use the highlight Twig filter to syntax-highlight code snippets:

   {{ codeSnippet|highlight('php') }}
   

   Outputs HTML-wrapped, syntax-highlighted code.

Where to Look First

• Twig Integration: Check Resources/views/HighlightBundle/default.html.twig for default templates.
• Configuration: Review config/packages/carteni_highlight.yaml for customization options (e.g., themes, languages).
• CLI Commands: Run php bin/console list carteni to explore available commands (e.g., highlight:install).

Implementation Patterns

Core Workflow

1. Highlighting Code in Twig:

   {% set code = '<?php echo "Hello"; ?>' %}
   {{ code|highlight('php', { 'theme': 'github' }) }}
   

   • Parameters:
     • language: Target language (e.g., php, javascript).
     • options: Override defaults (e.g., theme, tabSize).

2. Dynamic Language Detection: Use the guessLanguage filter to auto-detect syntax:

   {{ codeSnippet|highlight(codeSnippet|guessLanguage) }}
   

3. Custom Themes:

   • Place theme CSS files in public/css/highlight/ (e.g., github.css).
   • Reference in config:

     carteni_highlight:
         themes:
             github: '%kernel.project_dir%/public/css/highlight/github.css'
     

Integration Tips

• Laravel Blade: Create a custom directive or use Twig via Blade::directive():

  Blade::directive('highlight', function ($expression) {
      return "<?php echo highlight($expression); ?>";
  });
  

  Usage:

  @highlight($codeSnippet, 'php')
  

• API Responses: Highlight code in JSON responses:

  return response()->json([
      'code' => highlight($request->code, 'python'),
  ]);
  

• Caching: Cache highlighted output for static pages:

  {% cache 'highlight_'.codeSnippet.md5 %}
      {{ codeSnippet|highlight('ruby') }}
  {% endcache %}
  

Gotchas and Tips

Pitfalls

1. Outdated Dependencies:

   • The bundle relies on scrivo/highlight.php (last updated 2017). Test thoroughly for edge cases (e.g., rare languages like coffeescript).
   • Workaround: Fork and update the underlying library if needed.

2. Theme Loading:

   • Custom themes must be manually placed in public/css/highlight/. The bundle does not auto-download themes.
   • Fix: Use a post-install script or composer post-install-cmd to fetch themes:

     composer require --dev carteni/highlight-themes
     

3. Twig Auto-Reloading: Clear Twig cache after adding new themes:

   php bin/console cache:clear
   

4. Language Support:

   • Not all highlight.js languages are supported. Check vendor/scrivo/highlight.php/lib/languages/ for available options.
   • Tip: Extend by adding custom language files to config/packages/carteni_highlight.yaml:

     carteni_highlight:
         languages:
             custom: '%kernel.project_dir%/path/to/custom.lang'
     

Debugging

1. Invalid HTML Output:

   • Ensure the highlight Twig filter is properly closed in templates. Use {{- ... -}} to trim whitespace if needed.

2. Missing Styles:

   • Verify theme paths in config and that CSS files are accessible via public/ URL.
   • Debug: Inspect browser dev tools for 404 errors on theme CSS.

3. Performance:

   • Highlighting large code blocks can be slow. Pre-highlight and store in the database if possible:

     $highlighted = highlight($code, 'javascript');
     $model->saveHighlightedCode($highlighted);
     

Extension Points

1. Custom Highlighter Service: Bind a custom service to override the default highlighter:

   # config/services.yaml
   services:
       Carteni\HighlightBundle\HighlighterInterface: '@app.custom_highlighter'
   

2. Event Listeners: Trigger actions before/after highlighting via Symfony events (requires extending the bundle):

   // Example: Log highlighted code
   $eventDispatcher->addListener(
       Carteni\HighlightBundle\Event\HighlightEvent::class,
       function ($event) {
           \Log::debug('Highlighted code:', ['language' => $event->getLanguage()]);
       }
   );
   

3. Language Auto-Loading: Dynamically load languages from a directory:

   // In a bundle compiler pass
   $definition->addMethodCall('loadLanguagesFromDir', ['%kernel.project_dir%/config/languages']);