Markup Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require anh/markup-bundle
   

   Add to config/app.php under providers:

   Anh\MarkupBundle\MarkupBundle::class,
   

   Publish config (if available) with:

   php artisan vendor:publish --provider="Anh\MarkupBundle\MarkupBundle"
   

2. First Use Case Register a markup handler in a service provider (e.g., AppServiceProvider):

   use Anh\MarkupBundle\MarkupBundle;
   
   public function boot()
   {
       MarkupBundle::registerHandler('html', new \Anh\MarkupBundle\Handlers\HtmlHandler());
   }
   

   Use the markup service in a controller:

   use Anh\MarkupBundle\MarkupService;
   
   public function index(MarkupService $markup)
   {
       $html = $markup->parse('html', '<p>Hello, <strong>Markup!</strong></p>');
       return response()->json(['content' => $html]);
   }
   

Implementation Patterns

Core Workflows

1. Handler Registration Extend \Anh\MarkupBundle\Handlers\AbstractHandler for custom formats (e.g., Markdown, BBCode):

   class MarkdownHandler extends AbstractHandler
   {
       public function parse($input): string
       {
           return \Parsedown::instance()->text($input);
       }
   }
   

   Register via:

   MarkupBundle::registerHandler('markdown', new MarkdownHandler());
   

2. Service Integration Inject MarkupService into controllers, services, or Blade directives:

   // Blade directive example
   Blade::directive('markup', function ($expression) {
       return "<?php echo app('markup')->parse('html', {$expression}); ?>";
   });
   

   Usage in Blade:

   @markup('<b>Dynamic HTML</b>')
   

3. Middleware for Sanitization Use middleware to parse markup before rendering:

   public function handle($request, Closure $next)
   {
       $request->merge([
           'sanitized_content' => app('markup')->parse('html', $request->content)
       ]);
       return $next($request);
   }
   

Advanced Patterns

• Caching Parsed Output Decorate MarkupService to cache results:

  class CachedMarkupService implements \Anh\MarkupBundle\Contracts\MarkupService
  {
      public function parse(string $format, string $input): string
      {
          $cacheKey = "markup_{$format}_{md5($input)}";
          return cache()->remember($cacheKey, now()->addHours(1), function() use ($format, $input) {
              return app('anh.markup')->parse($format, $input);
          });
      }
  }
  

• Event-Driven Extensions Dispatch events before/after parsing (if the bundle supports it):

  event(new \Anh\MarkupBundle\Events\MarkupParsing($format, $input));
  

Gotchas and Tips

Common Pitfalls

1. Handler Not Found

   • Error: Undefined handler for format 'xyz'.
   • Fix: Ensure the handler is registered before first use (e.g., in boot()).
   • Debug: Check registered handlers with:

     dd(app('anh.markup')->getHandlers());
     

2. XSS Vulnerabilities

   • Risk: HTML handlers may not sanitize input by default.
   • Mitigation: Use a sanitizer like HTMLPurifier in the handler:

     $purifier = new \HTMLPurifier();
     return $purifier->purify($input);
     

3. Performance Overhead

   • Issue: Parsing large inputs repeatedly (e.g., in loops).
   • Solution: Cache parsed results or lazy-load handlers.

Configuration Quirks

• No Default Config: The bundle may lack a published config file. Check for environment variables or hardcoded defaults in the source.
• Handler Priority: If multiple handlers support a format, the last registered one wins. Explicitly unregister conflicting handlers if needed:

  MarkupBundle::unregisterHandler('html');
  

Extension Points

1. Custom Formats

   • Extend AbstractHandler and implement parse() for new formats (e.g., LaTeX, SVG).
   • Example:

     class LatexHandler extends AbstractHandler
     {
         public function parse($input): string
         {
             return \Dompdf\Dompdf::loadHtml($input)->render();
         }
     }
     

2. Service Binding

   • Override the default service binding in AppServiceProvider:

     $this->app->bind(\Anh\MarkupBundle\Contracts\MarkupService::class, CustomMarkupService::class);
     

3. Testing

   • Mock MarkupService in tests:

     $mock = Mockery::mock(\Anh\MarkupBundle\Contracts\MarkupService::class);
     $mock->shouldReceive('parse')->andReturn('<p>Mocked</p>');
     $this->app->instance(\Anh\MarkupBundle\Contracts\MarkupService::class, $mock);
     

Debugging Tips

• Log Handler Calls: Add logging in AbstractHandler:

  public function parse($input): string
  {
      \Log::debug("Parsing {$this->getFormat()} with input: " . substr($input, 0, 50));
      return $this->doParse($input);
  }
  

• Validate Input: Sanitize or validate input before parsing to avoid edge cases (e.g., malformed XML).