Implement Webdriver by TheSyscall · Pull Request #88 · Icinga/icingaweb2-module-pdfexport

TheSyscall · 2026-03-13T10:42:08Z

Changes

Removed ReactPHP dependency
The module no longer relies on ReactPHP, as such it no longer provides the asynchronous methods to generate PDFs that were never part of the Hook
Introduced backend abstraction
A new backend concept allows different rendering strategies to be plugged in and extended more easily.
Added WebDriver support
Implemented a WebDriver-based backend with support for Chrome and Firefox.
Automatic backend fallback
If a backend fails or is unavailable, the system now automatically falls back to the next available option. (The order of this is currently hardcoded as Webdriver > Remote Chrome > Local Chrome)
New configuration form
Replaced the existing configuration with a new ipl\Web\Compat\Form-based ConfigForm.

Requires

related to Icinga/icingaweb2-module-reporting#275

WebDriver

This module can be configured to connect to a webdriver instance. (Backend)

When a PDF is requested, via the Print PDF button on any site or the one in the reporting module, it sends commands to the WebDriver server in a standardized format.

Each browser has its own driver (like ChromeDriver for Chrome or GeckoDriver for Firefox).
This driver acts as a bridge between your script and the browser.

Browser
The driver sends commands to the browser, which executes them just like a user interaction.

For this to work we require a working chromedriver or geckodriver (firefox) instance.

Adding this to a docker compose file will spin up one for each of the supported webdrivers.

  selenium-chrome:
    image: selenium/standalone-chrome
    container_name: selenium-chrome
    ports:
      - "4444:4444"
    shm_size: '2gb'
    restart: always

  selenium-firefox:
    image: selenium/standalone-firefox
    container_name: selenium-firefox
    ports:
      - "4445:4444"
      - "7900:7900"
    shm_size: '2gb'
    restart: always

Currently supported features:

Backend	Generate PDF	Layout Plugins	Merge PDF (Coverpage)	Coverpage Layout	Header/Footer
HeadlessChrome Remote (Legacy)	Yes	Yes	Yes	Yes	Yes
HeadlessChrome Local (Legacy)	Yes	Yes	Yes	Yes	Yes
Chromedriver	Yes	Yes	Yes	No	Yes
Geckodriver	Yes	No	No	No	No

Known issues

Firefox seems to generate compressed PDFs and the TCPDF library we use https://github.com/karriereat/pdf-merge seems to not handle the deflate process properly.
~~Chromedriver reports an error with the cover page properties.~~ Is actually related to a deprecated command.

(
x   [error] => invalid argument
   [message] => invalid argument: params not passed
   (Session info: chrome=145.0.7632.116)
   [stacktrace] => #0 0x55aaccc62b6a <unknown>
#1 0x55aacc675a32 <unknown>
#2 0x55aacc71fcee <unknown>
#3 0x55aacc713369 <unknown>
#4 0x55aacc6bcc0f <unknown>
#5 0x55aacc6bd9d1 <unknown>
#6 0x55aaccc276b9 <unknown>
#7 0x55aaccc2a5c1 <unknown>
#8 0x55aaccc13e29 <unknown>
#9 0x55aaccc2b17e <unknown>
#10 0x55aaccbfa4b0 <unknown>
#11 0x55aaccc4f578 <unknown>
#12 0x55aaccc4f74b <unknown>
#13 0x55aaccc611a3 <unknown>
#14 0x7fc8d9558aa4 <unknown>
#15 0x7fc8d95e5a64 __clone
)

TheSyscall · 2026-03-19T14:45:04Z

If you use docker you can just use the two services provided in the PR description.
The only other configuration apart from this is to go to the module's configuration page and add the host + port to the webdriver server.

To test the legacy chrome backend, just follow the existing documentation.

The PdfExport module allows you to create PDFs of any page in IW2, it is also used to create reports with a custom cover page in the reporting module.

TheSyscall · 2026-03-23T09:18:25Z

The master is also affected, so this is not our problem, is it?

It is not. The connection to the user can time out before the PDF is done generating, that seems to be a problem that has always existed, and this PR doesn't change that.

sukhwinder33445 · 2026-04-10T09:19:57Z

Please have a look at this comment and the screenshot.

TheSyscall · 2026-04-15T11:40:28Z

Please have a look at this comment and the screenshot.

This has been addressed in 6861696

Al2Klimov · 2026-04-15T14:24:55Z

+            'required'    => true,
+            'placeholder' => 100,
+            'min'         => 0,
+            'description' => $this->translate('The priority of the backend. A lower priority will be used first.'),


This ordering seems counter-intuitive to me at first sight.

@flourish86 What do you think?

This is the same order as menu items internally.

To be fair afaik. it is the first time that a user would have to interact with the number directly.

Al2Klimov · 2026-04-15T15:02:07Z

+        $this->addContent($table);
+    }
+
+    public function backendAction(): void


Being able to rename a backend would be nice. See Icinga/icinga-sso-web#3

I would leave that up to Icinga/icingaweb2#5480

Shouldn't be necessary if you use random IDs as section keys like Icinga/icinga-sso-web#3.

I don't think randomize IDs are necessary here. They make the config file hard to read and probably cause problems with configuration management. The INI section name is usually the name if the resource, so I implemented this exact behaviour in ~~Icinga/icingaweb2#5480~~ Icinga/icingaweb2#5567.

Al2Klimov · 2026-04-15T15:04:35Z

+        $this->addContent($table);
+    }
+
+    public function backendAction(): void


Being able to deactivate a backend temporarily for testing would be nice, but I guess changing priorities will do it as well. You decide.

Implemented

On some distributions (e.g. Fedora), `/usr/bin/chromium-browser` is a shell wrapper that adds `--enable-sync` to Chrome's flags and reroutes stderr through a buffering subprocess: ```bash exec 2> >(exec cat >&2) ``` This creates a double-pipe between Chrome and PHP with a combined buffer of ~128 KB. `--enable-sync` causes Chrome to emit verbose startup logging that fills this buffer. Chrome's IO thread handles both stderr writes and the DevTools HTTP server, so once the buffer is full the entire DevTools protocol stalls -- `getJsonVersion()` would hang for up to 60 seconds until Chrome finished writing. Fix: after the DevTools socket is found, drain the stderr pipe in a loop while probing the HTTP endpoint with short timeouts. Once Chrome responds, close the read end of the pipe. Chrome ignores SIGPIPE, so subsequent stderr writes fail silently without blocking. To support this, ShellCommand gains three methods: `getStderrPipe()` to expose the pipe resource for external draining, `getStderr()` to retrieve accumulated output after `wait()` returns (used for startup failure diagnostics), and `closeStderrPipe()` to close the pipe without stopping the process. `stop()` is guarded against double-close in case `closeStderrPipe()` was called first.

Google Chrome and Fedora's chromium-browser both route Chrome's stderr through a process substitution `(exec 2> >(exec cat >&2))`. This caused two failures: - Fedora: cat filled the pipe buffer, blocking Chrome's IO thread - Ubuntu Chrome 152: closing PHP's read end sent SIGPIPE to cat, making Chrome's FD2 return EPIPE Fix: append `2>/dev/null` to the Linux command line so cat's output goes to `/dev/null`, preventing both blocking and EPIPE. Since stderr is now discarded, switch from stderr regex parsing to polling Chrome's DevToolsActivePort file for the DevTools port and browser ID.

IcingaWeb2 passes a null title when the view has no title set. `setTitle()` and `getTitle()` now accept and return `?string.`

Ubuntu 26.04's apache2 systemd unit sets `MemoryDenyWriteExecute=yes`, which blocks Chrome's V8 JIT and kills the renderer. Add a section with diagnosis and the systemd drop-in fix.

Al2Klimov

.

Al2Klimov · 2026-09-03T13:32:27Z

+
+        switch ($type) {
+            case 'remote_chrome':
+                $this->addElement('text', 'host', [


So, you conditionally add elements, but no hidden ones? This can lose values on toggling type.

Al2Klimov · 2026-09-03T14:02:15Z

+                            }
+
+                            try {
+                                $chrome = (HeadlessChromeBackend::createLocal($value));


Suggested change

$chrome = (HeadlessChromeBackend::createLocal($value));

$chrome = HeadlessChromeBackend::createLocal($value);

Al2Klimov · 2026-09-03T14:10:40Z

+cat >/etc/yum.repos.d/google-chrome-stable.repo <<EOF
+[google-chrome-stable]
+name=google-chrome-stable
+baseurl=http://dl.google.com/linux/chrome/rpm/stable/\$basearch


Suggested change

cat >/etc/yum.repos.d/google-chrome-stable.repo <<EOF

[google-chrome-stable]

name=google-chrome-stable

baseurl=http://dl.google.com/linux/chrome/rpm/stable/\$basearch

cat >/etc/yum.repos.d/google-chrome-stable.repo <<'EOF'

[google-chrome-stable]

name=google-chrome-stable

baseurl=http://dl.google.com/linux/chrome/rpm/stable/$basearch

Al2Klimov · 2026-09-03T14:14:06Z

+
+yum makecache


Suggested change

yum makecache

Al2Klimov · 2026-09-03T15:03:04Z

+    private function registerEvent($method, $params): void
+    {
+        if (Logger::getInstance()->getLevel() === Logger::DEBUG) {
+            $shortenValues = function ($params) use (&$shortenValues) {


Looks like the ideal case for a class method.

Al2Klimov · 2026-09-03T15:24:21Z

+
+    public function isSupported(): bool
+    {
+        // TODO: Come up with a check


Good idea, let's do this!

Al2Klimov · 2026-09-03T15:25:28Z

-    public static function getPort()
-    {
-        return Config::module('pdfexport')->get('chrome', 'port', 9222);
+        return $this->locator;


??= strikes again...

Al2Klimov · 2026-09-03T15:26:08Z

-            return $this->chrome()->getVersion() >= 59;
+            return $locator->getFirstSupportedBackend() !== null;
        } catch (Exception $e) {
+            Logger::warning("No supported PDF backend available.");


Suggested change

Logger::warning("No supported PDF backend available.");

Logger::warning('No supported PDF backend available.');

Al2Klimov · 2026-09-03T15:38:01Z

+        fulfill(e.detail);
+    };
+
+    const timeoutId = setTimeout(() => {


Can we put this below?

Otherwise it's like, oh, you removeEventListener... which event listener? Ah, yes, there's one below!

cla-bot Bot added the cla/signed label Mar 13, 2026

TheSyscall force-pushed the webdriver branch 2 times, most recently from cf3eb8d to 1a6156a Compare March 13, 2026 11:18

TheSyscall self-assigned this Mar 19, 2026

TheSyscall marked this pull request as ready for review March 19, 2026 08:26

TheSyscall requested a review from Al2Klimov March 19, 2026 08:26

This comment was marked as resolved.

Sign in to view

TheSyscall force-pushed the webdriver branch from e870efa to b08e5e2 Compare April 7, 2026 12:38

TheSyscall requested a review from Al2Klimov April 7, 2026 12:48

TheSyscall mentioned this pull request Apr 8, 2026

Add ConfigForm based on CompatForm Icinga/icingaweb2#5480

Merged

sukhwinder33445 mentioned this pull request Apr 9, 2026

Switch back to using syncronous pdf export Icinga/icingaweb2-module-reporting#275

Merged

Al2Klimov mentioned this pull request Apr 15, 2026

Introduce missing first and htmlToPdf methods to PdfexportHook Icinga/icingaweb2#5491

Merged

Al2Klimov reviewed Apr 15, 2026

View reviewed changes

Al2Klimov self-requested a review April 15, 2026 16:03

TheSyscall force-pushed the webdriver branch from e553152 to 5864d1f Compare April 16, 2026 09:53

Al2Klimov removed their request for review April 16, 2026 10:55

Al2Klimov mentioned this pull request May 18, 2026

Allow custom csp header Icinga/icingaweb2#5477

Merged

TheSyscall force-pushed the webdriver branch from 06126b5 to 241036d Compare June 23, 2026 14:14

Remove ReactPHP

e66fd6b

TheSyscall force-pushed the webdriver branch 2 times, most recently from 3fd2c34 to d19553a Compare August 31, 2026 06:47

TheSyscall requested a review from Al2Klimov August 31, 2026 08:27

TheSyscall added 3 commits September 2, 2026 12:57

Convert the HeadlessChrome class into a PdfPrintDriver

8847aeb

Add types to printable html document

f1dbfe3

Use str_starts_with whereever possible

5ec93d6

TheSyscall added 20 commits September 2, 2026 12:57

Use new ConfigSectionForm

c8ee3eb

Code review changes

e37e127

Show a different name on rename

6964ef9

Update first method to mirror parent

9c945d8

Add option to disable a backend

c6fae99

Update to new ConfigSectionForm constructor

2ecaf1d

fixup! Properly log error and remove Hook::has guard

324a698

fixup! Remove extra log message

d7f3243

Update to new ConfigSectionForm

73f5e33

Rework wait-for-layout

4586699

Add docstrings

fc9aedc

f! code format

47fa6f7

f! Remove duplicate closeBrowser() call

114906e

f! captured full regex instead of matched parts

b8e5d52

f! Make compatible with new config section form implementation

65986f2

Allow null on document title

f9a2d00

IcingaWeb2 passes a null title when the view has no title set. `setTitle()` and `getTitle()` now accept and return `?string.`

Add CSRF counter-measure to backend config form

c25f348

Document systemd MemoryDenyWriteExecute workaround for Ubuntu

e2b7bbe

Ubuntu 26.04's apache2 systemd unit sets `MemoryDenyWriteExecute=yes`, which blocks Chrome's V8 JIT and kills the renderer. Add a section with diagnosis and the systemd drop-in fix.

This comment was marked as resolved.

Sign in to view

TheSyscall added 4 commits September 2, 2026 14:50

Don't set a timeout to immediately clear

6c96603

Remove centOS from the documentation

1e7da88

f! fix typo

2dd01ea

Remove troubleshooting steps

c0b9766

TheSyscall force-pushed the webdriver branch from d19553a to c0b9766 Compare September 2, 2026 14:12

f! Use constructor property promotion

bd6a94e

TheSyscall force-pushed the webdriver branch from f6544d1 to bd6a94e Compare September 2, 2026 14:19

TheSyscall requested a review from Al2Klimov September 3, 2026 10:34

Al2Klimov reviewed Sep 3, 2026

View reviewed changes

	$chrome = (HeadlessChromeBackend::createLocal($value));
	$chrome = HeadlessChromeBackend::createLocal($value);

	Logger::warning("No supported PDF backend available.");
	Logger::warning('No supported PDF backend available.');

Uh oh!

Conversation

TheSyscall commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Requires

WebDriver

Currently supported features:

Known issues

Uh oh!

This comment was marked as resolved.

Uh oh!

TheSyscall commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

TheSyscall commented Mar 23, 2026

Uh oh!

sukhwinder33445 commented Apr 10, 2026

Uh oh!

TheSyscall commented Apr 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheSyscall May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

Al2Klimov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

TheSyscall commented Mar 13, 2026 •

edited

Loading

TheSyscall commented Mar 19, 2026 •

edited

Loading

TheSyscall May 11, 2026 •

edited

Loading