Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Set PDF whitespace in KnpSnappyBundle with wkhtmltopdf’s four margin options: margin-top, margin-bottom, margin-left, and margin-right. Put them under the PDF service’s options in app/config/config.yml, using explicit units such as 2cm, then regenerate a PDF and inspect every edge. The exact configuration tree and any per-render PHP methods depend on the KnpSnappyBundle and Snappy versions locked by your Symfony2 application.
Set all four margins in Symfony2
For a traditional Symfony2 application, the historically relevant file is app/config/config.yml. Configure the PDF service like this:
knp_snappy:
pdf:
enabled: true
binary: /usr/local/bin/wkhtmltopdf
options:
margin-top: 2cm
margin-bottom: 2cm
margin-left: 2cm
margin-right: 2cmEach value is a size, not a percentage or a bare integer. wkhtmltopdf accepts units such as cm; the official API reference uses 2cm as an example. Choose a value that matches your document rather than copying the example blindly.
margin-topcontrols whitespace above the page content.margin-bottomcontrols whitespace below the content.margin-leftcontrols the inner edge on the left.margin-rightcontrols the inner edge on the right.
After changing configuration, clear the Symfony cache for the environment that generates the PDF, restart any long-running worker that has loaded the old container, and render a new file. A PDF already written to disk will not change when the YAML changes.
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 errorsCheck the paths and versions before changing YAML
Confirm the binary path
binary must point to the wkhtmltopdf executable available to the PHP process, not merely to a binary on your development shell’s PATH. Check the path and permissions as the same operating-system user that runs PHP-FPM, Apache, or your queue worker. A valid-looking margin configuration cannot help if the converter cannot be started.
Confirm the bundle configuration tree
Current KnpSnappyBundle documentation shows a newer Symfony layout, with the same binary and options nested below pdf in config/packages/knp_snappy.yaml. Symfony2 projects normally use app/config/config.yml, but the installed bundle version is authoritative. If Symfony reports an unknown root key or option, inspect that version’s configuration definition and README rather than copying a current example into a legacy project.
Check the dependency lock
Do not infer Symfony2 support from a current package release. Packagist lists KnpSnappyBundle 1.10.6, published January 7, 2026, as requiring PHP 8.1 or newer and Symfony FrameworkBundle ^5.1|^6.0|^7.0|^8.0. Those requirements do not establish compatibility with Symfony2. Keep the project’s pinned KnpSnappyBundle, Snappy library, and wkhtmltopdf versions together, and consult their version-specific documentation before upgrading any one of them.
Rank #2
Understand what the setting changes
PDF margins are global page settings
The four options set the printable content rectangle for each generated page. They are useful when every page needs the same border, when a printer requires a safe area, or when headers and footers need room. If the content is wider or taller than the available rectangle, wkhtmltopdf may wrap, overflow, or create additional pages.
CSS margins are different
CSS controls the layout of elements inside the HTML document. The wkhtmltopdf options control page-level whitespace. Keep those responsibilities separate: use the PDF options for the page boundary and CSS for spacing between headings, tables, cards, and other elements. The precise interaction can vary with the wkhtmltopdf build and document styles, so verify the rendered result instead of assuming that a CSS margin and a PDF margin combine in a particular way.
Use units deliberately
Write the unit with every value, for example 15mm, 0.75in, or 2cm. A unitless value is ambiguous and can be rejected or interpreted unexpectedly by a particular wrapper or binary. Use the same unit family across all four edges when the document must be symmetrical.
Apply margins for one render when your pinned API supports it
Bundle-wide YAML is the safest documented route for a Symfony2 installation. Some Snappy versions also expose per-render option methods or an options argument, allowing one document to use different margins without changing the container. The exact method signature is version-dependent and is not established for every historical Symfony2 combination.
Before using a per-render call, inspect the installed Snappy class or its version-matched documentation. A typical pattern in versions that expose setOption is:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →<?php
$pdf = $this->get('knp_snappy.pdf');
$pdf->setOption('margin-top', '2cm');
$pdf->setOption('margin-bottom', '2cm');
$pdf->setOption('margin-left', '2cm');
$pdf->setOption('margin-right', '2cm');
$content = $pdf->getOutputFromHtml($html);
return new SymfonyComponentHttpFoundationResponse(
$content,
200,
array('Content-Type' => 'application/pdf')
);Treat this as an API-shape check, not a promise that every old release has the method. If the method is absent, put the values in the YAML configuration or use the options mechanism documented by your locked Snappy release. Do not silently mix a per-render option API from a newer package with a Symfony2-era bundle.
Rank #4
Choose and verify a margin set
- Start with a known page size and a simple test page containing a border, a heading at the top, a footer at the bottom, and a wide table.
- Set all four options explicitly. Leaving one side at a binary default makes later comparisons difficult.
- Render the same HTML before and after the change.
- Measure the visible content edge in a PDF viewer or print proof. Check the first and last page, not only a middle page.
- Inspect long headings, tables, images, headers, and footers for wrapping or clipping.
- Record the binary version, bundle version, margin values, and page size with the deployment configuration so another environment can reproduce the output.
If only one edge needs adjustment, keep the other three at explicit values rather than relying on defaults. For example, a report with a binding gutter might use a larger left margin while retaining equal top, bottom, and right values.
Headers, footers, and page size
Headers and footers consume space near the page edges. Reserve enough top or bottom margin for them and verify that the first and last lines do not overlap. A margin change does not itself change A4 to A1 (or any other paper size); page size is a separate wkhtmltopdf option and must be checked against the option set supported by your installed binary and wrapper. When changing both, test them together because a larger sheet changes the available content rectangle.
Troubleshoot margin problems
“The option is unknown” or the container will not compile
- Cause: the YAML shape belongs to a different KnpSnappyBundle generation, or the key is outside the
pdfsection. - Fix: compare the configuration tree supplied by the installed bundle; in Symfony2, start with
app/config/config.ymland keepoptionsnested underpdf.
The PDF looks unchanged
- Cause: Symfony cache, a long-running worker, or a pre-generated PDF still contains the old configuration.
- Fix: clear the correct environment cache, restart workers, generate a new file, and confirm that the request uses the PDF service you edited.
Margins work locally but not in production
- Cause: different wkhtmltopdf binaries, different bundle locks, or a PHP user that cannot execute the configured binary.
- Fix: compare versions and paths on both hosts, run the converter as the service user, and check application logs for process-start or permission errors.
Content is clipped or unexpectedly reflows
- Cause: the margins leave too little space for the HTML, a table has a fixed width, or CSS and page-level spacing interact differently in the deployed build.
- Fix: reduce the content width, allow table wrapping, adjust the relevant edge, and test a representative long document. Do not solve a page-level problem only by adding arbitrary CSS padding.
The per-render PHP example fails
- Cause: the installed Snappy API does not provide
setOptionor expects options in a different argument. - Fix: inspect the pinned class signature and use the documented method for that release, or move the values to bundle configuration.
Only some pages have the wrong whitespace
- Cause: page content changes height, a header or footer appears conditionally, or a page-break rule moves content.
- Fix: compare the HTML and CSS on the affected page, then render a minimal reproduction with the same options. The four margin values apply to the PDF pages globally; they do not target an individual HTML element.
Deployment and maintenance checklist
- Pin and document the KnpSnappyBundle, Snappy, and wkhtmltopdf versions.
- Use an executable binary path available to the production PHP user.
- Set all four margins with explicit units.
- Keep PDF page margins distinct from CSS layout margins.
- Clear cache and restart workers after configuration changes.
- Render a test PDF covering first-page, middle-page, last-page, tables, images, and headers or footers.
- Recheck output after any converter, operating-system, or bundle upgrade.
Or skip the browser setup
If your actual requirement is a clean image of a web page rather than a wkhtmltopdf PDF, ScreenshotNeo provides a single HTTP request. It accepts cookie and consent banners as a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets before capture, and lets you turn each cleanup step off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
For a screenshot, see the ScreenshotNeo API documentation and run:
Best Value
- Used Book in Good Condition
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same request in PHP uses cURL:
<?php
$url = 'https://api.screenshotneo.com/v1/shot';
$query = http_build_query(array(
'access_key' => 'YOUR_API_KEY',
'url' => 'https://stripe.com'
));
$ch = curl_init($url . '?' . $query);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 90);
$body = curl_exec($ch);
if ($body === false) {
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
file_put_contents('shot.webp', $body);Python:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo includes full-page capture, lazy-image loading, CSS-selector element capture, dark mode, device presets, custom viewport and retina scale, PDF controls, custom CSS and JavaScript, clicks, waits, blocking rules, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous webhooks, bulk capture, usage data, and an OpenAPI specification. Every feature is on every plan: 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000, and annual billing provides two months free. Create a free ScreenshotNeo account.
Summary
For Symfony2, define margin-top, margin-bottom, margin-left, and margin-right under knp_snappy.pdf.options in app/config/config.yml, use explicit units such as 2cm, and verify the syntax against the versions your project actually locks. Clear cache, regenerate the PDF, and test edge cases before deploying.
Frequently Asked Questions
Can I use a different margin on just one PDF page?
The four wkhtmltopdf margin options are page-level settings. A per-render override may be possible in some Snappy versions, but a page-specific margin is not established by the bundle configuration itself; use document layout and page-break rules for page-specific content and verify the behavior of your pinned API.
Does changing these options alter the original HTML?
No. The options affect the converter’s PDF page area. Your HTML and CSS remain unchanged, so the same source can be rendered again with another margin set.
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.
