Markdown Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cdaguerre/markdown-bundle
   

   Add to config/app.php under providers:

   Cdaguerre\MarkdownBundle\MarkdownServiceProvider::class,
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Cdaguerre\MarkdownBundle\MarkdownServiceProvider"
   

2. Basic Usage: Inject the Markdown facade or service into a controller/blade view:

   use Cdaguerre\MarkdownBundle\Facades\Markdown;
   
   $html = Markdown::parse('# Hello, Markdown!');
   

3. First Use Case: Convert markdown in a blog post model to HTML before displaying:

   public function show(Post $post) {
       $post->content_html = Markdown::parse($post->content);
       return view('posts.show', compact('post'));
   }
   

Implementation Patterns

Common Workflows

1. Blade Directives: Use @markdown directive in views:

   @markdown($post->content)
   

   (Check if the package supports this—if not, create a custom directive.)

2. Model Observers: Automatically convert markdown on save:

   class PostObserver {
       public function saved(Post $post) {
           $post->content_html = Markdown::parse($post->content);
           $post->save();
       }
   }
   

3. Form Request Validation: Validate markdown syntax before processing:

   use Cdaguerre\MarkdownBundle\Rules\ValidMarkdown;
   
   public function rules() {
       return [
           'content' => ['required', new ValidMarkdown],
       ];
   }
   

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

   return response()->json([
       'content' => Markdown::parse($request->content),
   ]);
   

Integration Tips

• Laravel Mix/Webpack: Process markdown client-side for live previews (e.g., using marked.js).
• Caching: Cache parsed HTML to avoid reprocessing:

  $cacheKey = 'post_'.$post->id.'_html';
  $html = Cache::remember($cacheKey, now()->addHours(1), function() use ($post) {
      return Markdown::parse($post->content);
  });
  

• Custom Parsers: Extend the bundle to support additional markdown features (e.g., tables, custom syntax).

Gotchas and Tips

Pitfalls

1. No Built-in Facade: The package may not include a facade by default. Create one if needed:

   php artisan make:facade Markdown
   

   Then update the facade class to point to the service.

2. Configuration Overrides: Ensure config/markdown.php is published and configured correctly. Defaults might not match your needs (e.g., parser engine like Parsedown vs. CommonMark).

3. Performance: Parsing large markdown strings repeatedly can be slow. Cache results aggressively or use a queue for async processing.

4. Security: Sanitize HTML output if markdown includes user-generated content to prevent XSS:

   use Purifier;
   $cleanHtml = Purifier::cleanHtml(Markdown::parse($input));
   

Debugging

• Parser Errors: Check if the underlying parser (e.g., Parsedown) throws exceptions. Wrap calls in a try-catch:

  try {
      $html = Markdown::parse($markdown);
  } catch (\Exception $e) {
      Log::error("Markdown parse error: " . $e->getMessage());
      $html = "<p>Error rendering markdown.</p>";
  }
  

• Configuration Issues: Verify the markdown.parser setting in config/markdown.php matches an available parser class.

Extension Points

1. Custom Parsers: Register a custom parser by binding it in the service provider:

   $this->app->bind('markdown.parser', function() {
       return new \Your\Custom\MarkdownParser();
   });
   

2. Filters/Plugins: Extend the parser with custom plugins (e.g., for syntax highlighting):

   $parser = new \Parsedown();
   $parser->setBreaksEnabled(true);
   Markdown::setParser($parser);
   

3. Event Listeners: Listen for markdown parsing events (if the package supports them) to log or modify output:

   Markdown::parse($input)->then(function($html) {
       // Post-process HTML
   });