Set viewer preferences and display mode

At a glance

This recipe controls how a conforming Portable Document Format (PDF) reader presents your document when it opens. You set the initial zoom, page layout, reader controls, window size, and title-bar text. The title bar can show the document title or the filename. This recipe follows examples/24-viewer-preferences.php.

Install

composer require nextpdf/core:^3

Conceptual overview

Viewer preferences live in the document catalog. They are hints to the reader, not guarantees. Use the three main flags this way. DisplayDocTitle controls the title-bar text (ISO 32000-2 §12.2). HideToolbar asks the reader to hide its toolbar. FitWindow asks the reader to resize its window to fit the first page. setDisplayMode() pairs an initial zoom with a page layout.

The profile is structural because the document carries a trailer /ID value. The post-pass normalizes that value before it compares two runs.

API surface

NextPDF\Core\Concerns\HasViewerPreferences (mixed into Document):

setViewerPreferences(array $prefs): static — keyed flags such as HideToolbar, HideMenubar, HideWindowUI, FitWindow, CenterWindow, DisplayDocTitle (bool), plus Direction, PrintScaling, Duplex (string), NumCopies (int).
setDisplayMode(string $zoom = 'default', string $layout = 'SinglePage'): static — $zoom ∈ default | fullpage | fullwidth | real | <numeric>; $layout ∈ SinglePage | OneColumn | TwoColumnLeft | TwoColumnRight | TwoPageLeft | TwoPageRight.

Code sample — Quick start

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Presentation Deck');

$doc->setDisplayMode('fullwidth', 'TwoColumnLeft');
$doc->setViewerPreferences([
    'HideToolbar'     => true,
    'FitWindow'       => true,
    'DisplayDocTitle' => true,
]);

$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Opens full-width, two columns, title bar shows the title.', newLine: true);

$doc->save(__DIR__ . '/viewer-prefs.pdf');
echo "Wrote viewer-prefs.pdf\n";

Code sample — Production

The full example below mirrors examples/24-viewer-preferences.php. It creates a multi-page document so you can see the two-column layout, and it writes to NEXTPDF_COOKBOOK_OUTPUT for the harness.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Viewer Preferences Demo');
$doc->setAuthor('NextPDF Example');

$doc->setDisplayMode('fullwidth', 'TwoColumnLeft');
$doc->setViewerPreferences([
    'HideToolbar'     => true,
    'HideMenubar'     => true,
    'FitWindow'       => true,
    'CenterWindow'    => true,
    'DisplayDocTitle' => true,
]);

for ($page = 1; $page <= 3; $page++) {
    $doc->addPage();
    $doc->setFont('helvetica', 'B', 18);
    $doc->cell(0, 12, "Page {$page}", newLine: true);
    $doc->setFont('helvetica', '', 11);
    $doc->multiCell(0, 7, 'With TwoColumnLeft layout a conforming reader '
        . 'shows pages side by side. Toolbar and menu bar are hidden, the '
        . 'window fits the first page and is centred, and the title bar '
        . 'shows the document title rather than the filename.');
}

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/viewer-preferences.pdf');

echo "Wrote document with viewer preferences\n";

Expected output:

Wrote document with viewer preferences

Edge cases & gotchas

Preferences are advisory. ISO 32000-2 defines viewer preferences as hints. Readers may ignore any of them. Browsers in particular honor very few. Never rely on HideToolbar/HideMenubar for a security or kiosk guarantee.
DisplayDocTitle needs a title. It only changes behavior when setTitle() sets a non-empty title. Without a title, the reader still shows the filename.
Layout strings are exact. setDisplayMode() expects the spec spellings, such as TwoColumnLeft, not two-column-left. An unknown layout falls back to the reader default.
Numeric zoom is a string. Pass '150' for 150 %, not the integer 150.
Single page vs. spread. TwoPageLeft/TwoPageRight require PDF 1.5+ readers. Older viewers fall back to a single-column layout.

Performance

Setting viewer preferences is constant-time catalog configuration and has no rendering cost. It stays well inside the 1000 ms / 64 MB budget.

Security notes

Hiding the toolbar or menu bar is cosmetic. It does not restrict what the user can do. Every reader keeps keyboard shortcuts and right-click actions, and many ignore the flags entirely. Do not treat viewer preferences as a control that limits saving, printing, or copying. Permission bits handle those requests, and readers still only honor them cooperatively. See Encrypt with permissions.

Conformance

Statement	Spec	Clause
`DisplayDocTitle` controls whether the window title bar shows the document title.	ISO 32000-2	§12.2
`HideToolbar` requests that the interactive toolbar be hidden.	ISO 32000-2	§12.2
`FitWindow` requests that the window be resized to the first page.	ISO 32000-2	§12.2

These preferences are advisory. The cited clauses define their meaning. They do not define a reader’s obligation to honor them.