restruct/docsys-tools

Portable set of FUSE/DocSys CLI tools

1.0.0 2025-09-17 11:03 UTC

Requires

• restruct/dot-static: @stable

MIT

README

Helper module for various binaries required for FUSE/DocSys:

DHUB + FUSE dependencies

• wkhtmltopdf (with patched QT, 0.12.6 fallbacks for Ubuntu 16/20 & OSX included)
• cpdf (included)

FUSE dependencies

• pdfinfo (included)
• pdftopng (included)
• convert (Image/GraphicsMagick)
• gs (Ghostscript)
• dot (Graphviz, installed as dependency)

FUSETOOLS dependencies

• soffice (CLI LibreOffice)

Update constants from version 0.* to 1.*

• DocSysTools\DocSysTools::init() renamed to init_paths()
• removed/replaced XPDF_BIN_PATH with PDFTOPNG_PATH
• changed GRAPHVIZ_DOT_PATH to DOT_PATH

Configuration

No configuration necessary, to detect & define contants for the paths of above cli tools:

DocSysTools\DocSysTools::init_paths();

Set required systems (DHUB/FUSE/FUSETOOLS) to halt execution if a certain tool for a system cannot be found:

DocSysTools\DocSysTools::init_paths(['DHUB', 'FUSE']);

To save running a few shell commands (to detect arch, OS + version), define these as constants:

define('DOCSYS_ARCH', 'arm64'); # arm64 / x86_64
define('DOCSYS_OS_NAME', 'macOS'); # Ubuntu / Debian / macOS

# Only for Ubuntu and if no system-installed wkhtmltopdf:
define('DOCSYS_OS_VERSION', 16); #  16 / 20

Required: wkhtmltopdf with PATCHED QT (for predictable PDFs)

In case of unexpected scaling issues (and/or other unpredictable behaviour such as random missing images etc) in generated PDFs, make sure you're using a wkhtmltopdf with patched QT:

wkhtmltopdf -V # should include "wkhtmltopdf [...] (with patched qt)"

Or in your php code (eg on dev/build task):

DocSysTools::check_wkhtml_patched($errorOnNonPatchedQT=false); // true to throw an error on unpatched QT

Installation of non-included tools/binaries (wkhtmltopdf, convert, gs & soffice)

How to install wkhtmltopdf 0.12.6 (WITH PATCHED QT!) on Ubuntu/Debian

# Remove 'normal' (non-patched QT version) if required
sudo apt-get remove wkhtmltopdf 
sudo apt autoremove

# Download latest release (jammy/22.04 release also works for noble/24.04)
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb

# Install dependencies
sudo apt-get update
sudo apt-get install -y libfontconfig1 libfreetype6 libx11-6 libxext6 libxrender1 xfonts-75dpi xfonts-base

apt-get install libfontenc1 xfonts-75dpi xfonts-base xfonts-encodings xfonts-utils openssl build-essential libssl-dev libxrender-dev git-core libx11-dev libxext-dev libfontconfig1-dev libfreetype6-dev fontconfig -y

# Install wkhtmltopdf
sudo dpkg -i wkhtmltox_0.12.6.1-3.jammy_amd64.deb
sudo apt-get install -f

# Check that wkhtmltopdf with patched QT got installed
wkhtmltopdf -V # should return "wkhtmltopdf 0.12.6.1 (with patched qt)"

# In case dpkg throws errors you may need to run
sudo apt --fix-broken install

# On Debian 12, libjpeg-turbo8 may be missing;
wget http://mirrors.kernel.org/ubuntu/pool/main/libj/libjpeg-turbo/libjpeg-turbo8_2.1.2-0ubuntu1_amd64.deb
sudo apt install ./libjpeg-turbo8_2.1.2-0ubuntu1_amd64.deb

For other operating systems, see this guide, in case of troubles you may find a solution here

(Some) wkhtmltopdf fallbacks included in this module

For environments where installing is not an option (eg shared hosting), fallbacks for Ubuntu 16 & 20 and OSX (Intel/rosetta) are included. Static builds were discontinued after 0.12.4 because of library version issues between systems so the included 0.12.6 versions may work if all required libs happen to be available on your system.

convert (ImageMagick/GraphicsMagick)

A convert binary will already be installed on most systems, if not you may install either ImageMagick or its more actively maintained fork GraphicsMagick. Most convenient is probably to install the compat metapackage, "a compatibility package for Ubuntu that provides the ImageMagick-compatible command-line interface for the GraphicsMagick image processing suite, allowing you to replace ImageMagick with the more stable and performant GraphicsMagick without code changes":

apt-get install graphicsmagick-imagemagick-compat

gs (Ghostscript)

gs will probably already be installed, if not:

sudo apt-get install ghostscript

soffice (LibreOffice headless)

soffice is LibreOffice's command line tool. The full LibreOffice suite pulls in X11 and lots of other dependencies you don't want on a server (may take up 1.5GB).

Instead libreoffice-core-nogui could be installed along with specific libreoffice-[tool]-nogui packages you want to be able to convert (315MB, see individual package options below):

apt-get install libreoffice-core-nogui libreoffice-writer-nogui libreoffice-impress-nogui libreoffice-draw-nogui --no-install-recommends --no-install-suggests

For the full set of tools and broadest document type support, just install libreoffice-nogui (about 364MB, the --no-* flags exclude X11 and reduce the amount of other dependencies):

apt-get install libreoffice-nogui --no-install-recommends --no-install-suggests

This installs (nogui versions):

• libreoffice-writer: Word processor
• libreoffice-calc: Spreadsheet
• libreoffice-impress: Presentation
• libreoffice-draw: Drawing
• libreoffice-base: Database
• libreoffice-math: Equation editor

DEV NOTES:

(Legacy) wkhtmltopdf static build (0.12.4)

0.12.4 can still just be downloaded and works (up untill Ubuntu 16.04, statically linked generic version); https://github.com/wkhtmltopdf/wkhtmltopdf/releases/0.12.4/

.deb extraction

(https://www.cyberciti.biz/faq/how-to-extract-a-deb-file-without-opening-it-on-debian-or-ubuntu-linux/)
unzipped & unzipped data.tar.xz, copied usr/local dir to docsys-tools/wkhtmltopdf-amd64-0.12.6-UbuntuXX.YY

Wkhtmltopdf (dynamically linked)

0.12.6 amd64 .deb for Ubuntu 16.04 and 20.04 works IF ALL requirements happen to be installed (download and extract from .deb, dynamically linked); https://wkhtmltopdf.org/downloads.html

(OSX) make (wkhtmltopdf) binaries executable

chmod +x /path/to/file

(OSX) “wkhtmltopdf” cannot be opened because the developer cannot be verified.

To remove the quarantine attribute from executable files on OSX: xattr -d com.apple.quarantine /path/to/file