Filament Docs Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tomatophp/filament-docs
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="TomatoPHP\FilamentDocs\FilamentDocsServiceProvider" --tag="filament-docs-config"
   php artisan vendor:publish --provider="TomatoPHP\FilamentDocs\FilamentDocsServiceProvider" --tag="filament-docs-migrations"
   php artisan migrate
   

2. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \TomatoPHP\FilamentDocs\FilamentDocsPlugin::make(),
           ]);
   }
   

3. First Use Case Create a template via the Templates section in Filament. Use the Tiptop Editor to design your document (e.g., a contract or invoice). Define dynamic variables (e.g., {client_name}) that will be replaced during generation.

Implementation Patterns

Core Workflows

1. Template Creation

   • Use the Tiptop Editor to design reusable templates (e.g., NDAs, invoices, or letters).
   • Define custom variables (e.g., {company_address}, {invoice_total}) using the template builder.
   • Save templates with logical names (e.g., "Client Contract V1").

2. Dynamic Variable Injection

   • Inject variables via the Facade:

     use TomatoPHP\FilamentDocs\Facades\FilamentDocs;
     
     FilamentDocs::setVar('client_name', 'John Doe');
     FilamentDocs::setVar('invoice_total', 1000.00);
     

   • Override variables per document instance using the Filament UI when generating.

3. Document Generation

   • Trigger generation via the "Generate Document" action in Filament.
   • Choose a template, assign variables, and preview before exporting.
   • Export as PDF or print directly with custom headers/footers.

4. Relation Management

   • Link documents to models (e.g., Client, Invoice) via Filament’s relation manager.
   • Example: Attach a generated contract to a Client record for tracking.

5. Bulk Operations

   • Use the filter-by-template feature to generate multiple documents from the same template (e.g., monthly invoices for all clients).

Integration Tips

• Customize Variables Programmatically Extend the facade to add domain-specific variables:

  FilamentDocs::extendVars(function ($vars) {
      $vars['tax_rate'] = config('company.tax_rate');
  });
  

• Hook into Generation Events Listen for document generation events to log or process data:

  FilamentDocs::listen('generating', function ($document) {
      // Log or modify document data before export
  });
  

• PDF Customization Override the PDF renderer by publishing the package’s views:

  php artisan vendor:publish --provider="TomatoPHP\FilamentDocs\FilamentDocsServiceProvider" --tag="filament-docs-views"
  

  Then extend resources/views/vendor/filament-docs/pdf.blade.php.

• Localization Translate template variables and UI text via Filament’s localization system:

  FilamentDocs::setTranslation('client_name', 'Nom du client');
  

Gotchas and Tips

Pitfalls

1. Variable Scope Conflicts

   • Variables set via the facade override those in the Filament UI. Test variable precedence in complex workflows.
   • Fix: Use unique variable names (e.g., invoice_{client_id}_total).

2. Editor Limitations

   • The Tiptop Editor may not support all HTML/CSS features. Test templates in a sandbox first.
   • Tip: Use inline styles or embedded CSS for critical layouts.

3. PDF Rendering Issues

   • Custom headers/footers may break if HTML is malformed. Validate with tools like PDF Crowd.
   • Debug: Check the storage/logs/filament-docs.log for rendering errors.

4. Migration Conflicts

   • If extending the documents table, run migrations after publishing the package’s migrations to avoid schema conflicts.

5. Caching Quirks

   • Generated PDFs are cached. Clear the cache (php artisan cache:clear) if changes to templates or variables aren’t reflected:

     FilamentDocs::clearCache();
     

Debugging Tips

• Log Variables Dump variables before generation:

  FilamentDocs::listen('generating', function ($document) {
      \Log::debug('Vars:', $document->vars);
  });
  

• Inspect Templates View the raw template HTML via the source code button in the Tiptop Editor or by querying the database:

  $template = \TomatoPHP\FilamentDocs\Models\Template::find(1);
  \Log::info($template->content);
  

• Test with Minimal Templates Start with a single variable (e.g., {test}) to isolate issues.

Extension Points

1. Custom Storage Override the default storage path for generated documents:

   config(['filament-docs.storage.path' => storage_path('app/docs')]);
   

2. Add Document Types Extend the Document model to support metadata (e.g., document_type):

   use TomatoPHP\FilamentDocs\Models\Document;
   
   Document::addGlobalScope('type', function (Builder $builder, string $type) {
       $builder->where('metadata->type', $type);
   });
   

3. Webhook Triggers Dispatch events after generation to notify external systems:

   FilamentDocs::listen('generated', function ($document) {
       // Send webhook or update CRM
   });
   

4. Batch Processing Use Laravel queues to generate documents asynchronously:

   FilamentDocs::generateLater($templateId, $vars);