tc-lib-pdf-page

Overview

tc-lib-pdf-page keeps the page stack of a PDF document and writes out the page tree, the page objects, and the content streams.

Page size, orientation, boxes, and margins are resolved here rather than in the document builder, which is what keeps multi-page layout rules consistent across a document.

Repository and API Docs

• GitHub: https://github.com/tecnickcom/tc-lib-pdf-page
• API docs: https://tcpdf.org/docs/srcdoc/tc-lib-pdf-page
• Packagist: https://packagist.org/packages/tecnickcom/tc-lib-pdf-page

Project Metadata

Installation

composer require tecnickcom/tc-lib-pdf-page

Where It Fits

Print-bound work, mainly, where trim and bleed have to be exact, and any document whose pagination is more involved than one page after another.

Features

Page Model

• Named page formats (ISO, ANSI, JIS, envelopes, photographic and other series) and custom sizes
• Portrait, landscape and size-derived orientation
• Conversion between points, millimeters, centimeters and inches
• MediaBox, CropBox, BleedBox, TrimBox and ArtBox, each with its BoxColorInfo guidelines
• Page, header, content and footer margins, with mirrored gutters in booklet mode
• Writable regions: equal columns, or rectangles computed around no-write areas

Page Stack

• Add, clone, move, delete and select pages, grouped for per-group numbering
• Page content stack with marks, and ~#PN / ~#PT page number aliases
• Annotation references, rotation, preferred zoom and page transitions
• PDF output with optional Flate compression and encryption

Selecting Which Boxes Are Emitted

ISO 15930 allows a page to declare a TrimBox or an ArtBox, not both. omitPageBox() excludes a box from the page dictionary and keepPageBox() restores it; both take a box name or a PageBoxType case. The MediaBox is required, so omitting it raises an exception. getBoxColorInfo() skips the boxes that are no longer in the dictionary.

use Com\Tecnick\Pdf\Page\PageBoxType;

$page->omitPageBox(PageBoxType::ArtBox);
$page->keepPageBox('ArtBox');

Normalization and Limits

• Box corners are normalized and ordered, and every box is clamped inside the MediaBox at output time. setPagePWidth() and setPagePHeight() validate a positive size, resize the boxes and orientation, and stay reversible: getPage()['box'] reports the declared coordinates, and the intersection with the MediaBox is applied only to the emitted output.
• addAnnotRef() ignores an object ID below 1 and never stores the same reference twice.
• A partial BoxColorInfo is completed with defaults, and the box chain is completed from the MediaBox format.
• Page rotation is normalized to [0, 360) and a fractional multiple of 90 is rejected; the zoom is forced positive and transition entries are pruned per style.
• The number of regions bands and of columns are capped (Region::MAX_BANDS and Settings::MAX_COLUMNS, both 1000).
• An empty display mode resolves to UseNone.

Integration

• Supports PDF composition stacks that need deterministic page geometry
• Pairs with color/encryption libraries for complete page objects
• Typed exceptions for invalid layout parameters

No-Write Regions

Pages can declare rectangular regions that text and HTML flow must avoid, so content wraps around reserved areas such as pre-printed letterhead zones or fixed graphics. The feature is driven from tc-lib-pdf; see the runnable example /examples/E080_no_write_regions/.

Per-Page Transparency Group

setPageTransparencyGroupMode() controls whether the page transparency /Group is emitted:

The notransparency constructor argument overrides the mode entirely: no page carries a transparency group. It is set by the conformance modes that forbid transparency (PDF/A-1, PDF/X-1a, PDF/X-3).

Typed Enums

Every affected parameter is declared as a string|Enum union, so existing string-based code keeps working:

use Com\Tecnick\Pdf\Page\PageBoxType;
use Com\Tecnick\Pdf\Page\TransparencyGroupMode;

$dims = $page->setBox([], PageBoxType::CropBox, 0, 0, 210, 297);
$page->setPageTransparencyGroupMode(TransparencyGroupMode::Auto);

Integration Notes

Keep the page geometry in one place. Once margins and box offsets are spread across templates as literals, a change of stock or of printer means hunting for them.

Test print layouts against the settings the job will actually run with. A trim box that looks right on screen can still be a millimetre off on the press.

Default Page Formats

The library defines 387 default page formats in 29 groups (from Format::FORMAT).

• ISO 216 A Series + 2 SIS 014711 extensions
  • A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12
• ISO 216 B Series + 2 SIS 014711 extensions
  • B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, B11, B12
• ISO 216 C Series + 2 SIS 014711 extensions + 5 EXTENSION
  • C0, C1, C2, C3, C4, C5, C6, C7, C8, C9, C10, C11, C12, C76, DL, DLE, DLX, DLP
• SIS 014711 E Series
  • E0, E1, E2, E3, E4, E5, E6, E7, E8, E9, E10, E11, E12
• SIS 014711 G Series
  • G0, G1, G2, G3, G4, G5, G6, G7, G8, G9, G10, G11, G12
• ISO Press
  • RA0, RA1, RA2, RA3, RA4, SRA0, SRA1, SRA2, SRA3, SRA4
• German DIN 476
  • 4A0, 2A0
• Variations on the ISO Standard
  • A2_EXTRA, A3+, A3_EXTRA, A3_SUPER, SUPER_A3, A4_EXTRA, A4_SUPER, SUPER_A4, A4_LONG, F4, SO_B5_EXTRA, A5_EXTRA
• ANSI Series
  • ANSI_E, ANSI_D, ANSI_C, ANSI_B, ANSI_A
• Traditional ‘Loose’ North American Paper Sizes
  • USLEDGER, LEDGER, ORGANIZERK, BIBLE, USTABLOID, TABLOID, ORGANIZERM, USLETTER, LETTER, USLEGAL, LEGAL, GOVERNMENTLETTER, GLETTER, JUNIORLEGAL, JLEGAL
• Other North American Paper Sizes
  • QUADDEMY, SUPER_B, QUARTO, GOVERNMENTLEGAL, FOLIO, MONARCH, EXECUTIVE, ORGANIZERL, STATEMENT, MEMO, FOOLSCAP, COMPACT, ORGANIZERJ
• Canadian standard CAN 2-9.60M
  • P1, P2, P3, P4, P5, P6
• North American Architectural Sizes
  • ARCH_E, ARCH_E1, ARCH_D, BROADSHEET, ARCH_C, ARCH_B, ARCH_A
• North American Envelope Sizes
  • Announcement Envelopes: ANNENV_A2, ANNENV_A6, ANNENV_A7, ANNENV_A8, ANNENV_A10, ANNENV_SLIM
  • Commercial Envelopes: COMMENV_N6_1/4, COMMENV_N6_3/4, COMMENV_N8, COMMENV_N9, COMMENV_N10, COMMENV_N11, COMMENV_N12, COMMENV_N14
  • Catalogue Envelopes: CATENV_N1, CATENV_N1_3/4, CATENV_N2, CATENV_N3, CATENV_N6, CATENV_N7, CATENV_N8, CATENV_N9_1/2, CATENV_N9_3/4, CATENV_N10_1/2, CATENV_N12_1/2, CATENV_N13_1/2, CATENV_N14_1/4, CATENV_N14_1/2
• Japanese (JIS P 0138-61) Standard B-Series
  • JIS_B0, JIS_B1, JIS_B2, JIS_B3, JIS_B4, JIS_B5, JIS_B6, JIS_B7, JIS_B8, JIS_B9, JIS_B10, JIS_B11, JIS_B12
• PA Series
  • PA0, PA1, PA2, PA3, PA4, PA5, PA6, PA7, PA8, PA9, PA10
• Standard Photographic Print Sizes
  • PASSPORT_PHOTO, E, L, 3R, KG, 4R, 4D, 2L, 5R, 8P, 6R, 6P, 8R, 6PW, S8R, 4P, 10R, 4PW, S10R, 11R, S11R, 12R, S12R
• Common Newspaper Sizes
  • NEWSPAPER_BROADSHEET, NEWSPAPER_BERLINER, NEWSPAPER_TABLOID, NEWSPAPER_COMPACT
• Business Cards
  • CREDIT_CARD, BUSINESS_CARD, BUSINESS_CARD_ISO7810, BUSINESS_CARD_ISO216, BUSINESS_CARD_IT, BUSINESS_CARD_UK, BUSINESS_CARD_FR, BUSINESS_CARD_DE, BUSINESS_CARD_ES, BUSINESS_CARD_CA, BUSINESS_CARD_US, BUSINESS_CARD_JP, BUSINESS_CARD_HK, BUSINESS_CARD_AU, BUSINESS_CARD_DK, BUSINESS_CARD_SE, BUSINESS_CARD_RU, BUSINESS_CARD_CZ, BUSINESS_CARD_FI, BUSINESS_CARD_HU, BUSINESS_CARD_IL
• Billboards
  • 4SHEET, 6SHEET, 12SHEET, 16SHEET, 32SHEET, 48SHEET, 64SHEET, 96SHEET
• Old European Sizes
  • Old Imperial English Sizes: EN_EMPEROR, EN_ANTIQUARIAN, EN_GRAND_EAGLE, EN_DOUBLE_ELEPHANT, EN_ATLAS, EN_COLOMBIER, EN_ELEPHANT, EN_DOUBLE_DEMY, EN_IMPERIAL, EN_PRINCESS, EN_CARTRIDGE, EN_DOUBLE_LARGE_POST, EN_ROYAL, EN_SHEET, EN_HALF_POST, EN_SUPER_ROYAL, EN_DOUBLE_POST, EN_MEDIUM, EN_DEMY, EN_LARGE_POST, EN_COPY_DRAUGHT, EN_POST, EN_CROWN, EN_PINCHED_POST, EN_BRIEF, EN_FOOLSCAP, EN_SMALL_FOOLSCAP, EN_POTT
  • Old Imperial Belgian Sizes: BE_GRAND_AIGLE, BE_COLOMBIER, BE_DOUBLE_CARRE, BE_ELEPHANT, BE_PETIT_AIGLE, BE_GRAND_JESUS, BE_JESUS, BE_RAISIN, BE_GRAND_MEDIAN, BE_DOUBLE_POSTE, BE_COQUILLE, BE_PETIT_MEDIAN, BE_RUCHE, BE_PROPATRIA, BE_LYS, BE_POT, BE_ROSETTE
  • Old Imperial French Sizes: FR_UNIVERS, FR_DOUBLE_COLOMBIER, FR_GRANDE_MONDE, FR_DOUBLE_SOLEIL, FR_DOUBLE_JESUS, FR_GRAND_AIGLE, FR_PETIT_AIGLE, FR_DOUBLE_RAISIN, FR_JOURNAL, FR_COLOMBIER_AFFICHE, FR_DOUBLE_CAVALIER, FR_CLOCHE, FR_SOLEIL, FR_DOUBLE_CARRE, FR_DOUBLE_COQUILLE, FR_JESUS, FR_RAISIN, FR_CAVALIER, FR_DOUBLE_COURONNE, FR_CARRE, FR_COQUILLE, FR_DOUBLE_TELLIERE, FR_DOUBLE_CLOCHE, FR_DOUBLE_POT, FR_ECU, FR_COURONNE, FR_TELLIERE, FR_POT
• Colombian Sizes
  • CO_CARTA, CO_EXTRA_TABLOIDE, CO_OFICIO, CO_PLIEGO, CO_PLIEGO2, CO_PLIEGO4, CO_PLIEGO8
• Japanese Sizes
  • JP_AB_BAN, JP_AIBAN, JP_A_KO_BAN, JP_B_KO_BAN, JP_CHOUBO_BAN, JP_CHUBAN, JP_CHU_TANZAKU, JP_DAI OBAN, JP_EBANKIRI, JP_FUURUSU_KO_BAN, JP_GAYOUSHI, JP_HASHIRE_E, JP_HATORON_BAN, JP_HOM_BAN, JP_HOSOBAN, JP_JIS_A_BAN, JP_JIS_B_BAN, JP_KAKEMONO_E, JP_KAKUBAN, JP_KAKU_SURIMONO, JP_KENTO_BAN, JP_KIKU_BAN, JP_KIKU_BAN4, JP_KIKU_BAN5, JP_KIKU_BAN5_OLD, JP_KIKU_BAN_A20_DORI, JP_KOBAN, JP_KO_BAN_B6, JP_KO_TANZAKU, JP_MOKUTANSHI, JP_NAGA_BAN, JP_OBAN, JP_OGATA_CHUBAN, JP_O_HOSOBAN, JP_POSTCARD, JP_SANGO_BAN, JP_SANGO_BAN_A48_DORI, JP_SANGO_BAN_B20_DORI, JP_SANGO_BAN_B36_DORI, JP_SANGO_BAN_B40_DORI, JP_SANROKU_BAN_B48_DORI, JP_SANSAN_BAN, JP_SANSHI_BAN, JP_SHIKISHIBAN, JP_SHIMBUNYOUSHI, JP_SHINSHO_BAN_B40_A, JP_SHINSHO_BAN_B40_B, JP_SHIROKU_BAN, JP_SHIROKU_BAN4, JP_SHIROKU_BAN5, JP_SHIROKU_BAN5_OLD, JP_SHIROKU_BAN6, JP_SHO_TANZAKU, JP_SUITORISHI, JP_TANZAKU, JP_TSUYA_GAMI, JP_UCHIWA, JP_WAIDO_BAN, JP_YATSUGIRI_BAN

Requirements

• PHP 8.2 or later
• Extension: zlib
• Package dependencies: tecnickcom/tc-lib-color, tecnickcom/tc-lib-pdf-encrypt
• Composer

Example

<?php

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

$page = new \Com\Tecnick\Pdf\Page\Page(
	'mm',
	new \Com\Tecnick\Color\Pdf(),
	new \Com\Tecnick\Pdf\Encrypt\Encrypt(false),
);

$page->add([
	'format' => 'A4',
	'orientation' => 'P',
	'margin' => ['PL' => 20, 'PR' => 20, 'PT' => 15, 'PB' => 15],
	'columns' => 2,
]);

$page->addContent('BT /F1 12 Tf 100 700 Td (Page ~#PN of ~#PT) Tj ET');

$pon = 0;
$pdfpages = $page->getPdfPages($pon);

add() returns the sanitized page data: the boxes in points, the normalized margins and the writable regions. getPdfPages() returns the PDF objects of the whole stack and advances $pon past the last object number it used.

Development and Packaging

• QA and local checks: make deps, make help, make qa
• Coverage report: make qa-coverage
• Packaging: make rpm, make deb

Support and Contribution

• Sponsor: https://github.com/sponsors/tecnickcom
• Contribution guide: https://github.com/tecnickcom/tc-lib-pdf-page/blob/main/CONTRIBUTING.md
• Security policy: https://github.com/tecnickcom/tc-lib-pdf-page/blob/main/SECURITY.md