Wkhtmltoimage I386 Laravel Package

Technical Evaluation

Architecture fit

• This is not a library; it is a binary-distribution channel. There is zero PHP code — no service provider, no config, no facade, no API surface. Its only contract is: a file appears at vendor/h4cc/wkhtmltoimage-i386/bin/wkhtmltoimage-i386 with a vendor/bin symlink.
• Therefore architectural fit is decided entirely by the wrapper we choose (typically knplabs/knp-snappy or barryvdh/laravel-snappy shelling out via Symfony Process). The package is a leaf node in the deployment layer, not the application layer.
• The i386 requirement is architectural, not incidental: it presumes a 32-bit userland with i386 shared libraries (glibc, fontconfig, freetype, multiarch enabled). Current targets — x86_64, ARM64 (Graviton, Apple Silicon), musl/Alpine — are not served without a compatibility layer.

Integration feasibility

• Feasible only where (a) infra is genuinely i386 or multiarch, (b) the image is glibc-based (Debian/Ubuntu, not Alpine), and (c) build and runtime stages share the same libc and font stack.
• Laravel wrapping is trivial (~20 lines plus a Snappy adapter; resolve path via base_path('vendor/bin/wkhtmltoimage-i386')). No framework integration is provided, and none is needed.
• The real feasibility question is rendering fidelity: QtWebKit-era 0.12.4 cannot be relied on for modern flexbox/grid, modern JS, HTTP/2, or some TLS 1.3 endpoints. Acceptable for our own static templates; a defect generator for customer-supplied HTML.

Technical risk

• Currency: last release 2018-01-15; upstream 0.12.4-era; QtWebKit is unmaintained and carries known memory-safety and SSRF/local-file-read classes of vulnerability when rendering hostile HTML. 33 stars, 0 dependents, score 2.125 — a dormant artifact, not a maintained project.
• Licensing: LGPL-3.0 binary invoked as a separate process is an aggregate, so obligations are largely notice plus source offer, but QtWebKit's LGPLv3-with-exceptions terms and the exact patch set of the static build are not verifiable from the repo. Legal sign-off required.
• Supply chain: Composer fetches an opaque prebuilt binary from a third-party tag with no checksum verification and no reproducible build. This bypasses normal SBOM/artifact-registry controls.
• Platform decay: 32-bit package availability shrinks every distro cycle; a base-image bump can silently break the binary.
• Correctness hazards: TLS failures on modern sites, blank/partial output with exit code 0, font substitution drift between build and runtime hosts.

Key questions

• Do we actually need i386, or is this copied from an old README? If not, stop here — use the amd64 sibling or the 0.12.6 static build.
• Who supplies the HTML: us, or untrusted third parties? (Determines sandboxing and SSRF exposure.)
• What is the fidelity bar — golden-image regression tests, or human eyeball? Are the source pages JS-heavy?
• Which base image and libc, and is multiarch already enabled in CI and production?
• Can we pin the binary into our own artifact registry with checksum and SBOM entry?
• Can legal review QtWebKit LGPL compliance for a static third-party build?

Integration Approach

Stack fit

• Laravel 8+ on Debian/Ubuntu x86_64 with multiarch: works via laravel-snappy + this binary, but only as a stopgap.
• Alpine/musl, ARM64, or ARM Fargate/Graviton: does not fit without an emulation layer — reject.
• Kubernetes with mixed-architecture node pools: requires nodeSelector/taints to guarantee i386-capable nodes; operationally brittle.

Migration path

• Greenfield: skip this package. Choose spatie/browsershot (headless Chromium) behind a queue job, or a wkhtmltopdf 0.12.6 amd64 static build if Chromium's footprint is prohibitive.
• Already on h4cc/wkhtmltoimage-amd64: do not migrate sideways to i386. Introduce an internal HtmlToImageRenderer interface with a Snappy/Wkhtml adapter and a Browsershot adapter, then move call sites one at a time.
• Already on i386 for legacy reasons: freeze it, containerize it in its own image (pinned distro, pinned libs, fonts baked in), and put the interface in front so the eventual swap never touches call sites.

Compatibility

• The consuming app's PHP version is irrelevant (no PHP code); the binding constraints are glibc version, fontconfig/freetype, and i386 package availability. Composer 1 vs 2 is a non-issue.
• Pin exactly ("0.12.4") with composer.lock committed; no caret ranges on a dormant binary.

Sequencing

1. Week 0 — confirm architecture requirement and obtain legal sign-off.
2. Week 1 — wrap in the renderer interface plus queue job with timeout/retry policy; add golden-image regression tests on the real page corpus.
3. Week 2 — bake binary and fonts into a purpose-built image; add checksum verification in CI.
4. Weeks 2–4 — parallel Browsershot spike; compare fidelity against the same corpus.
5. Weeks 4–6 — cut over behind a config flag; remove the binary dependency.

Operational Impact

Maintenance

• There is no upstream response path: no security fixes will arrive for the binary. "Maintenance" means pinning indefinitely and accepting known CVEs — a standing risk-acceptance entry owned by the platform team, not a maintenance line item.
• Bus factor 1, zero dependents, last tag 2018: treat it as a vendored frozen artifact we now own end-to-end.

Support

• Community-only, no SLA. The internal runbook must cover: missing i386 shared libraries, missing fonts, TLS handshake failures, blank output with exit 0, and hung processes. On-call will see these as user-visible "preview unavailable" tickets unless we alert on stderr patterns rather than exit codes alone.

Scaling

• Process-per-render: roughly hundreds of milliseconds baseline plus CPU-bound rasterization; memory spikes on long pages. Scale horizontally with queue workers, cap concurrency per node, fix --width/--height, and enforce a hard timeout (Symfony Process setTimeout plus SIGKILL fallback for zombie children).
• Because of the i386 constraint we cannot freely use the cheapest current instance families (ARM), which is a real cost and elasticity penalty versus a Chromium-on-ARM alternative.

Failure modes

• Hard: image build fails (no i386 repo), exec format error, missing libfontconfig.so.1 (i386), segfault on large DOM.
• Soft: blank/grey output, missing webfonts, clipped or unscaled layout on modern CSS, stale cached content, non-zero exit with usable output.
• Security: SSRF and local-file inclusion if HTML is user-supplied — run non-root, read-only filesystem, restricted egress, no credentials in the environment.

Ramp-up

• The wrapper is an hour of work; the failure taxonomy is the cost. Engineers must learn wkhtmltoimage flag semantics and QtWebKit rendering limits — knowledge that does not transfer to Chromium tooling. That non-transferable tribal knowledge is the strongest argument to spend the migration budget now rather than accrue more of it.

Recommendation: do not adopt for new work. If wkhtmltoimage is mandated, use the amd64 0.12.6 static build; otherwise migrate to a headless-Chromium renderer behind an internal interface.