Creole Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require softark/creole
   

   Ensure cebe/markdown (dependency) is also installed.

2. Basic Usage

   use SoftArk\Creole\CreoleParser;
   
   $parser = new CreoleParser();
   $html = $parser->parse('== Heading == Some *bold* text.');
   echo $html;
   

   Outputs:

   <h2>Heading</h2><p>Some <strong>bold</strong> text.</p>
   

3. First Use Case Parse a wiki-style document from a database or file:

   $creoleContent = File::get('path/to/wiki.page');
   $html = (new CreoleParser())->parse($creoleContent);
   return view('wiki.view', ['content' => $html]);
   

Implementation Patterns

Common Workflows

1. Laravel Blade Integration Create a custom Blade directive for inline parsing:

   // app/Providers/AppServiceProvider.php
   Blade::directive('wiki', function ($expression) {
       return "<?php echo (new \\SoftArk\\Creole\\CreoleParser())->parse({$expression}); ?>";
   });
   

   Usage:

   @wiki($wikiContent)
   

2. API Response Formatting Parse Creole in API responses:

   return response()->json([
       'title' => 'Documentation',
       'content' => (new CreoleParser())->parse($request->creole_content)
   ]);
   

3. Middleware for Wiki Pages Parse Creole before rendering wiki routes:

   // app/Http/Middleware/ParseCreole.php
   public function handle($request, Closure $next) {
       if ($request->route()->getName() === 'wiki.show') {
           $request->merge(['content' => (new CreoleParser())->parse($request->content)]);
       }
       return $next($request);
   }
   

Integration Tips

• Cache Parsed Output Store parsed HTML in the database or cache to avoid reprocessing:

  $cacheKey = 'wiki:'.$pageId;
  $html = Cache::remember($cacheKey, now()->addHours(1), function() use ($pageContent) {
      return (new CreoleParser())->parse($pageContent);
  });
  

• Extend with Custom Rules Override the parser for domain-specific syntax:

  $parser = new CreoleParser();
  $parser->addRule('//', function($match) {
      return '<div class="note">'.$match[1].'</div>';
  });
  

• Laravel File Storage Parse files from storage/app/wiki/:

  $files = Storage::files('wiki');
  $parsed = collect($files)->mapWithKeys(function ($file) {
      return [pathinfo($file, PATHINFO_FILENAME) => (new CreoleParser())->parse(Storage::get($file))];
  });
  

Gotchas and Tips

Pitfalls

1. Nested Syntax Conflicts Creole lacks strict nesting rules (e.g., == Heading == *bold* == breaks). Validate input:

   if (preg_match('/==.*==.*==/', $input)) {
       throw new \InvalidArgumentException('Invalid Creole syntax');
   }
   

2. HTML Injection Risks Always escape output if embedding in non-HTML contexts:

   $safeHtml = e((new CreoleParser())->parse($userInput));
   

3. Performance with Large Documents Avoid parsing multi-MB files in memory. Stream or chunk:

   $parser = new CreoleParser();
   $html = '';
   foreach (explode("\n", $largeContent) as $line) {
       $html .= $parser->parse($line);
   }
   

Debugging

• Enable Verbose Output Temporarily extend the parser to log unmatched patterns:

  $parser = new CreoleParser();
  $parser->setDebug(true); // Hypothetical method; inspect source for hooks
  

• Check for Missing Rules If syntax isn’t parsed, verify against Creole spec or extend the parser.

Configuration Quirks

• No Built-in Config The package is lightweight; configure via code (e.g., custom rules, output formatting).

• Output Formatting Control HTML attributes via extensions:

  $parser->setAttribute('h2', 'class', 'wiki-heading');
  

Extension Points

1. Custom Syntax Highlighting Hook into the parser’s parse() method to inject CSS classes:

$parser->addRule('{{', function($match) { return ''.$match[1].''; });

2. **Laravel Service Provider**
 Bind the parser as a singleton for dependency injection:
 ```php
 // app/Providers/AppServiceProvider.php
 $this->app->singleton(CreoleParser::class, function () {
     return new CreoleParser();
 });

3. Database Storage Store parsed HTML alongside raw Creole for performance:

   // Migration
   Schema::table('wiki_pages', function (Blueprint $table) {
       $table->text('parsed_html')->nullable();
   });