Download the PHP package ismaelw/laratex without Composer

LaraTeX

A laravel package to generate PDFs using LaTeX

· Report Bug · Request Feature

For better visualization you can find a small Demo and the HTML to LaTeX converter here.

Getting Started

Important information about your environment

This package was developed and tested on Unix (FreeBSD) servers and has been tested successfully on a Windows machine both running pdflatex. Always make sure to write your paths correctly :)

This package makes use of the storage_path() function. On Windows it is possible that the absolute path will be written out with backslashes. Windows is really good with paths using both forward & backslashes but just keep this in mind if something doesn't work that well on windows.

Prerequisites

You need to have texlive-full installed on your server. This program has tex packages and language libraries which help you generate documents. Note: You can also choose to install textlive which is the lighter version of the package.

The difference is:

• When you install textlive and want to use any additional tex package, you need to install it manually.
• texlive-full comes with these extra packages. As a result it may take up some additional space on your server (to store the package library files).

If you are choosing a hosting provider that doesn't allow you to install applications yourself please make sure that pdflatex, xelatex or lualatex is installed or ask if it can get installed. Also make sure that you have SSH access to the server as you might need it to find out in which path your pdflatex installation is sitting.

Installation

You can install the package with composer:

Configuration

To load the config file with php artisan run the following command:

After this please make sure to configure your LaraTeX installation. In your LaraTeX Config file \config\laratex.php you can configure two settings:

binPath If your system doesn't allow to just run the command line command "pdflatex" you may specify the correct one. On Unix systems you can find out which bin path to use by running the command which pdflatex

If you are running this package with on a windows system please check this in cmd.exe before. There you should find out if running the command pdflatex works in cmd or if you need to provide the absolute path to your pdflatex application. If you cannot just run pdflatex you might have to add the path to your pdflatex compiler in your PATH system environment variables.

bibTexPath If your system doesn't allow to just run the command line command "bibtex" you may specify the correct one. On Unix systems you can find out which bin path to use by running the command which bibtex

If you are running this package with on a windows system please check this in cmd.exe before. There you should find out if running the command bibtex works in cmd or if you need to provide the absolute path to your bibtex application. If you cannot just run bibtex you might have to add the path to your bibtex compiler in your PATH system environment variables.

tempPath This specifies the folder where temporary files are saved while rendering a tex file into a PDF file. It is important that you always start your path without a slash and end your path with a slash (e.g. app/pdf/)

teardown As seen in the section Garbage Collection this package deletes all temp files (log, aux etc.) created while generating the PDF file. When debugging successfully generated PDF files it can be useful to check the generated tex file. Set this setting to false if you don't want LaraTeX to delete those files after generating the PDF.

Usage

Dry Run

Before diving into the usage directly, it is important that you make sure that the required programs are installed properly on your server. The package comes with a dryrun method. It will automatically generate a file called dryrun.pdf if everything is set up properly on the server. If not please double-check the configuration of the binPath above.

Dryrun will download a beautifully clean test pdf if pdflatex is setup properly.

With this package you have multiple options. You can render a PDF file and download it directly, save it somewhere, just get the tex content or bulk download a ZIP file containing multiple generated PDF files.

Preparing a Laravel View with LaTeX Content

Create a view file inside resources/views/latex/tex.blade.php You are of course free to create your view files wherever you want inside of your resources folder. Just make sure to define the view to use correctly later.

You can see how we have easily used blade directives for {{ $name }} to show a name or @foreach to show languages in a table to dynamically generate the content.

For more complex LaTeX files where you may need to use blade directives like {{ $var }} inside of a LaTeX command which already uses curly brackets (e.g. \textbf{}) you can always use Laravels @php @endphp method or plain PHP like ` or<?= $var ?>(Example:\textbf{<?= $var ?>}`).

As an addition there is also a @latex() Blade directive mentioned in the next chapter.

Important note when using html characters

When using the {{ }} statement in a blade template, Laravel's blade engine always sends data through the PHP function htmlspecialchars() first. This will convert characters like & to & and < to < to just mention a few. pdflatex doesn't like those converted string and will throw an error like Misplaced alignment tab character &..

To fix this issue you have to use the {!! !!} statement so that unescaped text is written to your tex template.

Using the Blade directive

Since LaTeX has its own syntax it is not advised to use the standard blade syntax {{ $variable }} or {!! $variable !!}. Instead you can use @latex($variable) in your blade templates instead, which handles the suitable escaping of reserved LaTeX characters.

Create a view file inside resources/views/latex/tex.blade.php You are of course free to create your view files wherever you want inside of your resources folder. Just make sure to define the view to use correctly later.

You can see how we have easily used the @latex() Blade directive to print variables.

Using graphics inside of your LaTeX files

Where exactly pdflatex looks for graphics included inside of a .tex file I am not really sure. What helped me the most was to always give the absolute path to a graphic like \includegraphics[scale=0.06]{/absolute/path/to/www/storage/graphics/file.pdf} for example. If you have a better working idea please help me and share your knowledge with me :)

Download a PDF file

If you named your blade file differently or you have it in another folder make sure to set the blade file correctly: return (new LaraTeX('folder.file'))

Save a PDF file

To save a PDF File use the savePdf Method.

Make sure that the destination folder exists inside of your storage folder.

Return the PDF content

To just get the pdf content as RAW or base64 use the content Method.

The default is raw.

or with base64:

Return the PDF inline

To just get the PDF inline use the inline Method.

This will return the pdf as an inline document stream shown as filename.pdf.

Return the TeX data

Using Raw TeX

If you do not want to use views as tex files, but already have tex content, or are using other libraries to generate tex content, you can use RawTex class instead of passing a view path :

Compile multiple times

There are a few cases in which it is necessary to compile twice. If you are using a table of contents (TOC) for example, or if you use the package lastpage to get a better pagination (Page n of n) as another example.

LaraTeX compiles once as a default. If you need to compile twice (or - for whatever reason more than twice) you can use the method compileAmount() to achieve this.

Compile using bibtex

If you want to use bibtex, please make sure that you have the bibTexPath property set correctly inside your laratex.php config file.

Bulk download in a ZIP archive

You want to export multiple PDFs inside of a ZIP-Archive? This package has that functionality ready for you. This gives a great flexibility for you. However, make sure you are not passing too many PDFs together, as it is going to consume a good amount of server memory to export those together.

Convert HTML to LaTeX BETA

As I already had a case where the data sent to the latex view was in HTML format I decided to add a parser that converts basic HTML strings to LaTeX. Included is a set of HTML Tags and how they should get converted. Note: At the end of the conversion, all HTML Tags that are not in the default conversion set nor in the override conversion set will be removed with strip_tags().

If you need the functionality but need a certain HTML Tag converted differently, you can send an override array to the method. This override array needs to look like this:

Explanation for the array keys:

The next code snippet shows how the process for the conversion works:

This example would return the following LaTeX String:

Listening to events

Whenever a pdf is succesfully generated, it fires the event LaratexPdfWasGenerated. Similarly whenever the PDF generation fails it fires the event LaratexPdfFailed.

These events are important if you need to perform some actions depending on the generation status, like updating the database. But mostly these PDF files have some metadata like the user the PDF belongs to or to which order the PDF belongs. You can pass these metadata while instantiating LaraTeX as a second argument.

This metadata is then passed back to you from the fired event, which makes it much more meaningful to listen. The metadata can be anything, it can be a string, numeric, an array, an object, a collection and so on. You can pass the metadata depending on your desired logic.

Then you can define a listener like :

Garbage Collection

When you export the PDF, a few extra files are generated by pdflatex along with your PDF (e.g. .aux, .log, .out etc.). The package takes care of the garbage collection process internally. It makes sure that no files are remaining when the PDF is generated or even when any error occures.

This makes sure the server does not waste it's space keeping those files.

Error Handling

We are using the application pdflatex from texlive to generate PDFs. If a syntax error occures in your tex file, it logs the error into a log file. Or if it is turned off, it shows the output in the console.

The package takes care of the same logic internally and throws ViewNotFoundException. The exception will have the entire information about the error easily available for you to debug.

Contribution

Please feel free to contribute if you want to add new functionalities to this package.

Credits

This Package was inspired alot by the laravel-php-latex package created by Techsemicolon Later I started my own version of laravel-php-latex ismaelw/laravel-php-latex because of missing support on the other package.

For better compatibility and better configuration handling I decided to create this package.

Thanks to the contribution of @koona-labs you can now use Blade directives.

Changelog

Please see CHANGELOG for more information about any major change.

License

The MIT License (MIT). Please see License File for more information.