Filament Diffs Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kirschbaum-development/filament-diffs
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="KirschbaumDevelopment\FilamentDiffs\FilamentDiffsServiceProvider"
   

2. Register the Plugin In your AppServiceProvider or Filament panel configuration:

   use KirschbaumDevelopment\FilamentDiffs\FilamentDiffsPlugin;
   
   FilamentDiffsPlugin::make()
       ->register();
   

3. First Use Case Display raw file content in an Infolist:

   use KirschbaumDevelopment\FilamentDiffs\Components\FileEntry;
   
   FileEntry::make('Code Snippet')
       ->content(fn ($record) => $record->code)
       ->language('php') // Optional: auto-detects if omitted
       ->columnSpanFull(),
   

Implementation Patterns

Core Workflows

1. Displaying Static or Dynamic Content

• Static Content: Hardcode the content directly:

  FileEntry::make('README.md')
      ->content('```markdown\n# Hello World\n```')
      ->language('markdown'),
  

• Dynamic Content: Fetch from a model or API:

  FileEntry::make('User Script')
      ->content(fn ($record) => $record->script)
      ->language('javascript'),
  

2. Side-by-Side Diffs

Compare two versions (e.g., old vs new):

use KirschbaumDevelopment\FilamentDiffs\Components\FileDiffEntry;

FileDiffEntry::make('Version Comparison')
    ->oldContent(fn ($record) => $record->old_version)
    ->newContent(fn ($record) => $record->new_version)
    ->language('yaml')
    ->columnSpanFull(),

3. Integration with Filament Forms

Use FileEntry in Forms for editing code snippets:

use KirschbaumDevelopment\FilamentDiffs\Components\FileEntry;

FileEntry::make('Configuration')
    ->content(fn ($record) => $record->config)
    ->language('json')
    ->required()
    ->columnSpanFull(),

4. Customizing Syntax Highlighting

Override default language detection or themes:

FileEntry::make('Custom Theme')
    ->content('...')
    ->language('php')
    ->theme('dark+') // Options: 'default', 'dark', 'dark+', 'light+'
    ->columnSpanFull(),

Advanced Patterns

1. Conditional Rendering

Show diffs only when changes exist:

FileDiffEntry::make('Changes')
    ->oldContent(fn ($record) => $record->previous_content)
    ->newContent(fn ($record) => $record->current_content)
    ->visible(fn ($record) => $record->has_changes),

2. Nested Diffs in Tables

Embed diffs in Filament Tables for row-level comparisons:

use KirschbaumDevelopment\FilamentDiffs\Components\FileDiffEntry;

Table::column(
    FileDiffEntry::make('Diff')
        ->oldContent(fn ($record) => $record->old_data)
        ->newContent(fn ($record) => $record->new_data)
        ->language('json')
        ->width('100%'),
),

3. API Payload Prettification

Format JSON/API responses for readability:

FileEntry::make('API Response')
    ->content(fn ($record) => json_encode($record->response, JSON_PRETTY_PRINT))
    ->language('json')
    ->columnSpanFull(),

Gotchas and Tips

Pitfalls

1. Performance with Large Files

   • Issue: Rendering massive files (e.g., 100KB+) may lag or crash.
   • Fix: Use ->maxLines(100) to truncate or pre-process content server-side.

2. Language Auto-Detection Failures

   • Issue: @pierre/diffs may misidentify languages (e.g., text/plain for unknown files).
   • Fix: Explicitly set the language:

     ->language('text') // Fallback
     

3. Dark Mode Inconsistencies

   • Issue: Themes may not respect Filament’s dark/light mode.
   • Fix: Force a theme:

     ->theme(app()->environment('local') ? 'dark+' : 'light+')
     

4. Caching Static Diffs

   • Issue: Repeatedly generating diffs for unchanged data wastes resources.
   • Fix: Cache the diff output:

     ->cacheFn(fn ($record) => $record->diff_cache_key)
     

Debugging Tips

1. Inspect Raw Content Log the input to @pierre/diffs to debug rendering:

   ->content(fn ($record) => {
       \Log::debug('Diff Input:', ['content' => $record->content]);
       return $record->content;
   }),
   

2. Validate Language Support Check supported languages in @pierre/diffs. Unsupported languages render as plain text.

3. Clear Filament Cache After updates, run:

   php artisan filament:cache-reset
   

Extension Points

1. Custom Diff Algorithms Override the diff engine by binding a custom service:

   $this->app->bind(
       \KirschbaumDevelopment\FilamentDiffs\Contracts\DiffEngine::class,
       fn () => new CustomDiffEngine()
   );
   

2. Add New Themes Extend the theme() method by publishing and modifying the plugin’s assets:

   php artisan vendor:publish --tag=filament-diffs-assets
   

3. Localization Translate labels (e.g., "Added", "Removed") by publishing the language files:

   php artisan vendor:publish --tag=filament-diffs-translations