Pygments Elephant Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cypresslab/pygments-elephant-bundle:0.*
   

   Add the bundle to config/bundles.php in Symfony:

   return [
       // ...
       Matteosister\PygmentsElephantBundle\MatteosisterPygmentsElephantBundle::class => ['all' => true],
   ];
   

2. Verify Pygments CLI Availability Ensure pygmentize is installed and accessible in your system PATH. Test with:

   pygmentize -V
   

3. First Use Case: Syntax Highlighting in Twig Inject the service in a Twig template or controller:

   {{ highlight('php', '<?php echo "Hello"; ?>') }}
   

   Or via controller:

   $highlightedCode = $this->get('pygments.elephant')->highlight('php', '<?php echo "Hello"; ?>');
   

Implementation Patterns

Common Workflows

1. Dynamic Syntax Highlighting Use in Twig templates for code blocks:

   {% for language, code in codeSnippets %}
       <div class="code-block">
           {{ highlight(language, code) }}
       </div>
   {% endfor %}
   

2. Service Integration Inject the PygmentsElephant service in controllers/services:

   public function __construct(PygmentsElephant $pygments) {
       $this->pygments = $pygments;
   }
   
   public function showCodeExample() {
       $highlighted = $this->pygments->highlight('javascript', 'console.log("Hi");');
       return $this->render('example.html.twig', ['code' => $highlighted]);
   }
   

3. Custom Lexers/Styles Override default lexers/styles via configuration (see Gotchas for details):

   # config/packages/matteosister_pygments_elephant.yaml
   matteosister_pygments_elephant:
       lexers_path: '%kernel.project_dir%/config/lexers'
       styles_path: '%kernel.project_dir%/config/styles'
   

4. Batch Processing Process multiple code snippets in a loop:

   $snippets = [
       ['php', '<?php echo "A"; ?>'],
       ['js', 'console.log("B");'],
   ];
   $highlighted = array_map(
       fn($snippet) => $this->pygments->highlight($snippet[0], $snippet[1]),
       $snippets
   );
   

Gotchas and Tips

Pitfalls

1. Missing pygmentize CLI

   • Error: CommandNotFoundException if pygmentize isn’t installed.
   • Fix: Install via easy_install pygments (Linux) or pip install pygments (cross-platform). On macOS, use brew install pygments.

2. Lexer/Style Paths

   • Error: Custom lexers/styles not loading.
   • Fix: Ensure paths in config/packages/matteosister_pygments_elephant.yaml are correct and files are valid Pygments lexers/styles (.py files).

3. Output Formatting

   • Gotcha: Raw HTML output may break if not escaped in Twig.
   • Fix: Use Twig’s |raw filter sparingly or escape with |striptags if needed:

     {{ highlight('html', '<div>')|raw }}
     

4. Performance

   • Gotcha: CLI calls add overhead for large codebases.
   • Tip: Cache highlighted snippets in a service:

     $cache = $this->get('cache.app');
     $cacheKey = md5($language . $code);
     $highlighted = $cache->get($cacheKey, function() use ($language, $code) {
         return $this->pygments->highlight($language, $code);
     });
     

Debugging

• Check CLI Output: Run pygmentize -L to list available lexers.
• Log Errors: Wrap service calls in try-catch:

  try {
      $highlighted = $this->pygments->highlight('unknown', 'code');
  } catch (\Exception $e) {
      $this->addFlash('error', 'Pygments error: ' . $e->getMessage());
  }
  

Extension Points

1. Custom Lexers Place .py lexer files in config/lexers and update the config path.

2. Pre/Post-Processing Extend the bundle by overriding the PygmentsElephant service:

   services:
       app.pygments.elephant:
           class: App\Service\CustomPygmentsElephant
           decorates: pygments.elephant
           arguments: ['@app.pygments.elephant.inner']
   

3. Symfony Flex Integration For newer Symfony apps, manually register the bundle in config/bundles.php (no autoloading via Flex).