Laravel Useful Commonmark Extension Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require johnnyhuy/laravel-useful-commonmark-extension
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Johnnyhuy\CommonMarkExtension\CommonMarkExtensionServiceProvider::class,
   ],
   

2. Publish Config (optional):

   php artisan vendor:publish --provider="Johnnyhuy\CommonMarkExtension\CommonMarkExtensionServiceProvider"
   

   This creates config/commonmark-extensions.php with default settings.

3. First Use Case: Parse markdown with extensions in a controller:

   use League\CommonMark\CommonMarkConverter;
   use League\CommonMark\Environment;
   
   $environment = new Environment();
   $environment->addExtension(new \Johnnyhuy\CommonMarkExtension\GistExtension());
   $converter = new CommonMarkConverter($environment);
   
   $markdown = "# Hello **World**\n\n[![Gist](https://gist.github.com/...)]";
   echo $converter->convert($markdown);
   

Implementation Patterns

Core Workflows

1. Dynamic Extension Loading: Register extensions in config/commonmark-extensions.php:

   'extensions' => [
       \Johnnyhuy\CommonMarkExtension\GistExtension::class,
       \Johnnyhuy\CommonMarkExtension\CodepenExtension::class,
   ],
   

   Use the helper in your code:

   $converter = app(\League\CommonMark\CommonMarkConverter::class);
   

2. Blade Integration: Create a Blade directive for reusable markdown parsing:

   // In a service provider
   Blade::directive('markdown', function ($expression) {
       $converter = app(\League\CommonMark\CommonMarkConverter::class);
       return "<?php echo {$converter->convert({$expression})}; ?>";
   });
   

   Usage in Blade:

   @markdown($post->content)
   

3. API Responses: Parse markdown in API responses:

   return response()->json([
       'content' => app(\League\CommonMark\CommonMarkConverter::class)->convert($request->markdown),
   ]);
   

4. Form Handling: Sanitize markdown input before processing:

   $cleanMarkdown = app(\League\CommonMark\CommonMarkConverter::class)->convert($request->raw_markdown);
   

Integration Tips

• Laravel Markdown Packages: Works seamlessly with spatie/laravel-markdown or root/str.
• Frontend Frameworks: Use the parsed HTML in Vue/React components via props or API responses.
• Caching: Cache parsed markdown if content rarely changes:

  $cacheKey = 'markdown_'.$post->id;
  $html = Cache::remember($cacheKey, now()->addHours(1), function() use ($post) {
      return app(\League\CommonMark\CommonMarkConverter::class)->convert($post->content);
  });
  

Gotchas and Tips

Common Pitfalls

1. Extension Conflicts:

   • If extensions break rendering, disable them one-by-one in config/commonmark-extensions.php to isolate the issue.
   • Some extensions (e.g., Gist) require valid URLs; validate input to avoid errors.

2. HTML Sanitization:

   • Extensions may inject unsafe HTML. Use HTMLPurifier or spatie/laravel-html to sanitize output:

     $purifier = app(\HTMLPurifier::class);
     $safeHtml = $purifier->purify($converter->convert($markdown));
     

3. Deprecated Laravel Versions:

   • The package supports Laravel 5-7. For newer versions, manually adapt the service provider or fork the package.

4. Missing Assets:

   • Extensions like Codepen/Gist rely on external CDNs. Ensure your layout includes:

     <script src="https://gist.github.com/..."></script>
     <script src="https://codepen.io/..."></script>
     

Debugging Tips

• Log Parsed Output:

  \Log::debug('Markdown parsed:', [
      'input' => $markdown,
      'output' => $converter->convert($markdown),
  ]);
  

• Inspect Extensions: Use dd($environment->getExtensions()) to list loaded extensions and debug their behavior.

Extension-Specific Quirks

Performance

• Disable Unused Extensions: Reduces parsing overhead.
• Lazy-Loading: Load extensions only when needed (e.g., in a service class):

  class MarkdownService {
      protected $extensions = [];
  
      public function addExtension($extension) {
          $this->extensions[] = $extension;
      }
  
      public function convert($markdown) {
          $environment = new Environment();
          foreach ($this->extensions as $extension) {
              $environment->addExtension($extension);
          }
          return (new CommonMarkConverter($environment))->convert($markdown);
      }
  }
  

Customization

• Extend Existing Extensions: Override methods in a subclass (e.g., for YouTube):

  class CustomYouTubeExtension extends \Johnnyhuy\CommonMarkExtension\YouTubeExtension {
      protected function getEmbedUrl($url) {
          // Custom logic
          return parent::getEmbedUrl($url);
      }
  }
  

• Add New Extensions: Follow the package’s structure (e.g., GistExtension) to create your own. Register it in the config.