Viewer Preferences

Viewer Preferences

Store hints in the document catalog that tell the PDF viewer how to present the document when it is first opened. Three independent setters control the page layout, the side panel shown, and the initial zoom destination. All are optional and all accept null to clear a previously set value.

use DragonOfMercy\PhpPdf\Document;
use DragonOfMercy\PhpPdf\OpenAction;
use DragonOfMercy\PhpPdf\PageLayout;
use DragonOfMercy\PhpPdf\PageMode;

$pdf = new Document();
$pdf->setPageLayout(PageLayout::TWO_COLUMN_RIGHT)
    ->setPageMode(PageMode::USE_OUTLINES)
    ->setOpenAction(OpenAction::fitWidth(top: 0));

PageLayout

Controls how the viewer arranges pages.

Case	PDF value	Description
PageLayout::SINGLE_PAGE	SinglePage	One page visible at a time (default).
PageLayout::ONE_COLUMN	OneColumn	Continuous single-column scroll.
PageLayout::TWO_COLUMN_LEFT	TwoColumnLeft	Continuous two-column scroll, odd pages on the left.
PageLayout::TWO_COLUMN_RIGHT	TwoColumnRight	Continuous two-column scroll, odd pages on the right (book/magazine order).
PageLayout::TWO_PAGE_LEFT	TwoPageLeft	Two pages per screen, odd pages on the left.
PageLayout::TWO_PAGE_RIGHT	TwoPageRight	Two pages per screen, odd pages on the right.

Pass null to clear: $pdf->setPageLayout(null).

PageMode

Controls which side panel (if any) the viewer opens.

Case	PDF value	Description
PageMode::USE_NONE	UseNone	No side panel (default).
PageMode::USE_OUTLINES	UseOutlines	Bookmarks (outline) panel open.
PageMode::USE_THUMBS	UseThumbs	Page thumbnails panel open.
PageMode::FULL_SCREEN	FullScreen	Launch in full-screen mode (hint only - many browser viewers ignore this).
PageMode::USE_OC	UseOC	Optional-content (layers) panel open. Only meaningful when the document has OC groups.
PageMode::USE_ATTACHMENTS	UseAttachments	Attachments panel open. Only meaningful when the document has file attachments.

Pass null to clear: $pdf->setPageMode(null).

OpenAction

Sets the initial view when the document is opened. Pages are 1-indexed (page 1 is the default). Coordinates use the document's unit and the top-down Y axis (consistent with the rest of the API).

OpenAction::fit($page);                                // entire page fits in the viewport
OpenAction::fitWidth($page, top: 50);                  // page width fills viewport, top edge at 50 mm from the page top
OpenAction::fitHeight($page, left: 0);                 // page height fills viewport
OpenAction::zoom($page, left: 10, top: 20, zoom: 1.5); // top-left at (10, 20) mm, zoomed 150%
OpenAction::actualSize($page);                         // 100% zoom anchored at the page top-left

Named constructors

Constructor	Parameters	Description
OpenAction::fit(int $page = 1)	1-indexed page	Fit the entire page in the viewport.
OpenAction::fitWidth(int $page = 1, ?float $top = null)	top in document unit, null = page top	Fit page width; scroll so $top is at the viewport top.
OpenAction::fitHeight(int $page = 1, ?float $left = null)	left in document unit, null = page left	Fit page height; scroll so $left is at the viewport left.
OpenAction::zoom(int $page = 1, float $left = 0.0, float $top = 0.0, float $zoom = 1.0)	coordinates and zoom factor (1.0 = 100%, 0 = keep current)	Arbitrary top-left corner and zoom.
OpenAction::actualSize(int $page = 1)	1-indexed page	100% zoom anchored at the page top-left.

Pass null to clear: $pdf->setOpenAction(null).

Compatibility note

Acrobat respects all of these hints faithfully. Browser-based viewers (Chrome built-in, Firefox PDF.js) honour layout and mode hints partially and typically ignore FullScreen mode. Always test the relevant viewers when viewer preferences are critical to the user experience.

See also

• Bookmarks and Hyperlinks