Creole Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require avtonom/creole-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Avtonom\CreoleBundle\AvtonomCreoleBundle::class => ['all' => true],
   ];
   

2. First Use Case Parse and render Creole markup in a Twig template:

   {{ creole('== Headline ==\nThis is *bold* and //italic// text.')|raw }}
   

   Requires Twig integration (included by default).

Where to Look First

• Parser: Avtonom\CreoleBundle\Parser\Parser – Core logic for converting Creole to a tree structure.
• Renderers:
  • Avtonom\CreoleBundle\Renderer\XhtmlRenderer (default, outputs HTML).
  • Avtonom\CreoleBundle\Renderer\LatexRenderer (experimental, outputs LaTeX).
• Twig Extension: Avtonom\CreoleBundle\Twig\CreoleExtension – Bridge for Twig templates.
• Tests: /tests/ – Reference implementations and edge cases.

Implementation Patterns

Core Workflow

1. Parse Markup

   $parser = $container->get('avtonom_creole.parser');
   $tree = $parser->parse('== Headline ==\n* List item');
   

   • Returns a Creole\Tree\Node object (serializable via Serializable).

2. Render Output

   $renderer = $container->get('avtonom_creole.xhtml_renderer');
   $html = $renderer->render($tree);
   

   • Supports caching by serializing the tree (e.g., Doctrine Object field).

3. Twig Integration

   {% set creoleContent = creole('== Headline ==') %}
   <div>{{ creoleContent|raw }}</div>
   

   • Use |raw to avoid HTML escaping.

Advanced Patterns

• Custom Renderers Extend Avtonom\CreoleBundle\Renderer\AbstractRenderer:

  class MarkdownRenderer extends AbstractRenderer {
      public function renderNode(Node $node) { ... }
  }
  

  Register as a service:

  services:
      app.creole.markdown_renderer:
          class: App\Renderer\MarkdownRenderer
          tags: ['avtonom_creole.renderer']
  

• Caching Parsed Trees Store serialized trees in Doctrine:

  $serialized = serialize($tree);
  $entity->setCreoleContent($serialized); // Doctrine `Object` field
  

  Retrieve and render later:

  $tree = unserialize($entity->getCreoleContent());
  $renderer->render($tree);
  

• Validation Use the parser’s exception handling:

  try {
      $tree = $parser->parse($markup);
  } catch (\RuntimeException $e) {
      // Handle invalid Creole
  }
  

Gotchas and Tips

Pitfalls

1. Unmaintained Status

   • No active maintenance; fork if critical bugs arise.
   • Missing features (images, placeholders, LaTeX tables/italics/bold).

2. LaTeX Renderer Limitations

   • Tables, italics, and bold spans are disabled due to pdflatex issues.
   • Test LaTeX output thoroughly before production use.

3. Serialization Caveats

   • Trees are Serializable, but ensure the Doctrine Object field is large enough.
   • Avoid circular references in custom renderers.

4. Twig Auto-escaping Always use |raw in Twig to prevent HTML escaping:

   {{ creole('*bold*')|raw }}
   

Debugging Tips

1. Inspect Tree Structure Dump the parsed tree to verify nodes:

   var_dump($tree->getChildren());
   

   • Useful for debugging custom renderers.

2. Validate Markup Test with the Creole 1.0 spec. Example edge cases:

   // Nested lists
   * Item 1
   ** Subitem
   * Item 2
   
   // Mixed formatting
   == Heading with //italic// and *bold* ==
   

3. Performance

   • Cache parsed trees aggressively (e.g., Redis or Doctrine).
   • Avoid re-parsing static content on every request.

Extension Points

1. Add New Markup Rules Extend the lexer (Avtonom\CreoleBundle\Lexer\Lexer) or parser to support custom syntax.

2. Integrate with Forms Use the parser in Symfony forms for rich-text input:

   $builder->add('content', TextType::class, [
       'attr' => ['class' => 'creole-editor'],
   ]);
   

   • Pair with a client-side Creole editor (e.g., Creole.js).

3. API Endpoints Expose parsing/rendering via a controller:

   $tree = $parser->parse($request->request->get('markup'));
   return new Response($renderer->render($tree));