Adf Tools Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require damienharper/adf-tools
   

   No additional configuration is required—it’s a lightweight, dependency-free library.

2. Basic Usage Import the ADF class and parse an Atlassian Document Format (ADF) string:

   use DamienHarper\ADFTools\ADF;
   
   $adfString = '{"blocks":[{"type":"paragraph","text":"Hello, ADF!"}]}';
   $adf = ADF::parse($adfString);
   
   // Convert back to JSON
   echo $adf->toJson();
   

3. First Use Case: Converting ADF to HTML Render ADF to HTML for display in a Laravel Blade view:

   $html = $adf->toHtml();
   return view('editor', ['content' => $html]);
   

Implementation Patterns

Core Workflows

1. Parsing and Serializing

   • Parse ADF from JSON strings (e.g., from Confluence API):

     $adf = ADF::parse(file_get_contents('confluence-export.adf'));
     

   • Serialize ADF to JSON for storage/API responses:

     $json = $adf->toJson();
     

2. Modifying ADF Content

   • Add/Remove Blocks:

     $adf->addBlock(['type' => 'heading', 'text' => 'New Section']);
     $adf->removeBlock(0); // Remove first block
     

   • Update Block Properties:

     $adf->getBlock(0)->setText('Updated text');
     

3. Integration with Laravel

   • Store ADF in Database:

     $post->adf_content = $adf->toJson();
     $post->save();
     

   • Retrieve and Reconstruct:

     $adf = ADF::parse($post->adf_content);
     

4. Rich Text Editing

   • Use with a frontend editor (e.g., TinyMCE, CKEditor) to:
     • Send ADF to the editor via API.
     • Receive updated ADF and parse it server-side.

Advanced Patterns

1. Custom Block Handling Extend the library for unsupported block types:

   ADF::extendBlockType('custom', function ($block) {
       return '<div class="custom-block">' . $block['text'] . '</div>';
   });
   

2. Batch Processing Process multiple ADF strings in a loop:

   foreach ($confluenceExports as $export) {
       $adf = ADF::parse($export);
       // Process or store each ADF
   }
   

3. Validation Validate ADF structure before parsing:

   if (ADF::isValid($adfString)) {
       $adf = ADF::parse($adfString);
   }
   

Gotchas and Tips

Common Pitfalls

1. Malformed ADF JSON

   • Issue: Invalid JSON or ADF structure throws exceptions.
   • Fix: Validate input with ADF::isValid() or wrap parsing in a try-catch:

     try {
         $adf = ADF::parse($input);
     } catch (\Exception $e) {
         Log::error("Invalid ADF: " . $e->getMessage());
     }
     

2. Unsupported Block Types

   • Issue: Custom Confluence blocks may not render.
   • Fix: Use ADF::extendBlockType() or manually handle unsupported blocks in toHtml().

3. HTML Injection Risks

   • Issue: Directly outputting toHtml() may expose XSS.
   • Fix: Sanitize output with Laravel’s e() or a whitelist:

     {!! e($adf->toHtml()) !!}
     

4. Performance with Large ADF

   • Issue: Deeply nested ADF slows parsing.
   • Fix: Optimize by processing blocks in chunks or using ADF::parseFragment() for partial updates.

Debugging Tips

1. Inspect ADF Structure Use toArray() to debug block properties:

   dd($adf->toArray());
   

2. Log Parsing Errors Enable debug mode for detailed exceptions:

   ADF::setDebugMode(true);
   

3. Compare ADF Versions Check for breaking changes between Confluence/ADF versions in the ADF spec.

Extension Points

1. Custom Renderers Override toHtml() for bespoke output:

   class CustomADF extends ADF {
       public function toHtml() {
           // Custom logic
           return parent::toHtml();
       }
   }
   

2. Plugin System Use events (if supported) or hooks to intercept block processing:

   ADF::on('block.render', function ($block, $html) {
       // Modify $html before output
   });
   

3. Testing Mock ADF objects for unit tests:

   $mockAdf = Mockery::mock(ADF::class);
   $mockAdf->shouldReceive('toHtml')->andReturn('<p>Test</p>');