Add disableTimeout() method

endelwar · endelwar · commit 40f45aa350a7 · 2025-04-10T15:49:34.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,15 +5,21 @@ The format is based on [Keep a Changelog(https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning(https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+### Added
+- Add `--timeout` option to the WeasyPrint command-line call by default. This improves consistency with the internal process timeout already applied by Symfony Process. If you're running WeasyPrint inside a worker, queue, or other timeout-managed environment, you can disable it using `$pdf->disableTimeout()` or `$pdf->setTimeout(null)`. (#15)
+- Add `disableTimeout()` method to easily disable the new CLI timeout behavior
+
+### Security
+- Update `symfony/process` minimal version to mitigate [CVE-2024-51736](https://github.com/advisories/GHSA-qq5c-677p-737q)
 
 ## 1.5.0 - 2024-11-04
 ### Added
 - Support WeasyPrint 63.0 new `srgb` option
-- Added support for PHP 8.4
+- Add support for PHP 8.4
 
 ## 1.4.0 - 2023-11-20
 ### Changed
-- Added support for Symfony 7.0 and PHP 8.3
+- Add support for Symfony 7.0 and PHP 8.3
 
 ## 1.3.0 - 2023-10-07
 ### Added
@@ -39,7 +45,7 @@ and this project adheres to [Semantic Versioning(https://semver.org/spec/v2.0.0.
 
 ## 1.0.0 - 2023-01-16
 ### Fixed
-- Fixed handling of repeatable options (attachment and stylesheet)
+- Fix handling of repeatable options (attachment and stylesheet)
 
 ### Changed
 - Bump symfony/process up to ^6.2
diff --git a/README.md b/README.md
@@ -81,6 +81,40 @@ $pdf->setOption('media-type', 'screen');
 $pdf->resetOptions();
 ```
 
+### Timeouts
+
+A default timeout of 10 seconds is set for the WeasyPrint process to prevent orphaned or hanging processes.  
+This is a defensive measure that applies in most cases and helps ensure system stability.
+
+You can change the timeout with the `setTimeout()` method:
+
+```php
+$pdf = new Pdf('/usr/local/bin/weasyprint');
+$pdf->setTimeout(30); // 30 seconds
+```
+
+The timeout can be disabled entirely using either of the following:
+
+```php
+$pdf->setTimeout(null);
+// or
+$pdf->disableTimeout();
+```
+
+This is especially useful if you're running inside a *queue worker*, *job runner*, or other environments that already handle timeouts (e.g. Symfony Messenger, Laravel Queue, Supervisor).  
+Disabling the internal timeout in those cases avoids conflicts with higher-level timeout strategies.
+
+> **Note:**  
+> The `setTimeout()` method affects **both**:
+> - how long the process is allowed to run before being forcibly stopped, and
+> - the `--timeout` option passed to the WeasyPrint command-line tool.
+>
+> If you only want to disable WeasyPrint's own timeout (while keeping the execution time limit), use:
+>
+> ```php
+> $pdf->setOption('timeout', null);
+> ```
+
 ## Differences with Snappy
 
 Although PhpWeasyPrint and Snappy are interchangeable, there are a couple of differences between the two, due to WeasyPrint CLI API:
diff --git a/src/AbstractGenerator.php b/src/AbstractGenerator.php
@@ -38,6 +38,21 @@ abstract class AbstractGenerator implements GeneratorInterface, LoggerAwareInter
     /**
      * @param array<string, bool|int|string|array|null> $options
      * @param array<string, mixed>|null                 $env
+     *
+     * @note
+     *  This class sets a default timeout on the process to prevent
+     *  orphaned or hanging processes. This is a defensive measure that applies
+     *  in most cases.
+     *
+     *  If you run this inside a queue worker, job runner, or any environment
+     *  that already handles timeouts (e.g. Symfony Messenger, Laravel Queue),
+     *  you can disable the internal timeout using:
+     *
+     *      $generator->disableTimeout();
+     *  or
+     *      $generator->setTimeout(null);
+     *
+     *  This ensures no conflicts with higher-level timeout strategies.
      */
     public function __construct(?string $binary = null, array $options = [], ?array $env = null)
     {
@@ -171,18 +186,7 @@ protected function buildCommand(string $binary, string $input, string $output, a
                     $command .= ' --' . $key . ' ' . \escapeshellarg($v);
                 }
             } else {
-                switch ($key) {
-                    case 'format':
-                        $command .= ' --' . $key . ' ' . $option;
-                        break;
-                    case 'resolution':
-                    case 'timeout':
-                        $command .= ' --' . $key . ' ' . (int)$option;
-                        break;
-                    default:
-                        $command .= ' --' . $key . ' ' . \escapeshellarg((string)$option);
-                        break;
-                }
+                $command .= ' --' . $key . ' ' . \escapeshellarg((string)$option);
             }
         }
 
@@ -259,6 +263,11 @@ public function setTimeout(?int $timeout): self
         return $this;
     }
 
+    public function disableTimeout(): self
+    {
+        return $this->setTimeout(null);
+    }
+
     /**
      * Defines the binary.
      *
diff --git a/src/Pdf.php b/src/Pdf.php
@@ -42,6 +42,14 @@ public function setTimeout(?int $timeout): self
         return $this;
     }
 
+    public function disableTimeout(): self
+    {
+        parent::disableTimeout();
+        $this->setOption('timeout', null);
+
+        return $this;
+    }
+
     /**
      * @param array<string, bool|int|string|array|null> $options
      *
@@ -137,6 +145,54 @@ protected function configure(): void
         ]);
     }
 
+    /**
+     * Builds the command string.
+     *
+     * @param string                                    $binary  The binary path/name
+     * @param string                                    $input   Url or file location of the page to process
+     * @param string                                    $output  File location to the pdf-or-image-to-be
+     * @param array<string, bool|int|string|array|null> $options An array of options
+     */
+    protected function buildCommand(string $binary, string $input, string $output, array $options = []): string
+    {
+        $escapedBinary = \escapeshellarg($binary);
+        $command = \is_executable($escapedBinary) ? $escapedBinary : $binary;
+
+        foreach ($options as $key => $option) {
+            if (null === $option || false === $option) {
+                continue;
+            }
+
+            if (true === $option) {
+                $command .= ' --' . $key;
+                continue;
+            }
+
+            if (\is_array($option)) {
+                foreach ($option as $v) {
+                    $command .= ' --' . $key . ' ' . \escapeshellarg($v);
+                }
+            } else {
+                switch ($key) {
+                    case 'format':
+                        $command .= ' --' . $key . ' ' . $option;
+                        break;
+                    case 'dpi':
+                    case 'jpeg-quality':
+                    case 'resolution':
+                    case 'timeout':
+                        $command .= ' --' . $key . ' ' . (int)$option;
+                        break;
+                    default:
+                        $command .= ' --' . $key . ' ' . \escapeshellarg((string)$option);
+                        break;
+                }
+            }
+        }
+
+        return $command . (' ' . \escapeshellarg($input) . ' ' . \escapeshellarg($output));
+    }
+
     private function setOptionsWithContentCheck(): void
     {
         $this->optionsWithContentCheck = [
diff --git a/tests/Unit/AbstractGeneratorTest.php b/tests/Unit/AbstractGeneratorTest.php
@@ -587,15 +587,6 @@ public function dataForBuildCommand(): array
                 ],
                 $theBinary . ' --attachment ' . \escapeshellarg('/path1') . ' --attachment ' . \escapeshellarg('/path2') . ' ' . \escapeshellarg('https://the.url/') . ' ' . \escapeshellarg('/the/path'),
             ],
-            [
-                $theBinary,
-                'https://the.url/',
-                '/the/path',
-                [
-                    'resolution' => 100,
-                ],
-                $theBinary . ' --resolution 100 ' . \escapeshellarg('https://the.url/') . ' ' . \escapeshellarg('/the/path'),
-            ],
         ];
     }
 
@@ -915,7 +906,7 @@ private function getPHPExecutableFromPath(): ?string
     public function testFailingGenerateWithOutputContainingPharPrefix(): void
     {
         $media = $this->getMockBuilder(AbstractGenerator::class)
-            ->setMethods([
+            ->onlyMethods([
                 'configure',
                 'prepareOutput',
             ])
diff --git a/tests/Unit/PdfTest.php b/tests/Unit/PdfTest.php
@@ -62,7 +62,7 @@ public function testThatSomethingUsingTmpFolder(): void
         $testObject->setTemporaryFolder(__DIR__);
 
         $testObject->getOutputFromHtml('<html></html>', ['stylesheet' => 'html {font-size: 16px;}']);
-        $this->assertMatchesRegularExpression('/emptyBinary --stylesheet ' . $q . '.*' . $q . ' ' . $q . '.*' . $q . ' ' . $q . '.*' . $q . '/', $testObject->getLastCommand());
+        $this->assertMatchesRegularExpression('/emptyBinary --stylesheet ' . $q . '.*' . $q . ' --timeout \d* ' . $q . '.*' . $q . ' ' . $q . '.*' . $q . '/', $testObject->getLastCommand());
     }
 
     /**
@@ -114,48 +114,71 @@ public function dataOptions(): array
         return [
             '0 - no options' => [
                 [],
-                '/emptyBinary ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
+                '/emptyBinary --timeout \d* ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
             ],
 
             '1 - pass a single stylesheet URL' => [
                 ['stylesheet' => 'https://google.com'],
-                '/emptyBinary --stylesheet ' . $q . 'https:\/\/google\.com' . $q . ' ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
+                '/emptyBinary --stylesheet ' . $q . 'https:\/\/google\.com' . $q . ' --timeout \d* ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
             ],
 
             '2 - pass a single stylesheet file' => [
                 ['stylesheet' => __DIR__ . '/../Fixture/style1.css'],
-                '/emptyBinary --stylesheet ' . $q . \preg_quote(__DIR__ . '/../Fixture/style1.css', '/') . $q . ' ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
+                '/emptyBinary --stylesheet ' . $q . \preg_quote(__DIR__ . '/../Fixture/style1.css', '/') . $q . ' --timeout \d* ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
             ],
 
             '3 - pass two stylesheet files' => [
                 ['stylesheet' => [__DIR__ . '/../Fixture/style1.css', __DIR__ . '/../Fixture/style2.css']],
                 '/emptyBinary --stylesheet ' . $q . \preg_quote(__DIR__ . '/../Fixture/style1.css', '/') . $q . ' '
-                . '--stylesheet ' . $q . \preg_quote(__DIR__ . '/../Fixture/style2.css', '/') . $q . ' ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
+                . '--stylesheet ' . $q . \preg_quote(__DIR__ . '/../Fixture/style2.css', '/') . $q . ' --timeout \d* ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
             ],
 
             '4 - pass one stylesheet file and one inline css' => [
                 ['stylesheet' => [__DIR__ . '/../Fixture/style1.css', 'html {font-size: 24px;}']],
                 '/emptyBinary --stylesheet ' . $q . \preg_quote(__DIR__ . '/../Fixture/style1.css', '/') . $q . ' '
-                . '--stylesheet ' . $q . '.*php_weasyprint.*\.css' . $q . ' ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
+                . '--stylesheet ' . $q . '.*php_weasyprint.*\.css' . $q . ' --timeout \d* ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
             ],
 
             '5 - save the given stylesheet CSS string into a temporary file and pass that filename' => [
                 ['stylesheet' => 'html {font-size: 16px;}'],
-                '/emptyBinary --stylesheet ' . $q . '.*\.css' . $q . ' ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
+                '/emptyBinary --stylesheet ' . $q . '.*\.css' . $q . ' --timeout \d* ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
             ],
 
             '6 - save the content of the given attachment URL to a file and pass that filename' => [
                 ['attachment' => 'https://www.google.com/favicon.ico'],
-                '/emptyBinary --attachment ' . $q . '.*php_weasyprint.*\.temp' . $q . ' ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
+                '/emptyBinary --attachment ' . $q . '.*php_weasyprint.*\.temp' . $q . ' --timeout \d* ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
             ],
 
             '7 - save the content of multiple attachments URL to files and pass those filenames' => [
                 ['attachment' => ['https://www.google.com/favicon.ico', 'https://github.githubassets.com/favicons/favicon.svg']],
-                '/emptyBinary --attachment ' . $q . '.*php_weasyprint.*\.temp' . $q . ' --attachment ' . $q . '.*php_weasyprint.*\.temp' . $q . ' ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
+                '/emptyBinary --attachment ' . $q . '.*php_weasyprint.*\.temp' . $q . ' --attachment ' . $q . '.*php_weasyprint.*\.temp' . $q . ' --timeout \d* ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
+            ],
+
+            '8 - set integer, string, and boolean options' => [
+                ['pdf-variant' => 'pdf/ua-1', 'dpi' => 300, 'timeout' => 60, 'srgb' => true, 'resolution' => 100],
+                "/emptyBinary --pdf-variant 'pdf\/ua-1' --dpi 300 --timeout 60 --srgb --resolution 100 " . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/',
             ],
         ];
     }
 
+    public function testDisableTimeout(): void
+    {
+        $testObject = new PdfSpy();
+        $testObject->disableTimeout();
+        $testObject->getOutputFromHtml('<html></html>');
+
+        $q = self::SHELL_ARG_QUOTE_REGEX;
+        $expectedRegex = '/emptyBinary ' . $q . '.*\.html' . $q . ' ' . $q . '.*\.pdf' . $q . '/';
+
+        $this->assertMatchesRegularExpression($expectedRegex, $testObject->getLastCommand());
+
+        $testObject2 = new PdfSpy();
+        $testObject2->setOption('timeout', null);
+        $testObject2->getOutputFromHtml('<html></html>');
+
+        $this->assertMatchesRegularExpression($expectedRegex, $testObject2->getLastCommand());
+    }
+
     /**
      * @covers \Pontedilana\PhpWeasyPrint\Pdf::createTemporaryFile
      * @covers \Pontedilana\PhpWeasyPrint\Pdf::__destruct
