Page Labels Reading and specifying 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 SetaPDF_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 SetaPDF_Core_Document_Catalog_PageLabels::getPageLabelByPageNo (
integer $pageNo [, string $encoding = 'UTF-8' ]
): string

Get the page label by a page number/index.

Parameters
$pageNo : integer

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 SetaPDF_Core_SecHandler_Exception

Throws SetaPDF_Core_Type_Exception

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

PHP
<?php
require_once('library/SetaPDF/Autoload.php');

echo '<pre>';

$document = \SetaPDF_Core_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 SetaPDF_Core_Document_Catalog_PageLabels::addRange (
integer $startPage [, string $style = null [, string $prefix = '' [, integer $firstPageValue = 1 [, string $encoding = 'UTF-8' ]]]]
): void

Add a page label range.

Parameters
$startPage : integer

The page index to start the page label range

$style : string

The page label style. See SetaPDF_Core_Document_Catalog_PageLabels::STYLE_XXX constants

$prefix : string

A page label prefix

$firstPageValue : integer

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

$encoding : string

The input encoding

Exceptions

Throws SetaPDF_Core_DataStructure_Tree_KeyAlreadyExistsException

Throws SetaPDF_Core_SecHandler_Exception

Throws SetaPDF_Core_Type_Exception

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

PHP
<?php
require_once('library/SetaPDF/Autoload.php');

$writer = new \SetaPDF_Core_Writer_Http('page-labels.pdf', true);
$document = new \SetaPDF_Core_Document($writer);

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

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

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

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

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

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

// save the document
$document->save()->finish();