Dompdf prints the header or footer once, or draws it over the page text
The header appears on page 1 onlyShort answer
Dompdf repeats only elements with position: fixed. Give the header and footer that style, reserve room for them with @page margins, and pull them into the margin with negative offsets. On Dompdf 3.1.0 and older, also put them at the top of the HTML. A total page count needs embedded PHP.
Fix it fast
1Find out which cause you have
Look at how the header is written in your HTML, and which Dompdf release you run. The release matters for one of the causes below.
grep -n -i "header\|footer" resources/views/pdf/*.php 2>/dev/null composer show dompdf/dompdf2Match what you see, then jump to its fix
- 1
The header shows once at the top of page 1, and the footer once at the end of the last page.The header and footer are normal elements, not fixed onesFix - 2
The header repeats, but it hides the first lines of each page, or it is cut off at the page edge.The fixed header lies on top of the page textFix - 3
The header is missing from the first page, or from the page that follows an earlier page break, and composer show reports 3.1.0 or older.An older Dompdf starts the fixed content on page 1 or page 2Fix - 4
CSS counters show the current page, but there is no way to print the total.The footer should say Page X of YFix
- 1
What does the error look like?
The header appears on page 1 onlyThe footer is missing on page 1 or page 2The fixed header covers the first lines of every pagePage number shows, but no total such as Page 2 of 5
Cause 1 of 4
The header and footer are normal elements, not fixed ones
1Check
In Dompdf an element in the normal flow is printed once, where it sits in the document. Look for a header or footer block that has no position rule.
grep -n -B1 -A4 "#header\|#footer\|class=\"header\"\|class=\"footer\"" resources/views/pdf/*.php 2>/dev/null2Fix
Give the elements position: fixed. Dompdf renders fixed content like absolutely positioned content, and repeats it on every page.
#header { position: fixed; top: 0; left: 0; right: 0; height: 60px; }
#footer { position: fixed; bottom: 0; left: 0; right: 0; height: 40px; }3Verify
Generate a PDF of three or more pages and look at the second and third page.
$dompdf->render();
$dompdf->stream();Confirmed by github.com
Cause 2 of 4
The fixed header lies on top of the page text
1Check
Dompdf positions fixed and absolute elements against the content box, which is the page without its margins. A header at top: 0 therefore starts inside the text area.
grep -n "@page" resources/views/pdf/*.php 2>/dev/null2Fix
Set page margins big enough for the header and footer, then move each element out into the margin with a negative offset.
@page { margin: 100px 50px; }
#header { position: fixed; left: -50px; right: -50px; top: -100px; height: 80px; }
#footer { position: fixed; left: -50px; right: -50px; bottom: -100px; height: 80px; }3Verify
The body text now starts below the header and ends above the footer on every page.
$dompdf->render();
$dompdf->stream();Confirmed by github.com
Cause 3 of 4
An older Dompdf starts the fixed content on page 1 or page 2
1Check
The Dompdf wiki says that in 3.1.0 and earlier, fixed content begins on page 1 or page 2 depending on whether a page break comes before it in the HTML.
composer show dompdf/dompdf | grep -i versions2Fix
Move the header and footer elements to the top of the HTML source, before any content or page break, or update the package.
<body>
<div id="header">...</div>
<div id="footer">...</div>
<main>...</main>
</body>
composer update dompdf/dompdf3Verify
Regenerate the PDF and check page 1 and the page after the first break.
$dompdf->render();
$dompdf->stream();Confirmed by github.com
Cause 4 of 4
The footer should say Page X of Y
1Check
CSS counters give the current page number. The wiki says Dompdf cannot produce the total page count through CSS.
grep -n "counter(page)" resources/views/pdf/*.php 2>/dev/null2Fix
Turn on embedded PHP and draw the text with page_text, which fills in {PAGE_NUM} and {PAGE_COUNT}. The option is off by default and is a security risk for HTML you do not control, so use it only for documents you wrote yourself.
$options = new \Dompdf\Options();
$options->set('isPhpEnabled', true);
$dompdf = new \Dompdf\Dompdf($options);
<script type="text/php">
if (isset($pdf)) {
$font = $fontMetrics->getFont("helvetica");
$y = $pdf->get_height() - 30;
$pdf->page_text(270, $y, "Page {PAGE_NUM} of {PAGE_COUNT}", $font, 9, [0, 0, 0]);
}
</script>3Verify
Every page shows its number and the total.
$dompdf->render();
$dompdf->stream();Confirmed by github.com
How do I stop it coming back?
- Keep header and footer markup in one shared layout file, so every PDF in the project repeats it the same way.
- Test with a document of at least three pages; a one-page sample hides every repeat problem.
- Never turn on isPhpEnabled for HTML that comes from users.
- Check the Dompdf release notes before updating, since page-layout behaviour is what changes between versions.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
DomPDF shows a broken image in a Laravel PDF
Image shows as a broken box in the generated PDF
DomPDF loads images itself, not through the browser.
3 causes, each with a fixBack end
Dompdf prints Cyrillic (or other Unicode) text as question marks or empty boxes
Accented or non-Latin letters are replaced by squares
Dompdf draws each character with the font you give it and does not switch fonts for missing glyphs.
3 causes, each with a fixBack end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack end
Apache returns 403 when a URL contains %3F
a request like /page%3Fname=test is refused while /page?name=test works
Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.
2 causes, each with a fixBack end
Apache returns 500 with Premature end of script headers
500 Internal Server Error
Apache ran your script, but the script printed no valid HTTP header before its output.
3 causes, each with a fixBack end
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fix