Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Dompdf prints the header or footer once, or draws it over the page text

ErrorThe header appears on page 1 only

Short 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.

  • Applies to Dompdf 3.x, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/dompdf
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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. 3The 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. 4CSS counters show the current page, but there is no way to print the total.The footer should say Page X of YFix

What does the error look like?

  • The header appears on page 1 only
  • The footer is missing on page 1 or page 2
  • The fixed header covers the first lines of every page
  • Page 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/null

2Fix

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

Did this fix it?

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/null

2Fix

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

Did this fix it?

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 versions

2Fix

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/dompdf

3Verify

Regenerate the PDF and check page 1 and the page after the first break.

$dompdf->render();
$dompdf->stream();

Confirmed by github.com

Did this fix it?

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/null

2Fix

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

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.