Index

  1. Installation
  2. Getting Started
  3. Memory Usage
  4. Readers and Writers
  5. The Document Class
  6. Metadata
  7. Pages
  8. Canvas
  9. Page Layout and Mode
  10. Viewer Preferences
  11. Document Outline
  12. Page Labels
    1. Introduction
    2. Handling Page Labels of Existing Documents
    3. Define Page Labels
  13. Actions
  14. Destinations
  15. Annotations
  16. Embedded File Streams
  17. Colors and Color Spaces
  18. Page Formats and Boundaries
  19. Standard and Public Key Encryption
  20. Fonts and Encodings
  21. Corrupted Documents
  22. Reader Enabled Documents
  23. Migrating
  24. API Reference

Page Labels Reading and specifying page labels

Table of Contents

  1. Introduction
    1. Handling Page Labels of Existing Documents
      1. Define Page Labels

        Introduction

        A page in a PDF document could be identified by its page index that expresses the page's relative position within the document. Furthermore it is possible to optionally define page labels to identify a page visually on screen or in print.

        Let's say you have a document index spreading over 3 pages while the first content pages should start with 1. With page labels the numbering could be restarted at the first content page. It is also possible to define a prefix and the numbering style (decimal, roman,...) for page labels.

        A documents page labels are structured in labelling ranges. Each range is a series of consecutive pages using the same numbering system.

        Handling Page Labels of Existing Documents

        The handling of page labels is possible through the \setasign\SetaPDF2\Core\Document\Catalog\PageLabels class. To get access to an instance the SetaPDF-Core component offers a helper method on the catalog instance of a document: 

        PHP
        $pageLabels = $document->getCatalog()->getPageLabels();

        To translate a page index to a page label defined in the document the class offers a simple helper method: 

        Description
        public \setasign\SetaPDF2\Core\Document\Catalog\PageLabels::getPageLabelByPageNo (
        int $pageNo,
        string $encoding = 'UTF-8'
        ): string

        Get the page label by a page number/index.

        Parameters
        $pageNo : int

        The page number/index to get the page label for

        $encoding : string

        The output encoding

        Return Values

        Returns the page label for the specific page number/index

        Exceptions

        Throws \setasign\SetaPDF2\Core\SecHandler\Exception

        Throws \setasign\SetaPDF2\Core\Type\Exception

        Following example will simply extract the page labels of an existing document: 

        PHP
        <?php

use setasign\SetaPDF2\Core\Document;

require_once('library/SetaPDF/Autoload.php');

echo '<pre>';

$document = Document::loadByFilename('files/pdfs/Brand-Guide.pdf');

$pages = $document->getCatalog()->getPages();
$pageLabels = $document->getCatalog()->getPageLabels();

for ($i = 1; $i <= $pages->count(); $i++) {
    echo 'Page Index: ' . $i . ' -> Page Label: ' . $pageLabels->getPageLabelByPageNo($i) . "\n";
}

echo '</pre>';

        Define Page Labels

        Beside interpreting page labels of existing PDF documents the SetaPDF-Core component allows you to specify individual page range in new or existing PDF documents.

        To add a page label range the class offers following method: 

        Description
        public \setasign\SetaPDF2\Core\Document\Catalog\PageLabels::addRange (
        int $startPage,
        string $style = null,
        string $prefix = '',
        int $firstPageValue = 1,
        string $encoding = 'UTF-8'
        ): void

        Add a page label range.

        Parameters
        $startPage : int

        The page index to start the page label range

        $style : string

        The page label style. See \setasign\SetaPDF2\Core\Document\Catalog\PageLabels::STYLE_XXX constants

        $prefix : string

        A page label prefix

        $firstPageValue : int

        The value of the numeric portion for the first page in the range

        $encoding : string

        The input encoding

        Exceptions

        Throws \setasign\SetaPDF2\Core\DataStructure\Tree\KeyAlreadyExistsException

        Throws \setasign\SetaPDF2\Core\SecHandler\Exception

        Throws \setasign\SetaPDF2\Core\Type\Exception

        Following PHP script will add several page label ranges to a new document with 100 blank pages: 

        PHP
        <?php

use setasign\SetaPDF2\Core\Document;
use setasign\SetaPDF2\Core\PageFormats;
use setasign\SetaPDF2\Core\Writer\HttpWriter;

require_once('library/SetaPDF/Autoload.php');

$writer = new HttpWriter('page-labels.pdf', true);
$document = new Document($writer);

// let's create dummy pages
$pages = $document->getCatalog()->getPages();
for ($i = 0; $i < 100; $i++) {
    $pages->create(PageFormats::A4);
}

// get the page label helper
$pageLabels = $document->getCatalog()->getPageLabels();

// Add a first page label range
$pageLabels->addRange(1, Document\Catalog\PageLabels::STYLE_UPPERCASE_LETTERS, 'Index-');

// Revert as of page 10 to normal page labeling
$pageLabels->addRange(10, Document\Catalog\PageLabels::STYLE_DECIMAL_NUMERALS);

// Restart labeling on page 90 with roman numerals and a prefix
$pageLabels->addRange(90, Document\Catalog\PageLabels::STYLE_UPPERCASE_ROMAN_NUMERALS, 'A-');

// let's define the page mode that shows the document thumbnails panel
$document->getCatalog()->setPageMode(Document\PageMode::USE_THUMBS);

// save the document
$document->save()->finish();
        © 2025 Setasign GmbH & Co. KG · Contact / Imprint · Data Privacy Statement (German)