Creole Full Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avtonom/creole-full-bundle "~1.1"
   

   Ensure softark/creole is also installed (handled automatically via dependency).

2. Register the Bundle: Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony <4):

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

3. First Use Case: Parse Creole/Wiki syntax in a controller or template:

   use Avtonom\CreoleBundle\Parser\CreoleParser;
   
   class WikiController extends AbstractController {
       public function renderWiki(CreoleParser $parser) {
           $markdown = "**Bold text** and //italic//";
           $html = $parser->parse($markdown);
           return $this->render('wiki/show.html.twig', ['content' => $html]);
       }
   }
   

   Or in Twig:

   {{ creole(content) }}
   

Implementation Patterns

Core Workflows

1. Parsing in Controllers/Commands: Inject CreoleParser service to transform Creole/Wiki syntax to HTML:

   public function processWikiContent(CreoleParser $parser, string $rawContent) {
       $html = $parser->parse($rawContent);
       // Store or return $html
   }
   

2. Dynamic Content Rendering: Use Twig extensions for seamless integration:

   {% set parsedContent = creole('== Heading ==\n* List item') %}
   {{ parsedContent|raw }}  {# Render raw HTML #}
   

3. Configuration Overrides: Customize parser behavior via config/packages/avtonom_creole.yaml:

   avtonom_creole:
       allowed_tags: ['p', 'strong', 'em', 'ul', 'ol']  # Whitelist tags
       auto_link: true
   

4. Event-Driven Processing: Listen to avtonom_creole.parse events to pre/post-process content:

   // src/EventListener/WikiListener.php
   public function onParse(WikiEvent $event) {
       $event->setContent(str_replace('{{var}}', $this->getVar(), $event->getContent()));
   }
   

Integration Tips

• Database Storage: Store Creole/Wiki syntax in DB (e.g., content column) and parse on-the-fly.
• API Responses: Use CreoleParser to render dynamic API responses with formatted text.
• Form Handling: Parse user-submitted Creole/Wiki in forms before saving to DB.

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch:

   • Bundle targets Symfony 2.3+. For Symfony 4/5, ensure compatibility by checking softark/creole updates.
   • Fix: Use softark/creole:^1.0 for newer Symfony versions.

2. XSS Risks:

   • By default, all HTML tags are allowed. Restrict via config:

     avtonom_creole:
         allowed_tags: ['p', 'em', 'strong']  # Explicit whitelist
     

3. Caching Issues:

   • Parsed HTML may not cache automatically. Implement a decorator for caching:

     $parser->parse($content);  // Re-parses every time
     

4. Twig Auto-escaping:

   • Use |raw filter to render HTML safely:

     {{ creole(content)|raw }}
     

Debugging

• Parser Errors: Enable debug mode to log Creole syntax issues:

  avtonom_creole:
      debug: true
  

• Output Mismatches: Compare raw Creole input with parsed HTML to identify missing rules.

Extension Points

1. Custom Rules: Extend softark/creole by creating a subclass:

   use Softark\Creole\Parser;
   
   class CustomParser extends Parser {
       protected function initialize() {
           parent::initialize();
           $this->addRule('{{var}}', function($match) { return 'Dynamic Value'; });
       }
   }
   

   Register as a service:

   services:
       app.custom_creole_parser:
           class: App\Parser\CustomParser
           tags: ['avtonom_creole.parser']
   

2. Pre/Post-Processing: Use events to modify content before/after parsing:

   // src/EventSubscriber/WikiSubscriber.php
   public static function getSubscribedEvents() {
       return [
           KernelEvents::VIEW => ['onKernelView', 20],
       ];
   }
   

3. Performance: For high-traffic sites, cache parsed results:

   $cacheKey = md5($content);
   $html = $cache->get($cacheKey, function() use ($parser, $content) {
       return $parser->parse($content);
   });