Why Inline PHP Breaks Page Numbering in DomPDF
Getting a custom HTML string to render correctly in dompdf is straightforward, but adding dynamic page numbers or headers often trips up developers who rely on inline PHP logic to generate that HTML. The core issue isn't that you can't use PHP in your template; it's how dompdf processes the content versus what your browser expects.
When you use a function like getView() to render a view file and capture the output via ob_start() and ob_get_clean(), you are generating a complete, static HTML string. This string is then passed directly to DOMPDF::load_html(). Once that method is called, the content is handed over to the PDF rendering engine. At this specific point in time, no PHP execution occurs within the rendered document. The variables inside your <h1> tags must have already been resolved by your PHP script before the string reaches dompdf.
If you attempt to use a tag like <?php echo $pageNumber; ?> directly inside the HTML passed to load_html(), it will render as literal text: "PHP echo $page". This is because dompdf does not execute PHP code; it parses CSS and renders HTML tags. It has no access to your application's session data, database connections, or global variables unless they are explicitly embedded in the string before rendering begins.
To achieve page numbers, you must leverage DOMPDF's native header and footer mechanism, which operates independently of the main document body. This is where the standard FAQ advice often causes confusion because it relies on specific configuration settings that don't work if your HTML structure doesn't match expectations.
The correct approach involves enabling headers or footers in the DOMPDF instance and defining a callback function. You cannot place a static page number string in the footer of your main HTML unless you manually calculate the total pages beforehand, which is rarely practical for dynamic documents. Instead, you define a PHP callable that dompdf invokes for every single page.
Here is how you should configure the DOMPDF instance to handle this:
$dompdf = new DOMPDF();
$dompdf->set_option('isHtml5ParserEnabled', true);
$dompdf->set_option('isChromiumFontHintingEnabled', false);
// Enable headers and footers
$dompdf->set_option('enableHeader', true);
$dompdf->set_option('enableFooter', true);
// Define the header/footer content
// Note: The $page variable is automatically available inside this function
$header_html = '<div style="font-size: 10px; text-align: right;">Page <span class="page"></span> of <span class="pages"></span></div>';
$footer_html = '<div style="font-size: 10px; text-align: center;">Page <span class="page"></span> of <span class="pages"></span></div>';
// Set the content using set_html() or load_html() depending on your setup
// If using load_html, you must pass a specific option to use a callback for headers/footers
$dompdf->set_option('defaultHeaderHtml', $header_html);
$dompdf->set_option('defaultFooterHtml', $footer_html);
// Alternatively, for more control over every page, set the content directly:
$dompdf->load_html($html, array('isRemoteEnabled' => false));
The critical distinction here is that the header and footer options expect a string of HTML that contains placeholders like <span class="page"></span>. The actual calculation of "Page 1", "Page 2", etc., happens internally by dompdf based on these markers. Your PHP script does not need to calculate the page count; dompdf does that automatically during the rendering process.
A common pitfall when using your custom getView() loader is trying to inject the calculation logic into the view file itself. Since the view returns a string, any PHP logic intended for dompdf must be handled via configuration options on the $dompdf object, not within the HTML string returned by getView().
If you require complex logic that differs per page type, you can still pass data to the footer using the defaultFooterHtml option by injecting a variable into the string before calling load_html. However, for standard pagination, relying on the built-in <span class="page"> and <span class="pages"> classes is the most robust method. It ensures that the PDF generator handles the layout logic rather than your application code, preventing rendering artifacts caused by manual page counting errors.
For projects requiring tighter integration between Laravel views and PDF generation, solutions like barryvdh/laravel-dompdf abstract some of these steps. They allow you to pass the view directly to the library, which then handles the necessary string extraction and DOMPDF configuration internally. While your current setup using a raw getView() function works for simple data injection, adding PDF-specific features like headers and footers requires shifting that logic to the DOMPDF configuration layer rather than keeping it entirely within your custom view rendering function.