The Main Class

Index

The Main Class

Introduction
Get an Instance
Adding Stamp Objects
Stamping the Stamp Objects

Introduction

As any other SetaPDF component the Stamper is represented by a main class: The \setasign\SetaPDF2\Stamper\Stamper class.

It is the midsection of the stamp workflow. It collects the stamp instances and will process them as they are configured by its stamp() or stampPageNo() methods.

Get an Instance

A class instance can be simply created by passing a document instance, that will get stamped, to its constructor.

Reading and writing the PDF document is up to the Core component. This way it is possible to work on the document instance further.

Adding Stamp Objects

A stamp object could be seen as a kind of content, that should get added onto a specific or several page. It doesn't "know" about its position or rotation on a page but all this can be defined while adding it to the stamper instance.

A stamp object can be added several times to a stamper instance. All this is done with the addStamp() method:

Description

public \setasign\SetaPDF2\Stamper\Stamper::addStamp (

\SetaPDF_Stamper_Stamp $stamp,
string|array $positionOrConfig = \setasign\SetaPDF2\Stamper\Stamper ::POSITION_LEFT_TOP,
int|string|array|callback $showOnPage = \setasign\SetaPDF2\Stamper\Stamper ::PAGES_ALL,
int $translateX = 0,
int $translateY = 0,
float $rotation = 0.0,
bool $underlay = false,
?callback $callback = null

): void

Adds a stamp object to the stamper instance.

Parameters

$stamp : \SetaPDF_Stamper_Stamp

Stamp object which shall be stamped on the document

$positionOrConfig : string|array

Position or array of configuration variables

$showOnPage : int|string|array|callback

The configuration defining on which pages the stamp shall be shown. Possible values are:

PAGES_XXX constant
Integer with the valid page number
String with the valid page number or the valid range (e.g. '10-12')
Array with all valid page numbers
Callback with the arguments (int $pageNumber, int $pageCount)

$translateX : int

Move the stamp on x-axis by $translateX

$translateY : int

Move the stamp on y-axis by $translateX

$rotation : float

Rotate the stamp by $rotation degrees

$underlay : bool

Defines whether the stamp should be place before or after the existing content

$callback : ?callback

Callback which will be called every time before the document will be stamped by this stamp if it's not returning true the stamp will not stamped on this run.

The addStamp() method can be called in 2 ways: By its parameter or with a config array which keys are named as the method parameters:

PHP

$stamper->addStamp(
    $stamp, 
    \setasign\SetaPDF2\Stamper\Stamper::POSITION_RIGHT_TOP, 
    \setasign\SetaPDF2\Stamper\Stamper::PAGES_LAST,
    -10,
    -10
);

// or

$stamper->addStamp(
    $stamp,
    array(
        'position' => \setasign\SetaPDF2\Stamper\Stamper::POSITION_RIGHT_TOP,
        'showOnPage' => \setasign\SetaPDF2\Stamper\Stamper::PAGES_LAST,
        'translateX' => -10,
        'translateY' => -10
    )
);

Positioning

The exact position of a stamp is a combination of the $position and $translateX/Y parameters.

The $position parameter shall be a value of a predefined constant (see \setasign\SetaPDF2\Stamper\Stamper::POSITION_XXX) that define the "starting position". The stamp can be positioned further by the $translateX and $translateY parameters. The origin of the coordinate system is the lower left corner of a page.

The constants are self-explanatory by their names but they can also be checked with the checkPositionParameter() method. It will return true on success or throw an \InvalidArgumentException instead.

public const string \setasign\SetaPDF2\Stamper\Stamper::POSITION_CENTER_BOTTOM = 'CB'

Position constant

public const string \setasign\SetaPDF2\Stamper\Stamper::POSITION_CENTER_MIDDLE = 'CM'

Position constant

public const string \setasign\SetaPDF2\Stamper\Stamper::POSITION_CENTER_TOP = 'CT'

Position constant

public const string \setasign\SetaPDF2\Stamper\Stamper::POSITION_LEFT_BOTTOM = 'LB'

Position constant

public const string \setasign\SetaPDF2\Stamper\Stamper::POSITION_LEFT_MIDDLE = 'LM'

Position constant

public const string \setasign\SetaPDF2\Stamper\Stamper::POSITION_LEFT_TOP = 'LT'

Position constant

public const string \setasign\SetaPDF2\Stamper\Stamper::POSITION_RIGHT_BOTTOM = 'RB'

Position constant

public const string \setasign\SetaPDF2\Stamper\Stamper::POSITION_RIGHT_MIDDLE = 'RM'

Position constant

public const string \setasign\SetaPDF2\Stamper\Stamper::POSITION_RIGHT_TOP = 'RT'

Position constant

A simple example:

PHP

<?php

use setasign\SetaPDF2\Core\Document;
use setasign\SetaPDF2\Core\Font\Standard\Helvetica;
use setasign\SetaPDF2\Core\PageFormats;
use setasign\SetaPDF2\Core\Text\Text;
use setasign\SetaPDF2\Core\Writer\HttpWriter;
use setasign\SetaPDF2\Stamper\Stamp\TextStamp;
use setasign\SetaPDF2\Stamper\Stamper;

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

// create a writer
$writer = new HttpWriter('positioning.pdf', true);
// we create a fresh document instance for demonstration purpose
$document = new Document($writer);
// create at least one page
$document->getCatalog()->getPages()->create(PageFormats::A4);

// create a stamper instance
$stamper = new Stamper($document);

// create a font object
$font = Helvetica::create($document);

// create simple text stamp
$stamp = new TextStamp($font, 12);
$stamp->setBorderWidth(1);
$stamp->setPadding(4);
$stamp->setAlign(Text::ALIGN_CENTER);
$stamp->setText("Positioning\nDemo");

// default position: left top
$stamper->addStamp($stamp, [
    'translateX' => 10,
    'translateY' => -10,
]);

// right top
$stamper->addStamp($stamp, [
    'position' => Stamper::POSITION_RIGHT_TOP,
    'translateX' => -10,
    'translateY' => -10,
]);

// right bottom
$stamper->addStamp($stamp, [
    'position' => Stamper::POSITION_RIGHT_BOTTOM,
    'translateX' => -10,
    'translateY' => 10,
]);

// left bottom
$stamper->addStamp($stamp, [
    'position' => Stamper::POSITION_LEFT_BOTTOM,
    'translateX' => 10,
    'translateY' => 10,
]);

// center
$stamper->addStamp($stamp, Stamper::POSITION_CENTER_MIDDLE);

// stamp the document
$stamper->stamp();

// show the whole page at opening time
$document->getCatalog()->setPageLayout(Document\PageLayout::SINGLE_PAGE);

// save and send it to the client
$document->save()->finish();

 Code
 Run

Show on Page

The $showOnPage parameter accepts various values defining the page or pages to show the stamp on. E.g. it allows you to pass following constants:

public const string \setasign\SetaPDF2\Stamper\Stamper::PAGES_ALL = 'all'

Page constant

public const string \setasign\SetaPDF2\Stamper\Stamper::PAGES_EVEN = 'even'

Page constant

public const string \setasign\SetaPDF2\Stamper\Stamper::PAGES_FIRST = 'first'

Page constant

public const string \setasign\SetaPDF2\Stamper\Stamper::PAGES_LAST = 'last'

Page constant

public const string \setasign\SetaPDF2\Stamper\Stamper::PAGES_ODD = 'odd'

Page constant

Additionally it allows you pass an integer, an array of integers, a range, defined as a string or a callback:

PHP

// constants
$showOnPage = \setasign\SetaPDF2\Stamper\Stamper::PAGES_EVEN;
$showOnPage = \setasign\SetaPDF2\Stamper\Stamper::PAGES_ODD;
$showOnPage = \setasign\SetaPDF2\Stamper\Stamper::PAGES_LAST;

// integer values
$showOnPage = 1;
$showOnPage = 3;

// array of integers
$showOnPage = [1, 3, 5];

// range
$showOnPage = '2-'; // stamp 2nd to last page
$showOnPage = '3-5'; // stamp 3rd to 5th page

// callback to stamp the second last page
$showOnPage = function($pageNumber, $pageCount) {
    return $pageNumber === ($pageCount - 1);
}

You can check this parameter with the checkShowOnPageParameter() method. It returns true on success or may throw an InvalidArgumentException exception if the argument is not a valid $showOnPage parameter.

Rotation

It is possible to define a rotation when you add a stamp to the stamper instance. The rotation origin is always the center of the stamp appearance. Additionally the stamp will be moved into the viewable area:

PHP

<?php

use setasign\SetaPDF2\Core\Document;
use setasign\SetaPDF2\Core\Font\Standard\Helvetica;
use setasign\SetaPDF2\Core\PageFormats;
use setasign\SetaPDF2\Core\Text\Text;
use setasign\SetaPDF2\Core\Writer\HttpWriter;
use setasign\SetaPDF2\Stamper\Stamp\TextStamp;
use setasign\SetaPDF2\Stamper\Stamper;

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

// create a writer
$writer = new HttpWriter('rotation.pdf', true);
// we create a fresh document instance for demonstration purpose
$document = new Document($writer);
// create at least one page
$document->getCatalog()->getPages()->create(PageFormats::A4);

// create a stamper instance
$stamper = new Stamper($document);

// create a font object
$font = Helvetica::create($document);

// create simple text stamp
$stamp = new TextStamp($font, 30);
$stamp->setBorderWidth(1);
$stamp->setPadding(4);
$stamp->setAlign(Text::ALIGN_CENTER);
$stamp->setText("Rotation\nDemo");

// left top with 45 degrees rotation
$stamper->addStamp($stamp, [
    'rotation' => 45
]);

// right top with 90 degrees rotation
$stamper->addStamp($stamp, [
    'position' => Stamper::POSITION_RIGHT_TOP,
    'rotation' => 90
]);

// stamp the document
$stamper->stamp();

// show the whole page at opening time
$document->getCatalog()->setPageLayout(Document\PageLayout::SINGLE_PAGE);

// save and send it to the client
$document->save()->finish();

 Code
 Run

Callback

A stamp object may display dynamic content like the current page number or its size may vary depending on the page size by defining a callback that will be called just before the stamp is done. This parameter could be passed to the $callback parameter of the addStamp() method.

PHP

<?php

use setasign\SetaPDF2\Core\Document;
use setasign\SetaPDF2\Core\Font\Standard\Helvetica;
use setasign\SetaPDF2\Core\PageFormats;
use setasign\SetaPDF2\Core\Text\Text;
use setasign\SetaPDF2\Core\Writer\HttpWriter;
use setasign\SetaPDF2\Stamper\Stamp\TextStamp;
use setasign\SetaPDF2\Stamper\Stamper;

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

// create a writer
$writer = new HttpWriter('callback.pdf', true);
// we create a fresh document instance for demonstration purpose
$document = new Document($writer);
// get the pages instance
$pages = $document->getCatalog()->getPages();
// create 20 pages
for ($i = 0; $i < 20; $i++) {
    $orientation = $i % 2
        ? PageFormats::ORIENTATION_LANDSCAPE
        : PageFormats::ORIENTATION_PORTRAIT;

    $pages->create(PageFormats::A4, $orientation);
}

// create a stamper instance
$stamper = new Stamper($document);

// create a font object
$font = Helvetica::create($document);

// create simple text stamp
$stamp = new TextStamp($font, 16);
$stamp->setPadding(4);
$stamp->setAlign(Text::ALIGN_RIGHT);

/**
 * @param $pageNumber The current page number that should be stamped
 * @param $pageCount The page count of the document
 * @param Document\Page $page The page instance of the current page
 * @param TextStamp $stamp The stamp object
 * @param array $currentStampData The data that were passed to the addStamp() method.
 *
 * @return bool
 */
$callback = function(
    $pageNumber,
    $pageCount,
    Document\Page $page,
    TextStamp $stamp,
    array &$currentStampData
) {
    // set the page number
    $stamp->setText('Page ' . $pageNumber . ' / ' . $pageCount);
    // increase the font size for demonstration purpose
    $stamp->setFontSize($stamp->getFontSize() + 2);

    // if the page is landscape we want to position the stamp on the lower left with a rotation of 45 degrees
    if ($page->getWidth() > $page->getHeight()) {
        $currentStampData['position'] = \SetaPDF_Stamper::POSITION_LEFT_BOTTOM;
        $currentStampData['rotation'] = 45;
    // otherwise lower right and a -45 degree rotation
    } else {
        $currentStampData['position'] = \SetaPDF_Stamper::POSITION_RIGHT_BOTTOM;
        $currentStampData['rotation'] = -45;
    }

    return true;
};

// right bottom and callback
$stamper->addStamp($stamp, [
    'position' => Stamper::POSITION_RIGHT_BOTTOM,
    'callback' => $callback
]);

// stamp the document
$stamper->stamp();

// show the whole page at opening time
$document->getCatalog()->setPageLayout(Document\PageLayout::SINGLE_PAGE);

// save and send it to the client
$document->save()->finish();

 Code
 Run

The callback has to return true if the stamp should be executed.

Stamping the Stamp Objects

As already seen in the previous examples the added stamps will get processed by calling the stamp() method.

If you've full control over the page numbers that should get stamped you could also use the stampPageNo() method.

Getting Started Stamp Types

SetaPDF-Stamper Manual

Index

The Main Class

Table of Contents

Introduction

Get an Instance

Adding Stamp Objects

Description

Parameters

Positioning

Show on Page

Rotation

Callback

Stamping the Stamp Objects