Html2Media Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/Niche Fit: Perfectly aligned with Laravel’s ecosystem, especially for applications requiring dynamic PDF generation (e.g., admin panels, reporting tools, or Filament-based dashboards). Leverages Laravel’s service container and Filament’s action system for seamless integration.
• Use Case Alignment: Ideal for:
  • Document-heavy workflows (invoices, reports, certificates).
  • Filament-powered admin interfaces where in-context PDF generation is needed.
  • Legacy HTML-to-PDF migration without heavy frontend dependencies (e.g., replacing jsPDF or Puppeteer).
• Extensibility: Supports customization via configuration methods (e.g., filename(), orientation(), margins()), allowing adaptation to non-standard use cases (e.g., multi-page layouts, dynamic content).

Integration Feasibility

• Low Friction: Designed for Laravel/Filament, with zero-configuration basics (e.g., composer require + action registration). Minimal boilerplate for core functionality.
• Dependency Stack:
  • Backend: PHP 8.1+, Laravel 9+, Filament 3+ (if using Filament actions).
  • Underlying Tech: Likely uses Dompdf or SnappyPDF (WkHTMLToPDF) under the hood (inferred from feature set). Verify in codebase.
  • Frontend: Lightweight (handles previews/modals via Filament’s built-in UI).
• Data Flow:
  • Input: HTML string or Blade view (via content() method).
  • Output: PDF file (streamed/downloadable) or print dialog trigger.
  • Critical Path: Ensure HTML/CSS is print-optimized (e.g., avoid fixed widths, test with !important overrides).

Technical Risk

• Hidden Dependencies:
  • Ghostscript/WkHTMLToPDF: If using SnappyPDF, ensure server has wkhtmltopdf installed (common pain point in shared hosting).
  • Memory Limits: Large HTML content may hit PHP memory limits (test with max_execution_time and memory_limit).
• CSS/Layout Quirks:
  • PDF rendering may not match browser output (e.g., fonts, tables, or complex layouts). Requires testing with real-world templates.
  • Mitigation: Provide a "preview" step (built-in) to catch issues early.
• Filament-Specific Risks:
  • Version lock: Filament 3.x may introduce breaking changes. Check compatibility with filament/filament version.
  • Action Registration: Ensure action is added to the correct Filament resource/table (e.g., TableActions vs. ResourceActions).
• Security:
  • Arbitrary File Writes: Validate filename() input to prevent directory traversal (e.g., ../malicious.pdf).
  • XSS in HTML: Sanitize user-provided HTML content before passing to the package.

Key Questions

1. Underlying Engine:
   • Is the package using Dompdf or SnappyPDF? Does this align with our server’s capabilities (e.g., wkhtmltopdf installation)?
2. Performance:
   • What’s the max HTML complexity this handles? Have we benchmarked with our largest templates?
3. Filament Version:
   • What’s the supported Filament version range? Are there known issues with Filament 3.x?
4. Customization Limits:
   • Can we override default PDF options (e.g., headers/footers, custom fonts)?
5. Fallbacks:
   • What’s the behavior if PDF generation fails (e.g., missing dependencies)? Is there a graceful degradation path?
6. Testing:
   • How do we test PDF output quality/consistency across different servers or user devices?

Integration Approach

Stack Fit

• Primary Use Case: Laravel applications using Filament for admin interfaces, where PDF generation is needed for:
  • Resource Actions: E.g., "Export as PDF" in Filament tables.
  • Modal Previews: Showing a print-ready version of content before download.
  • Dynamic Reports: Generating PDFs from database-driven HTML templates.
• Alternatives Considered:
  • jsPDF: Client-side, but lacks print dialog and server-side reliability.
  • Puppeteer: Overkill for simple PDFs; requires Node.js.
  • Dompdf Standalone: More control but higher maintenance.
• Stack Compatibility:
  • Laravel: Native integration via service providers and Facades.
  • Filament: First-class support for Filament actions (v3+).
  • Queueable: Can be wrapped in Laravel queues for async generation (not built-in; requires customization).

Migration Path

1. Pilot Phase:
   • Start with a single Filament resource/table where PDF generation is needed.
   • Example: Add to an InvoiceResource for exporting invoices.

   use Torgodly\Html2Media\Actions\Html2MediaAction;
   
   public static function getTableActions(): array
   {
       return [
           Html2MediaAction::make('exportPdf')
               ->filename(fn (Invoice $record) => "invoice_{$record->id}.pdf")
               ->content(fn (Invoice $record) => view('invoices.pdf_template', ['invoice' => $record])),
       ];
   }
   

2. Gradual Rollout:
   • Replace ad-hoc PDF solutions (e.g., manual Dompdf calls) with the package.
   • Extend to other resources as needed (e.g., reports, certificates).
3. Configuration Standardization:
   • Define a base config for PDF settings (e.g., margins, orientation) in a service provider.
   • Example:

   $this->app->singleton(Html2MediaConfig::class, fn () => new Html2MediaConfig([
       'default_options' => [
           'orientation' => 'portrait',
           'margin_top' => 20,
           'margin_bottom' => 20,
       ],
   ]));
   

Compatibility

• Laravel Versions: Tested with Laravel 9+ (check composer.json for exact range).
• Filament Versions: Confirm compatibility with Filament 3.x (may need to pin version).
• PHP Extensions:
  • Ensure file_get_contents, dom, and mbstring are enabled.
  • For SnappyPDF: Verify wkhtmltopdf is installed and in PATH.
• Frontend Dependencies:
  • Filament’s built-in modal system handles previews; no additional JS required.

Sequencing

1. Prerequisites:
   • Install the package: composer require torgodly/html2media.
   • Publish config (if applicable): php artisan vendor:publish --tag=html2media-config.
   • Install wkhtmltopdf (if using SnappyPDF):

     # Ubuntu/Debian
     sudo apt-get install wkhtmltopdf
     # Or download from https://wkhtmltopdf.org/
     

2. Core Integration:
   • Register actions in Filament resources/tables.
   • Test with static HTML first (e.g., ->content('<h1>Test</h1>')).
3. Dynamic Content:
   • Integrate with Blade views or Livewire/Inertia components.
   • Example:

     ->content(fn ($record) => view('emails.template', ['data' => $record->toArray()]))
     

4. Advanced Customization:
   • Override default PDF options (e.g., headers, footers).
   • Implement async processing via Laravel queues.
5. Monitoring:
   • Log failures (e.g., missing wkhtmltopdf) and set up alerts.
   • Test edge cases (e.g., large HTML, complex CSS).

Operational Impact

Maintenance

• Package Updates:
  • Monitor for breaking changes (MIT license allows forks if needed).
  • Test updates against Filament/Laravel versions.
• Dependency Management:
  • wkhtmltopdf updates may require reconfiguration.
  • Dompdf/SnappyPDF updates could affect rendering behavior.
• Custom Code:
  • Minimal if using out-of-the-box features. Custom actions/configs may need updates if the package API changes.

Support

• Troubleshooting:
  • Common issues:
    • Blank PDFs: Often due to CSS conflicts (e.g., position: fixed).
    • Missing Dependencies: Clear error messages for wkhtmltopdf or PHP extensions.
    • Filament Action Not Showing: Check resource/action registration.
  • Debugging tools:
    • Use the preview modal to inspect HTML/CSS before PDF generation.
    • Log the generated HTML to verify content before conversion.
• Documentation Gaps:
  • Limited examples for non-Filament use cases (e.g., standalone Laravel routes).
  • No clear guidance on async processing or custom PDF options.

Scaling

• Performance:
  • Sync: PDF generation blocks the request. For large HTML, consider:
    • Async Processing: Dispatch a job to generate PDFs