Laratex Laravel Package

Getting Started

• Install with composer require ismaelw/laratex.
• Publish the config file (typically php artisan vendor:publish --provider="Ismaelw\LaraTeX\LaraTeXServiceProvider") and review config/laratex.php for the LaTeX binary path (pdflatex/xelatex) and temporary directory.
• Confirm the binary is available on the host (which pdflatex) and that the configured temp directory is writable by the web server user.
• First use case: compile a simple LaTeX string to PDF from a controller or artisan tinker:

  use Ismaelw\LaraTeX\Facades\LaraTeX;
  
  $pdf = LaraTeX::compile('\documentclass{article}\begin{document}Hello\end{document}');
  $pdf->save(storage_path('app/hello.pdf'));
  

• Start with a minimal \documentclass{article} document, then move to Blade templates for real reports.

Implementation Patterns

• Blade-based templates: Store .tex Blade views in resources/views/latex/ and render them with data before compiling. This keeps LaTeX layout separate from PHP logic and supports loops/conditionals.
• Controller responses: Compile on demand and return response()->download($path)->deleteFileAfterSend(true) for one-off invoices or reports.
• Queued jobs: LaTeX compilation can take seconds; dispatch a job (e.g., GeneratePdfJob) and notify the user when the PDF is ready. Store the output in storage/app/latex/ and serve via signed URLs.
• Service injection: Type-hint the package’s compiler/service in constructors or resolve via the facade. Wrap compilation in a small application service so you can swap the implementation in tests.
• Config-driven binaries: Use the config file to set the LaTeX engine and temp path per environment (e.g., different paths in local vs. production). The v1.3.0-p1 patch passes the temporary directory to the Process constructor, so custom temp paths now work reliably on older Laravel versions.
• File cleanup: Generate into a unique temp directory per compilation and remove it in a finally block, or use Laravel’s Storage::deleteDirectory() after sending the response.
• Testing: Mock the compiler service or bind a fake that copies a fixture PDF, so tests don’t require a full LaTeX installation.

Gotchas and Tips

• Binary availability: pdflatex must be installed with required packages (e.g., texlive-latex-base, texlive-fonts-recommended). Missing packages produce stderr output that the package may surface as an exception—log the full Process output when debugging.
• Temp directory permissions: The configured temp directory must be writable. If you use a custom path, upgrade to v1.3.0-p1 or later; this patch passes the temp directory to the Process constructor and fixes issue #36 on older Laravel versions.
• Escaping user input: LaTeX special characters (&, %, $, #, _, {, }, ~, ^, \) break compilation. Escape or sanitize user-provided values before injecting them into templates.
• Timeouts: Long documents can exceed the default Process timeout. Set a higher timeout in config or in the job, and consider chunking very large reports.
• Config caching: After changing config/laratex.php, run php artisan config:clear (or config:cache in production) so the new binary/temp paths take effect.
• Cleanup on failure: If compilation throws, temp files may remain. Use try/finally around compilation or a scheduled cleanup command for the temp directory.
• Debugging: Capture and log both stdout and stderr from the LaTeX process. A minimal failing .tex file plus the raw log is usually enough to identify a missing package or syntax error.
• Extension points: Override the compiler binary, temp path, and timeout via config. For custom behavior (e.g., post-processing PDFs), wrap the package service in your own class rather than modifying vendor code.