Merge pull request #5 from Gagl0u/add-custom-extension

feat: Add the possibility to add a custom extension to twig
bugfix: escaping for " and '
dependencies updated

Author: lukas-staab

README.md

@@ -56,9 +56,13 @@ Example: `_tex.dir`
 php -f samples/simple-report.php
 ```
 
+# Examples 
+
+You can find some real world examples in the `samples` Folder
+
 # Contribute 
 Please run 
 ```
 composer cs-fix 
 ```
-before doing a pull request
+and commit the changes in an extra commit before doing a pull request

composer.json

@@ -3,18 +3,18 @@
     "description": "Renders LaTeX Templates in PHP",
     "type": "libary",
     "license": "MIT",
-    "version": "1.1.9",
+    "version": "1.2.0",
     "authors": [
         {
             "name": "Lukas Staab",
-            "email": "l.staab@posteo.de"
+            "email": "lukas@open-administration.de"
         }
     ],
     "minimum-stability": "stable",
     "require": {
         "php": "^8.0",
         "symfony/process": "^5.3|^6.0|^7.0",
-        "twig/twig": "^3.3",
+        "twig/twig": "^3.10",
         "psr/log": "^1|^2|^3"
     },
     "require-dev": {

composer.lock

@@ -5,7 +5,6 @@
 \usepackage{graphicx}
 \usepackage{xcolor}
 \usepackage{ngerman}
-\usepackage[tx]{sfmath}
 \usepackage{calc}
 \usepackage{lastpage}
 \usepackage{xifthen}

samples/basic.tex.twig

@@ -6,27 +6,27 @@
 
 require ROOT . '/vendor/autoload.php';
 
-$finder = new \Symfony\Component\Process\ExecutableFinder();
+$finder = new Symfony\Component\Process\ExecutableFinder();
 $pdfLatex = $finder->find('pdflatex');
 $tex = new LatexRenderer(__DIR__, ROOT . '/runtime/', 'pdflatex', true); // <- debug true - files will not be deleted
-$monolog = new \Monolog\Logger('Tex-Samples', [new \Monolog\Handler\StreamHandler('php://output')]);
+$monolog = new Monolog\Logger('Tex-Samples', [new Monolog\Handler\StreamHandler('php://output')]);
 $tex->setLogger($monolog);
 $pdf = $tex->renderPdf('simple-report', [
     'title' => 'My Custom Title',
     'author' => 'Me!',
     'content' => [
         [
-          'headline' => 'This is a Test Headline',
-          'items' => [
-              [
-                  'label' => 'test',
-                  'value' => 'value',
-              ],
-              [
-                  'label' => 'test',
-                  'value' => 'value',
-              ],
-          ],
+            'headline' => 'This is a Test Headline',
+            'items' => [
+                [
+                    'label' => 'test',
+                    'value' => 'value',
+                ],
+                [
+                    'label' => 'test',
+                    'value' => 'value',
+                ],
+            ],
         ],
         [
             'headline' => 'test2',
@@ -57,6 +57,6 @@
         ],
     ],
 ], [
-    'example.pdf' => file_get_contents('example.pdf'),
+    'example.pdf' => file_get_contents(ROOT . '/samples/example.pdf'),
 ]);
 echo $pdf !== null ? 'Success' . PHP_EOL : 'Failure' . PHP_EOL;

samples/simple-report.php

@@ -41,8 +41,11 @@
         \vspace{5mm}
     (% endif %)%end signatures
 (% endfor  %)%end content
-\mysection{Attachments}
+\mysection{List of Attachments}
 \begin{enumerate}[label=\roman*)]
+(% if _tex.files is empty  %)
+    \item no attachments given
+(% endif %)
 (% for name,path in _tex.files %)
     \item \texttt{(( name ))} in \texttt{(( path ))} with \texttt{(( path|pages ))} pages
 (% endfor %)

samples/simple-report.tex.twig

@@ -0,0 +1,56 @@
+<?php
+
+use PhpLatexRenderer\LatexRenderer;
+
+define('ROOT', dirname(__FILE__, 2));
+
+require ROOT . '/vendor/autoload.php';
+
+$finder = new Symfony\Component\Process\ExecutableFinder();
+$pdfLatex = $finder->find('pdflatex');
+$tex = new LatexRenderer(__DIR__, ROOT . '/runtime/', 'pdflatex', true); // <- debug true - files will not be deleted
+$monolog = new Monolog\Logger('Tex-Samples', [new Monolog\Handler\StreamHandler('php://output')]);
+$tex->setLogger($monolog);
+$pdf = $tex->renderPdf('simple-report', [
+    'title' => 'My Custom Title',
+    'author' => 'Me!',
+    'content' => [
+        [
+            'headline' => 'This is a Test Headline',
+            'items' => [
+                [
+                    'label' => 'Euro',
+                    'value' => '€',
+                ], [
+                    'label' => 'Dollar',
+                    'value' => '$',
+                ], [
+                    'label' => 'Tilde',
+                    'value' => '~',
+                ], [
+                    'label' => 'Circumflex',
+                    'value' => '^',
+                ], [
+                    'label' => 'And',
+                    'value' => '&',
+                ], [
+                    'label' => 'Percent',
+                    'value' => '%',
+                ], [
+                    'label' => 'Hashtag',
+                    'value' => '#',
+                ], [
+                    'label' => 'Underscore',
+                    'value' => '_',
+                ], [
+                    'label' => 'Curlybraces',
+                    'value' => '{}',
+                ], [
+                    'label' => 'Hyphens',
+                    'value' => '"\'',
+                ],
+            ],
+        ],
+    ],
+]);
+echo $pdf !== null ? 'Success' . PHP_EOL : 'Failure' . PHP_EOL;

samples/testEscaping.php

@@ -1,7 +1,7 @@
 <?php
 
 require dirname(__FILE__, 2) . '/vendor/autoload.php';
-$p = new \Symfony\Component\Process\Process(['pdflatex'], __DIR__, getenv());
+$p = new Symfony\Component\Process\Process(['pdflatex'], __DIR__, getenv());
 $p->run();
 echo $p->getOutput();
 echo PHP_EOL . 'error:';

samples/testPath.php

@@ -4,18 +4,32 @@
 
 class LatexEscape
 {
-    public static function escape($twig, ?string $unsafe, $charset): string
+    // @see: https://tex.stackexchange.com/a/34586
+    public const ESCAPES = [
+        '\\' => '\\textbackslash{}',
+        '&' => '\\&',
+        '%' => '\\%',
+        '$' => '\\$',
+        '#' => '\\#',
+        '_' => '\\_',
+        '{' => '\\{',
+        '}' => '\\}',
+        '~' => '\\~{}',
+        '^' => '\\^{}',
+        "'" => "\\'{}",
+        '"' => '\\"{}',
+    ];
+
+    public static function escape(?string $unsafe, $charset): string
     {
         if ($unsafe === null) {
             return '';
         }
         $safer = str_replace(
-            ['\\', '&', '%', '$', '#', '_', '{', '}', '~', '^'],
-            ['\\textbackslash{}', '\\&', '\\%', '\\$', '\\#', '\\_', '\\{', '\\}', '\\textasciitilde{}', '\\textasciicircum{}'],
+            array_keys(self::ESCAPES),
+            array_values(self::ESCAPES),
             $unsafe
         );
-        $safer = trim($safer);
-        // $safer = str_replace(PHP_EOL, '\\\\', $safer);
-        return $safer;
+        return trim($safer);
     }
 }

src/LatexEscape.php

@@ -9,9 +9,10 @@
 use Twig\Environment;
 use Twig\Error\Error;
 use Twig\Extension\DebugExtension;
-use Twig\Extension\EscaperExtension;
+use Twig\Extension\ExtensionInterface;
 use Twig\Lexer;
 use Twig\Loader\FilesystemLoader;
+use Twig\Runtime\EscaperRuntime;
 
 /**
  * Configure and execute the rendering
@@ -22,7 +23,7 @@ class LatexRenderer
 
     private string $latexExec;
 
-    private \Twig\Environment $twig;
+    private Environment $twig;
 
     private bool $debug;
 
@@ -34,7 +35,7 @@ class LatexRenderer
      * @param $latexExec string the path to the latex exec to use
      * @param $debug bool true the files will not be deleted after attempted rendering
      */
-    public function __construct($templateDirs, string $tmpDir = '/tmp/', string $latexExec = 'pdflatex', bool $debug = false)
+    public function __construct(array|string $templateDirs, string $tmpDir = '/tmp/', string $latexExec = 'pdflatex', bool $debug = false)
     {
         $this->debug = $debug;
         $this->latexExec = $latexExec;
@@ -47,7 +48,7 @@ public function __construct($templateDirs, string $tmpDir = '/tmp/', string $lat
             'cache' => false,
         ]);
         $this->twig->addGlobal('_tex', []);
-        $this->twig->getExtension(EscaperExtension::class)->setEscaper('tex', [LatexEscape::class, 'escape']);
+        $this->twig->getRuntime(EscaperRuntime::class)->setEscaper('tex', [LatexEscape::class, 'escape']);
         $this->twig->addExtension(new LatexFilterExtension());
         $this->twig->addExtension(new PdfFilterExtension());
         if ($debug) {
@@ -62,7 +63,7 @@ public function __construct($templateDirs, string $tmpDir = '/tmp/', string $lat
     }
 
     /**
-     * @param array $lexerOptions {@see \Twig\Lexer}
+     * @param array $lexerOptions {@see Lexer}
      */
     public function setTwigLexer(array $lexerOptions): void
     {
@@ -74,9 +75,6 @@ public function setLogger(LoggerInterface $logger): void
         $this->logger = $logger;
     }
 
-    /**
-     * @param $templateDir
-     */
     public function setTemplateDir($templateDir): void
     {
         $this->twig->setLoader(new FilesystemLoader($templateDir));
@@ -96,6 +94,14 @@ public function setTmpDir(string $tmpDir): void
         }
     }
 
+    /**
+     * @param ExtensionInterface $extension the custom extension to add to twig instance
+     */
+    public function addCustomExtension(ExtensionInterface $extension): void
+    {
+        $this->twig->addExtension($extension);
+    }
+
     /**
      * @param array $variables _tex will be added
      * @param array $files additional files which will be saved to ./files/<name> - format: key=name, value=fileContent
@@ -133,7 +139,7 @@ public function renderPdf(string $templateName, array $variables, array $files =
 
         $proc = new Process([$this->latexExec, 'main.tex'], $this->tmpDir . "tex/$templateName/$uid/", getenv());
         $proc->run();
-        // do a second time
+        // run it a second time, some tex features need dual compilation
         $proc2 = $proc->restart();
         $proc2->wait();
         $dir = $this->tmpDir . "tex/$templateName/$uid";