Quill Delta Parser Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require nadar/quill-delta-parser:^3.7.0
   

   Add to composer.json if using a monorepo or custom package management.

2. Basic Usage (Updated for Font Size)

   use Nadar\QuillDeltaParser\Parser;
   
   $delta = [
       ['insert', 'Hello '],
       ['insert', 'World', {'bold': true, 'font': {'size': '24px'}}],
   ];
   
   $parser = new Parser();
   $html = $parser->parse($delta);
   // Output: <p>Hello <span style="font-size: 24px;"><strong>World</strong></span></p>
   

3. First Use Case Parse raw Quill Delta JSON (from API or frontend) into sanitized HTML for:

   • Storing in a database ($model->content = $html)
   • Displaying in Blade templates ({!! $html !!})

Implementation Patterns

Core Workflows

1. Frontend ↔ Backend Sync

   // Frontend (Quill.js with font-size support)
   const delta = quill.getContents();
   // Send to Laravel via API
   

   // Backend (Laravel Controller)
   $delta = json_decode(request('delta'), true);
   $html = (new Parser())->parse($delta);
   

2. Database Storage

   // Migration
   Schema::create('posts', function (Blueprint $table) {
       $table->id();
       $table->text('content_html'); // Store parsed HTML
       $table->json('content_delta')->nullable(); // Optional: Store raw delta
   });
   

3. Blade Rendering

   <div class="quill-editor">
       {!! $post->content_html !!}
   </div>
   

Advanced Patterns

1. Font Size Customization

   $parser = new Parser();
   $parser->setFontSizeMap([
       'small' => '12px',
       'medium' => '16px',
       'large' => '24px',
   ]);
   

2. Custom Elements with Font Support

   $parser = new Parser();
   $parser->addCustomElement('mention', function ($attrs, $text) {
       $fontSize = $attrs['font']['size'] ?? '16px';
       return '<span class="mention" style="font-size: ' . $fontSize . '" data-id="' . $attrs['id'] . '">@' . $text . '</span>';
   });
   

3. Delta Validation

   use Nadar\QuillDeltaParser\Validator;
   
   $validator = new Validator();
   if ($validator->validate($delta)) {
       $html = $parser->parse($delta);
   }
   

4. Batch Processing

   $deltas = collect($request->deltas);
   $htmls = $deltas->map(fn($delta) => $parser->parse($delta));
   

Gotchas and Tips

Common Pitfalls

1. XSS Risks

   • Always sanitize input deltas (use Validator or htmlspecialchars).
   • Avoid !! in Blade if user-generated content isn’t trusted.

2. Nested Deltas

   • Quill’s nested deltas (e.g., lists) require recursive parsing. The parser handles this by default, but custom elements may break nesting.

3. Font Size Attribute Handling

   • The font.size attribute now maps to inline style="font-size: ...".
   • Override with setFontSizeMap for custom size handling.

Debugging Tips

1. Log Raw Deltas

   \Log::debug('Raw Delta:', $delta);
   

   • Verify structure matches Quill’s format (e.g., ['insert', 'text', {'bold': true, 'font': {'size': '24px'}}]).

2. Inspect HTML Output

   $html = $parser->parse($delta);
   \Log::debug('Generated HTML:', $html);
   

   • Use browser dev tools to compare expected vs. actual output.

3. Custom Element Quirks

   • If a custom element fails, check:
     • Correct attribute names in the delta (e.g., font.size vs. font-size).
     • Returned HTML structure (e.g., self-closing tags vs. blocks).

Extension Points

1. Override Default Tags

   $parser->setTagMap([
       'bold' => 'b', // Default: 'strong'
       'italic' => 'i',
   ]);
   

2. Font Size Customization

   $parser->setFontSizeMap([
       'small' => '12px',
       'medium' => '16px',
       'large' => '24px',
   ]);
   

3. Pre/Post-Processing

   $parser->setPreProcess(function ($delta) {
       // Modify delta before parsing (e.g., sanitize)
       return $delta;
   });
   
   $parser->setPostProcess(function ($html) {
       // Modify HTML after parsing (e.g., wrap in div)
       return '<div class="content">' . $html . '</div>';
   });
   

4. Performance

   • For bulk parsing, reuse the Parser instance:

     $parser = new Parser(); // Initialize once
     foreach ($deltas as $delta) {
         $html = $parser->parse($delta);
     }