Fine Diff Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aldaflux/fine-diff-bundle
   

   Add the bundle to app/AppKernel.php:

   new AlDaFlux\FineDiffBundle\AlDaFluxPHPFineDiffBundle(),
   

2. First Use Case: Compare two strings in a Twig template:

   {{ renderDiff('Hello world', 'Hello Laravel') }}
   

   Outputs a side-by-side diff highlighting changes.

Where to Look First

• Twig Functions: renderDiff() and renderHtmlTextDiff() in the Usage section.
• Configuration: config.yml for granularity settings (character, word, sentence, paragraph).
• Source: Original PHP-FineDiff for algorithm details.

Implementation Patterns

Core Workflows

1. String Comparison: Use renderDiff() for plain text (e.g., user-generated content, logs, or API responses).

   {{ renderDiff(oldText, newText, 'word') }}  {# Granularity: word-level diff #}
   

2. HTML-Aware Diffs: Preprocess HTML with strip_tags() before using renderHtmlTextDiff():

   {{ renderHtmlTextDiff(strip_tags(oldHtml), strip_tags(newHtml), 'sentence') }}
   

3. Dynamic Granularity: Pass granularity as a third argument to control sensitivity:

   {% set granularity = 'paragraph' if isLongText else 'character' %}
   {{ renderDiff(text1, text2, granularity) }}
   

Integration Tips

1. Symfony Forms: Display diffs in form validation errors:

   {% for error in form.errors %}
       {{ renderDiff(oldValue, error.message) }}
   {% endfor %}
   

2. API Responses: Compare request/response payloads in debug tools:

   $diff = $this->get('aldaflux_fine_diff')->renderDiff($oldPayload, $newPayload);
   

3. Event Listeners: Log diffs for auditing:

   public function onContentUpdate(ContentEvent $event) {
       $diff = $this->get('aldaflux_fine_diff')->renderDiff(
           $event->getOldContent(),
           $event->getNewContent(),
           'sentence'
       );
       $this->logger->info('Content changed:', ['diff' => $diff]);
   }
   

4. Admin Panels: Highlight changes in CMS content revisions (e.g., SonataAdmin, EasyAdmin).

Gotchas and Tips

Pitfalls

1. HTML Handling:

   • renderHtmlTextDiff() requires strip_tags() preprocessing. Failing to strip tags may break rendering.
   • Example of incorrect usage:

     {{ renderHtmlTextDiff(oldHtml, newHtml) }}  {# ❌ Will fail #}
     

2. Performance:

   • Fine-grained diffs (character level) are slower for large texts (>10KB). Use paragraph for performance-critical paths.

3. False Positives:

   • Word-level diffs ('word') may flag minor typos as changes. Adjust granularity based on use case.

Debugging

1. Empty Output:

   • Ensure input strings are non-empty. Empty strings return no diff.
   • Debug with:

     {{ dump(oldValue) }}, {{ dump(newValue) }}
     

2. Styling Issues:

   • The bundle outputs raw HTML. Override styles in your CSS:

     .diff-add { background: #ddffdd; }
     .diff-del { background: #ffdddd; }
     

Extension Points

1. Custom Granularity: Extend the bundle by adding a custom granularity strategy:

   // src/AlDaFlux/FineDiffBundle/DependencyInjection/Configuration.php
   $builder->append($builder->createArrayNode('custom_granularities'))
       ->addPrototype('strategy')
       ->children()
           ->scalarNode('class')->isRequired()->end()
       ->end();
   

2. Twig Extensions: Override Twig functions in your own bundle:

   // src/Acme/MyBundle/Twig/MyExtension.php
   public function getFunctions() {
       return [
           new \Twig\TwigFunction('customDiff', [$this, 'renderDiff']),
       ];
   }
   

3. Service Configuration: Inject the fine_diff service directly for programmatic use:

   $diffRenderer = $container->get('aldaflux_fine_diff');
   $diff = $diffRenderer->renderDiff($str1, $str2);
   

Pro Tips

1. Localization: Translate diff labels (e.g., "added", "removed") via Symfony’s translation system:

   {{ renderDiff(oldText, newText, 'word', {'added': '✅ Added', 'removed': '❌ Removed'}) }}
   

2. Inline Edits: Use diffs to power collaborative editing (e.g., Google Docs-style):

   <div class="editor-diff">
       {{ renderDiff(currentDraft, latestVersion) }}
   </div>
   

3. Testing: Mock the service in PHPUnit:

   $this->container->set('aldaflux_fine_diff', $this->createMock(FineDiff::class));