Ciconia Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kzykhys/ciconia
   

   Add to composer.json if not using autoloading:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Ciconia\\": "vendor/kzykhys/ciconia/src/"
       }
   }
   

   Run composer dump-autoload.

2. First Use Case Parse a simple Markdown string:

   use Ciconia\Parser;
   
   $parser = new Parser();
   $html = $parser->parse('# Hello World!');
   echo $html; // Outputs: <h1>Hello World!</h1>
   

3. Where to Look First

   • Source Code (for customization).
   • Tests (for edge cases and examples).
   • README.md (basic syntax support).

Implementation Patterns

Core Workflow

1. Parsing Markdown

   $parser = new Parser();
   $html = $parser->parse($markdownString);
   

   • Supports standard Markdown (headings, lists, links, emphasis, etc.).
   • Extendable for custom syntax via Ciconia\Parser\Extension.

2. Integration with Laravel

   • Service Provider: Register the parser as a singleton:

     $this->app->singleton('ciconia.parser', function () {
         return new Parser();
     });
     

   • Helper Function: Add to app/Helpers/markdown.php:

     if (!function_exists('markdown')) {
         function markdown($text) {
             return app('ciconia.parser')->parse($text);
         }
     }
     

     Use in Blade:

     {!! markdown($post->content) !!}
     

3. Batch Processing

   • Parse multiple Markdown files (e.g., from storage/markdown/):

     $files = Storage::files('markdown');
     foreach ($files as $file) {
         $markdown = Storage::get($file);
         $html = $parser->parse($markdown);
         Storage::put('public/html/' . basename($file, '.md') . '.html', $html);
     }
     

4. Custom Extensions

   • Add support for Laravel-specific syntax (e.g., @user mentions):

     $parser->addExtension(new class extends Extension {
         public function parse($text) {
             return preg_replace('/@(\w+)/', '<a href="/users/$1">@$1</a>', $text);
         }
     });
     

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last release in 2014; may not support modern PHP (tested on PHP 5.4+).
   • No active maintenance; fork or patch if critical bugs arise.

2. Limited Syntax

   • Missing advanced Markdown features (tables, footnotes, GFM extensions).
   • Workaround: Pre-process text or use a fallback parser (e.g., erusev/parsedown).

3. Performance

   • Not optimized for large-scale parsing (e.g., 1000+ articles).
   • Cache parsed HTML:

     $cacheKey = 'markdown_' . md5($markdown);
     $html = Cache::remember($cacheKey, 3600, function () use ($parser, $markdown) {
         return $parser->parse($markdown);
     });
     

4. XSS Risks

   • Always sanitize output in Blade:

     {!! htmlspecialchars(markdown($input), ENT_QUOTES, 'UTF-8') !!}
     

   • Or use |e filter:

     {!! markdown($input) | e !!}
     

Debugging

1. Enable Verbose Output

   • Extend Parser to log parsing steps:

     $parser = new Parser();
     $parser->setDebug(true); // Hypothetical; check source for actual method.
     

2. Test Edge Cases

   • Use existing tests as a reference:

     $parser->parse('*Unfinished* list'); // May not render as expected.
     

3. Fallback Parser

   • Combine with parsedown for unsupported syntax:

     use Parsedown;
     $parsedown = new Parsedown();
     $html = $parser->parse($markdown);
     $html = $parsedown->text($html); // Fallback for missing features.
     

Configuration Quirks

1. No Built-in Config

   • Directly modify Parser class or extend it for settings (e.g., hardcoded line breaks).

2. Extension Order

   • Extensions run in registration order. Critical extensions (e.g., security) should be added first.

Extension Points

1. Custom Block Parsers

   • Override Ciconia\Parser\Block\AbstractBlock for new block types (e.g., admonitions):

     class AdmonitionBlock extends AbstractBlock {
         public function parse($text) {
             return '<div class="admonition">' . $text . '</div>';
         }
     }
     

2. Inline Parsers

   • Extend Ciconia\Parser\Inline\AbstractInline for custom inline syntax (e.g., @highlight):

     $parser->addInlineExtension(new class extends AbstractInline {
         public function parse($text) {
             return preg_replace('/@highlight(.*)@highlight/', '<mark>$1</mark>', $text);
         }
     });
     

3. Pre/Post-Processing

   • Wrap the parser for additional logic:

     $parser = new Parser();
     $wrapper = new class($parser) {
         private $parser;
         public function __construct(Parser $parser) {
             $this->parser = $parser;
         }
         public function parse($text) {
             $text = $this->preProcess($text);
             $html = $this->parser->parse($text);
             return $this->postProcess($html);
         }
     };