The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Use the API that matches your installation. “phpwkhtmltoimage” can mean the mikehaertl/phpwkhtmltopdf wrapper’s Image class or the separate wkhtmltoxImageConverter PHP extension. Their option names and calling conventions differ. This guide shows both, explains format, transparency, crop, sizing, JavaScript loading and error handling, and includes runnable examples.
Identify your PHP interface first
Before changing an option, determine which library your project actually uses. The wrapper creates an Image object and accepts an associative array either in the constructor or through setOptions(). The extension creates a wkhtmltoxImageConverter with a settings array. Code written for one interface should not be copied into the other.
mikehaertl/phpwkhtmltopdf wrapper
Typical wrapper code looks like this:
use mikehaertlwkhtmltoImage;
$image = new Image([
'url' => 'https://example.com',
]);
$image->saveAs('/tmp/example.png');You can also create the object first and then call $image->setOptions($options). Keep the option array in the wrapper’s documented format for the version installed in your project.
wkhtmltox Image Converter extension
The extension uses a settings array when constructing the converter:
#1 Best Overall
$settings = [
'fmt' => 'png',
'screenWidth' => 1280,
'smartWidth' => false,
];
$converter = new wkhtmltoxImageConverter($settings);The examples below label the interface they target. Check the documentation shipped with your installed version before deploying, because package versions can expose different keys.
Choose the output format and quality
Decide the output format before tuning layout. PNG and SVG are the documented choices when you need transparency; JPEG is useful when a smaller, lossy file is acceptable. The extension documents quality for JPEG compression, with 94 shown as its example/default value.
| Format | Use it when | Important options |
|---|---|---|
| PNG | You need lossless output, crisp text or transparent pixels. | fmt => 'png'; transparent => true for transparency. |
| SVG | Your workflow accepts vector output and requires transparency. | fmt => 'svg'; transparent => true. |
| JPEG | You prefer a smaller lossy image for photographs or previews. | fmt => 'jpg'; set quality to the desired compression level. |
| BMP | A downstream tool specifically requires BMP. | fmt => 'bmp'. |
Extension example: PNG with transparency
$settings = [
'fmt' => 'png',
'transparent' => true,
];
$converter = new wkhtmltoxImageConverter($settings);
$converter->convert('https://example.com', '/tmp/example.png');Transparency applies to PNG or SVG output in the documented extension settings. It does not turn a JPEG into a transparent image.
Extension example: JPEG quality
$settings = [
'fmt' => 'jpg',
'quality' => 94,
];
$converter = new wkhtmltoxImageConverter($settings);
$converter->convert('https://example.com', '/tmp/example.jpg');Quality is a compression control, not a display-size control. Change dimensions separately with screen or crop settings.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteControl the captured rectangle with crop settings
The extension’s crop.left, crop.top, crop.width and crop.height define a pixel-based rectangle. Use them when you need a region rather than the whole rendered page.
$settings = [
'fmt' => 'png',
'crop.left' => 120,
'crop.top' => 80,
'crop.width' => 900,
'crop.height' => 500,
];
$converter = new wkhtmltoxImageConverter($settings);
$converter->convert('https://example.com/dashboard', '/tmp/panel.png');- left and top move the rectangle’s origin in pixels.
- width and height set the rectangle’s size in pixels.
- Capture coordinates refer to the rendered page, so changing zoom or screen width can move the same element.
The command-line tool exposes analogous controls as --crop-x, --crop-y, --crop-w and --crop-h. Do not assume those spellings are valid PHP array keys; use the names documented by your PHP interface.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Set viewport width and smart-width behavior
Responsive pages choose breakpoints from the rendering width. Set a screen width that matches the layout you want, then decide whether content is allowed to expand beyond it.
Extension settings
$settings = [
'fmt' => 'png',
'screenWidth' => 1440,
'smartWidth' => false,
];
$converter = new wkhtmltoxImageConverter($settings);
$converter->convert('https://example.com', '/tmp/desktop.png');screenWidth establishes the rendering width. smartWidth controls whether the renderer expands to the content width. Disable smart width when you need a predictable viewport for visual comparisons; enable it when the page’s content should determine the final width.
CLI equivalent and its limitation
The CLI provides --width and related controls, but its manual describes width as a guide unless smart width is disabled. Therefore a command using only --width may not produce the exact pixel width you expect. Match the CLI behavior to your PHP interface rather than mixing option names.
Make late content appear: JavaScript and loading controls
A screenshot can be technically successful while missing content that has not loaded yet. The extension documents these settings:
load.jsdelay: wait a specified period for scripts and late-rendered elements.load.zoomFactor: change the rendering scale, which also affects apparent dimensions.load.loadErrorHandling: choose what to do when a resource fails.web.enableJavascript: enable or disable JavaScript execution.web.loadImages: include or suppress image loading.web.background: control background rendering.web.minimumFontSize: enforce a minimum text size.web.defaultEncoding: set the page’s default character encoding.web.userStyleSheet: apply a stylesheet during rendering.
Example for a JavaScript-rendered page
$settings = [
'fmt' => 'png',
'web.enableJavascript' => true,
'web.loadImages' => true,
'load.jsdelay' => 1500,
'load.zoomFactor' => 1.0,
];
$converter = new wkhtmltoxImageConverter($settings);
$converter->convert('https://example.com/app', '/tmp/app.png');Use the smallest delay that consistently allows the page to settle. A delay cannot repair a blocked request, an application error or a selector that never renders. For CLI workflows, --window-status can wait for a specified window status value instead of relying only on a fixed delay.
Handle load failures deliberately
The extension documents three load-error behaviors: abort, skip and ignore. Select one according to the job’s purpose.
Rank #3
| Behavior | Best fit | Trade-off |
|---|---|---|
abort |
Invoices, compliance captures and tests where incomplete output is unacceptable. | One failed resource can stop conversion. |
skip |
Batch work where an individual failed object should be omitted. | The skipped item will not be represented in the result. |
ignore |
Pages where a non-critical asset may fail but the remaining image is useful. | You can receive output that lacks part of the page. |
$settings = [
'fmt' => 'png',
'load.loadErrorHandling' => 'ignore',
];
$converter = new wkhtmltoxImageConverter($settings);
$converter->convert('https://example.com', '/tmp/tolerant.png');For reliable automation, record which policy was used and inspect the resulting file rather than treating a returned file as proof that every resource loaded.
Complete extension configuration example
This example combines format, transparency, viewport, crop, resource loading and error handling. Remove settings you do not need; fewer moving parts make troubleshooting easier.
$settings = [
'fmt' => 'png',
'transparent' => true,
'screenWidth' => 1280,
'smartWidth' => false,
'crop.left' => 0,
'crop.top' => 0,
'crop.width' => 1280,
'crop.height' => 900,
'load.jsdelay' => 1000,
'load.zoomFactor' => 1.0,
'load.loadErrorHandling' => 'abort',
'web.background' => true,
'web.loadImages' => true,
'web.enableJavascript' => true,
];
$converter = new wkhtmltoxImageConverter($settings);
$converter->convert('https://example.com', '/tmp/capture.png');If this fails, reduce it to fmt and the URL, verify that basic conversion works, then add one setting at a time.
Wrapper configuration pattern
For mikehaertl/phpwkhtmltopdf, keep options in the associative array accepted by the wrapper and set them either at construction or with setOptions():
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
use mikehaertlwkhtmltoImage;
$options = [
'url' => 'https://example.com',
// Add only option names supported by your installed wrapper version.
];
$image = new Image($options);
// Alternatively:
// $image = new Image();
// $image->setOptions($options);
if (!$image->saveAs('/tmp/example.png')) {
throw new RuntimeException($image->getError());
}The wrapper’s option vocabulary is not automatically identical to the extension’s dotted keys. Confirm the wrapper documentation and the installed wkhtmltoimage binary before adding format, crop, width or JavaScript flags.
Common problems and fixes
The option is ignored
Cause: a CLI flag or extension key was placed in the wrapper array, or vice versa. Fix: identify the interface, consult its option list and test one key in isolation.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
The image is blank or missing pictures
Cause: JavaScript or image loading is disabled, the delay is too short, or a resource request failed. Fix: enable web.enableJavascript and web.loadImages, increase load.jsdelay modestly, and choose an explicit load-error policy.
The width is not exact
Cause: smart-width expansion or zoom changed the rendered dimensions. Fix: set screenWidth, disable smart width when a fixed viewport matters, set load.zoomFactor deliberately and verify crop dimensions.
Recommended Free Tools
Transparency produces a white background
Cause: the output format does not support the documented transparency setting, or the page itself paints a white background. Fix: use PNG or SVG, set transparent to true, and check the page’s CSS background.
Characters render incorrectly
Cause: an unsuitable default encoding or unavailable font. Fix: set web.defaultEncoding appropriately, ensure fonts are reachable in the conversion environment and capture after fonts have loaded.
Conversion aborts on a minor asset
Cause: load.loadErrorHandling is set to abort. Fix: use skip or ignore only when incomplete output is acceptable.
Performance and reliability checklist
- Start with the smallest option set that reproduces the required image.
- Use a fixed screen width and zoom when outputs are compared across runs.
- Prefer a readiness strategy that reflects the page: a bounded JavaScript delay for predictable pages, or a window-status signal in CLI workflows when the page provides one.
- Do not enable image loading or JavaScript unnecessarily for static pages.
- Use crop settings to reduce output area only after confirming the element’s position at the chosen viewport.
- Choose
abortfor correctness-critical captures and a tolerant policy for best-effort batches. - Keep the PHP package, extension and wkhtmltoimage binary versions recorded together; option availability can vary.
- Validate output dimensions, file type and transparency in an automated post-conversion check.
Or skip the browser setup
If your goal is simply a dependable website screenshot rather than configuring a local wkhtmltoimage stack, ScreenshotNeo provides a GET endpoint and an MCP server for AI clients. Cookie and consent banners, newsletter popups and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and the response reports the page verdict and billing status in headers.
One request is enough (see the ScreenshotNeo API documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Frequently Asked Questions
Can I use extension keys such as screenWidth in the mikehaertl wrapper?
Not automatically. The wrapper and the wkhtmltox extension are separate interfaces; verify the wrapper’s option names for your installed version.
Which setting controls JPEG file size?
The extension’s quality setting controls JPEG compression. It does not set the rendered width or height.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsShould I use a delay or window status?
Use a bounded JavaScript delay when a predictable wait is sufficient. In CLI workflows, window-status can wait for an explicit readiness value exposed by the page.
The Bottom Line
Configure the interface you actually installed, then tune format, viewport, crop, loading and error handling independently. Never copy CLI flags or extension keys into a PHP wrapper array without checking that API’s documented option names.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
