Parsedown Extra Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require erusev/parsedown-extra
   

   Register the service provider in config/app.php:

   'providers' => [
       // ...
       Erusev\ParsedownExtra\ParsedownExtraServiceProvider::class,
   ],
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Erusev\ParsedownExtra\ParsedownExtraServiceProvider"
   

2. Basic Usage Inject the ParsedownExtra class into a controller or service:

   use Erusev\ParsedownExtra\ParsedownExtra;
   
   public function convertMarkdown(ParsedownExtra $parsedown)
   {
       $markdown = "# Hello, **World!**\n\n- List item";
       $html = $parsedown->text($markdown);
       return response()->html($html);
   }
   

3. First Use Case Convert markdown in a blog post or comment system:

   $parsedown = app(ParsedownExtra::class);
   $content = $parsedown->text($userInputMarkdown);
   

Implementation Patterns

Common Workflows

1. Dynamic Markdown Processing Use dependency injection to process markdown in controllers, middleware, or services:

   public function __construct(ParsedownExtra $parsedown) {
       $this->parsedown = $parsedown;
   }
   

2. Reusable Parsing Logic Create a helper trait or service:

   trait MarkdownConverter {
       public function parse(string $markdown): string {
           return app(ParsedownExtra::class)->text($markdown);
       }
   }
   

3. Integration with Blade Extend Blade directives for markdown support:

   Blade::directive('markdown', function ($expression) {
       return "<?php echo app(\\Erusev\\ParsedownExtra\\ParsedownExtra::class)->text({$expression}); ?>";
   });
   

   Usage:

   @markdown($post->content)
   

4. API Responses Return parsed markdown as HTML in API responses:

   return response()->json([
       'content' => $parsedown->text($request->markdown),
   ]);
   

5. Form Request Validation Use ParsedownExtra in form requests to sanitize markdown before processing:

   public function passes($attribute, $value) {
       $this->parsedown = app(ParsedownExtra::class);
       $this->sanitized = $this->parsedown->text($value);
       return true;
   }
   

Gotchas and Tips

Pitfalls

1. XSS Vulnerabilities

   • Parsedown Extra does not automatically sanitize HTML. Use htmlspecialchars() or a package like htmlpurifier if user input is untrusted:

     $safeHtml = htmlspecialchars($parsedown->text($userInput), ENT_QUOTES, 'UTF-8');
     

2. Performance with Large Text

   • Parsing extensive markdown (e.g., documentation) may impact performance. Cache results:

     $cacheKey = 'markdown_'.$post->id;
     $html = Cache::remember($cacheKey, now()->addHours(1), function() use ($parsedown, $post) {
         return $parsedown->text($post->content);
     });
     

3. Config Overrides

   • Custom extensions or settings may conflict with defaults. Review config/parsedown-extra.php:

     'extensions' => [
         'hardBreak', // Enable hard line breaks
     ],
     

4. Nested Markdown in HTML

   • If markdown is embedded in HTML (e.g., <div>{{ markdown }}</div>), ensure the parser doesn’t reprocess it:

     $parsedown->setSafeMode(true); // Disable markdown parsing in HTML blocks
     

Debugging Tips

1. Inspect Extensions Check enabled extensions via:

   $extensions = $parsedown->getExtensions();
   dd($extensions);
   

2. Log Parsed Output Debug unexpected HTML by logging the parsed result:

   \Log::debug('Parsed Markdown:', ['html' => $parsedown->text($markdown)]);
   

3. Test Edge Cases Validate with:

   • Tables (| Syntax |)
   • Definition lists (term)
   • Footnotes ([^note])
   • Abbreviations (*[HTML]: HyperText Markup Language)

Extension Points

1. Custom Extensions Register additional extensions:

   $parsedown->registerExtension(new \Erusev\ParsedownExtra\Extension\MyCustomExtension());
   

2. Override Defaults Extend the base ParsedownExtra class:

   class CustomParsedownExtra extends ParsedownExtra {
       public function __construct() {
           parent::__construct();
           $this->setBreaksEnabled(true);
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(ParsedownExtra::class, function ($app) {
       return new CustomParsedownExtra();
   });
   

3. Laravel Events Trigger events before/after parsing (e.g., for analytics or logging):

   event(new MarkdownParsed($markdown, $html));