vrok/tex-wrapper

PDFLatex wrapper class

1.2.1 2023-01-24 18:16 UTC

Requires

• php: >=7.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.16.3
• phpunit/phpunit: ^9.2.3

MIT

• wrapper
• latex
• pdflatex

README

PHP class wrapping calls to PDFLaTeX/LuaLaTeX to generate PDF files from LaTeX generated by PHP itself.

Requires pdflatex/lualatex or another engine to be installed, e.g. in Debian package texlive-latex-base.

Usage

// autogenerate filename for TeX file in temp dir
$wrapper = new TexWrapper\Wrapper();

// use existing TeX or store in custom path.
// the resulting PDF will have the same filename with ".pdf" appended
$wrapper = new TexWrapper\Wrapper('/my/path/texfile');

// generate the TeX file
$texContent = '\documentclass{article}
        \begin{document}
        \title{Introduction to \LaTeX{}}
        \author{Author Name}
        \maketitle
        \section{Introduction}
        Here is the text of your introduction.
        \end{document}';
$wrapper->saveTex($texContent);

// to customize log output or apply texfot to filter unnecessary messages
$wrapper->setCommand('texfot '.$wrapper->getCommand().' 2>&1');

// to use lualatex instead of pdflatex
$cmd = 'lualatex --file-line-error '
        .' --interaction=nonstopmode --output-directory=%dir% %file%';
$wrapper->setCommand($cmd);

// build PDF file in the same path where the TeX file lives
$result = $wrapper->buildPdf();
if ($result) {
    echo "PDF file ".$wrapper->getPdfFile()." was created!";
} else {
    echo "PDF file wasn't generated!";
}

// even when the PDF was generated there could be errors and the latex engine
// or the post-processing command exited with an error code > 0
// getErrors() returns an array, possible indexes are: engine, missingFonts,
// postProcessor
var_dump($wrapper->getErrors());

// pdflatex always generates output, some warnings like missing fonts do not
// generate errors, the output is always saved:
var_dump($wrapper->getLog()); // returns string

// if you don't need the TeX file anymore
// it is automatically deleted on Wrapper destruction if no initial filename
// was set
$wrapper->deleteTex();

Post-Processing

To apply post-processing to the created PDF, e.g. to reduce file size use postProcess($cmd). The command must keep the PDF file in place, else postProcess will return false. The placeholder %file% points to the previously created PDF file, %dir% to the containing folder.

// Example: use ghostscript (debian package: ghostscript) to minimize PDF file
// size. Test first: very simple documents can get larger through this!
$postProcessor = 'gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4'
        .' -dPDFSETTINGS=/printer -dNOPAUSE -dQUIET -dBATCH'
        .' -dDetectDuplicateImages -dCompressFonts=true -r150'
        .' -sOutputFile=%file%.tmp %file% && mv %file%.tmp %file%';
$result = $wrapper->postProcess($postProcessor);
if ($result) {
    echo "post-processed ".$wrapper->getPdfFile();
} else {
    echo "post-processing failed!";

    $errors = $wrapper->getErrors();
    var_dump($errors['postProcessor']);
}

Note on texfot

Texfot tries to remove unnecessary lines from the LaTeX engine output. But while pdflatex/lualatex outputs everything including all errors to the stdout, texfot writes errors to stderr, so we have to include them in stdout by using "2>&1" in the command for the wrapper to log them. Texfot uses the temporary file /tmp/fot which is not deleted after execution so it can cause errors when used by different users which can not write the others files.

Note on LuaLaTeX

The lualatex command requires access to a working directory in $HOME, e.g. $HOME/.texlive2017, depending on the installation and version. Make sure to create it for the user executing PHP before using the script.